Home Original page

Using Phan From Command Line

Using Phan From the Command Line (Phan V6)

Complete reference for Phan v6 command-line flags, options, and usage patterns.

Quick Reference

# Basic analysis
phan

# Analysis with config file
phan --config-file .phan/config.php

# No config file (analyze provided files only)
phan -n file1.php file2.php

# Incremental analysis (faster re-runs)
phan --incremental

# Force full re-analysis
phan --force-full-analysis

# Save baseline for issue tracking
phan --save-baseline .phan/.baseline.php

# Analyze against baseline
phan --load-baseline .phan/.baseline.php

Core Flags

Configuration

--config-file <FILE> / -c

Specify the configuration file to use.

phan --config-file .phan/config.php
phan -c custom-config.php

-n / --no-config-file

New in V6: When used with file arguments, limits analysis to just the provided files (ignores the rest of the project).

# Quick analysis of specific files
phan -n src/User.php src/Product.php

# Without -n, would analyze entire configured project
phan src/User.php  # Analyzes entire project

This is useful for:

  • Quick checks during development
  • IDE integration
  • Focused analysis of specific modules

--project-root-directory <DIR>

Override the project root directory.

phan --project-root-directory /path/to/project

Incremental Analysis (V6)

Dramatically speeds up re-runs by only analyzing changed files.

--incremental / -i

Enable incremental analysis mode.

# First run - full analysis
phan --incremental
# Creates .phan/.phan-incremental.php manifest

# Subsequent runs - only changed files
phan --incremental
# Much faster!

New in V6: Previously -i was an alias for --ignore-undeclared. Now it's for --incremental.

--no-incremental / -N

Disable incremental analysis (useful if enabled in config).

--force-full-analysis

Force a complete re-analysis, ignoring the incremental manifest.

# After major changes or dependency updates
phan --force-full-analysis

--subdirectory-only

New in V6: Analyze only the current subdirectory with better performance.

cd src/Module/A
phan --subdirectory-only

Benefits:

  • Faster focused analysis
  • Still loads dependency information from full project
  • Useful for large monorepos

Baseline Management (V6)

Track issues over time without suppressing them in code.

--save-baseline <FILE>

Generate or update a baseline file.

# Create baseline
phan --save-baseline .phan/.baseline.php

# Update baseline after fixes
phan --save-baseline .phan/.baseline.php

The baseline records all current issues. On subsequent runs:

  • Only NEW issues are reported
  • Known issues are suppressed automatically
  • Allows gradual improvement over time

--load-baseline <FILE>

Use a previously saved baseline.

phan --load-baseline .phan/.baseline.php

Typically configured in config.php:

return [
    'load_baseline' => '.phan/.baseline.php',
];

--save-baseline-in-missing-files-only

Only save suppressions for files not yet analyzed.

phan --save-baseline-in-missing-files-only .phan/.baseline.php

Performance Tuning (V6)

--ast-trim-max-elements-per-level <N>

Limit array elements per level before summarization.

# Default: 256
phan --ast-trim-max-elements-per-level 512

Lower values = less memory, fewer accurate types Higher values = more memory, better accuracy

--ast-trim-max-total-elements <N>

Limit total elements in nested arrays.

# Default: 512
phan --ast-trim-max-total-elements 1024

--max-union-type-set-size <N>

Limit union type combinations.

# Default: 1024
phan --max-union-type-set-size 2048

When exceeded, types are intelligently merged to prevent runaway growth.

Output and Reporting

-j / --processes <NUM>

Number of parallel analysis processes.

# Use 4 processes
phan -j 4

# Use optimal for your CPU
phan -j $(nproc)

Default: number of CPU cores

-o / --output-mode <MODE>

Specify output format.

phan -o text           # Human-readable (default)
phan -o json           # JSON output
phan -o csv            # CSV format
phan -o checkstyle     # Checkstyle format (for CI)

-f / --output-file <FILE>

Write output to file instead of stdout.

phan -f analysis-results.txt
phan -o json -f results.json

--color

Enable colored output.

--no-color

Disable colored output.

-q / --quiet

Only show errors, no summary.

Issue Control

--issue-handlers <HANDLERS>

Specify how to handle specific issue types.

# Suppress specific issues
phan --issue-handlers PhanUnreferencedPublicMethod:suppress

# Warn on others
phan --issue-handlers PhanDeprecatedFunction:warn

--suppress-issue-type <TYPE>

Suppress a specific issue type globally.

phan --suppress-issue-type PhanUnreferencedPublicMethod

--show-suggestions

Show suggested fixes (if available).

Analysis Scope

--analyze-twice

Run analysis twice to catch more issues.

Slower but more thorough. Useful for complex codebases.

--skip-phpstan-baseline

Don't use phpstan baseline (if configured).

phan --skip-phpstan-baseline

PHP Version and Compatibility

--target-php-version <VERSION>

Set the PHP version to analyze for.

phan --target-php-version 8.2
phan --target-php-version 7.4

Default: version from config or current PHP version

--minimum-target-php-version <VERSION>

Phan v6: Specify minimum target version.

phan --minimum-target-php-version 8.0

Plugin Management

--load-plugins <PLUGINS>

Load specific plugins.

phan --load-plugins PregRegexPlugin,PHPDocPlugin

Multiple plugins separated by comma.

-i changed in V6

Breaking Change: The -i flag is now --incremental (not --ignore-undeclared).

# Old (v5)
phan -i  # Ignored undeclared variables

# New (v6)
phan -i  # Enables incremental analysis

Daemon Mode

--daemon

Run Phan in daemon mode.

# Start daemon
phan --daemon

# Request analysis
phan --daemon-request

For long-running processes with faster subsequent requests.

See Using-Phan-Daemon-Mode for details.

Version and Help

--version / -v

Display Phan version.

--help / -h

Display help message.

--extended-help

Display extended help with all options.

Common Usage Patterns

Pattern 1: Quick File Check

# Analyze specific file(s) without full project analysis
phan -n src/User.php

Pattern 2: IDE Integration

# Fast analysis for IDE/editor
phan -n "$FILE_PATH" --output-mode json

Pattern 3: CI/CD Pipeline

# Incremental analysis in CI
phan --incremental \
     --output-mode checkstyle \
     --output-file reports/phan.xml

Pattern 4: Baseline Improvement

# Create baseline
phan --save-baseline .phan/.baseline.php

# Run with baseline (only NEW issues reported)
phan --load-baseline .phan/.baseline.php

# Fix some issues, then update baseline
phan --save-baseline .phan/.baseline.php

Pattern 5: Performance Tuning

# For large codebases
phan --incremental \
     --processes 8 \
     --ast-trim-max-elements-per-level 512 \
     --max-union-type-set-size 2048

Pattern 6: Parallel Processing

# Use all CPU cores
phan -j $(nproc)

# Specific number of processes
phan -j 4

Exit Codes

# 0 - Analysis successful, no issues
phan; echo $?  # 0

# 1 - Analysis found issues
phan; echo $?  # 1

# 2 - Error during analysis
phan; echo $?  # 2

Use in scripts:

#!/bin/bash
phan
if [ $? -eq 0 ]; then
    echo "Analysis passed"
else
    echo "Analysis found issues"
    exit 1
fi

Environment Variables

PHAN_ALLOW_MISSING_PARAM_TYPE

Allow missing parameter type hints (v5 behavior).

PHAN_ALLOW_MISSING_PARAM_TYPE=1 phan

PHAN_DISABLE_XDEBUG

Disable XDebug for performance.

PHAN_DISABLE_XDEBUG=1 phan

Performance Monitoring

Check Memory Usage

# Monitor peak memory
/usr/bin/time -v phan

Measure Analysis Time

# Time the analysis
time phan

Profile with Different Settings

#!/bin/bash
echo "Performance comparison"
echo "====================="

echo -e "\nStandard analysis:"
time phan

echo -e "\nIncremental analysis:"
time phan --incremental

echo -e "\nParallel (8 processes):"
time phan -j 8

Troubleshooting

"Configuration file not found"

# Specify config file explicitly
phan --config-file .phan/config.php

# Or use no config
phan -n file.php

"Too many issues to display"

# Output to file instead
phan -f output.txt

# Or use quiet mode
phan -q

"Analysis is slow"

# Use incremental analysis
phan --incremental

# Use parallel processing
phan -j 8

# Reduce memory/accuracy tradeoff
phan --ast-trim-max-elements-per-level 128

"Inconsistent issues on different runs"

# Force full analysis
phan --force-full-analysis

Complete Example: CI/CD Pipeline

#!/bin/bash
set -e

echo "=== Phan Static Analysis ==="

# Install dependencies
composer install

# Create baseline on first run
if [ ! -f .phan/.baseline.php ]; then
    echo "Creating baseline..."
    phan --save-baseline .phan/.baseline.php
fi

# Run analysis
echo "Running analysis..."
phan \
    --load-baseline .phan/.baseline.php \
    --incremental \
    --processes 8 \
    --output-mode checkstyle \
    --output-file reports/phan.xml

# Check results
if [ $? -eq 0 ]; then
    echo "✓ Analysis passed"
else
    echo "✗ Analysis found issues"
    exit 1
fi

See Also