Phan - A Static Analyzer for PHP

Phan - A Static Analyzer for PHP

Phan is a static analyzer for PHP that prefers to minimize false-positives. It attempts to prove incorrectness rather than correctness.


It looks for common issues and will verify type compatibility on various operations when type information is available or can be deduced. Phan has a good (but not comprehensive) understanding of flow control and does not attempt to track values.

Features:

  • Check that all methods, functions, classes, traits, interfaces, constants, properties and variables are defined and accessible.
  • Check for type safety and arity issues on method/function/closure calls.
  • Check for PHP7/PHP5 backward compatibility.
  • Check for features that weren't supported in older PHP 7.x minor releases (E.g. object, void, iterable, ?T, [$x] = ...;, etc.)
  • Check for sanity with array accesses.
  • Check for type safety on binary operations.
  • Check for valid and type-safe return values on methods, functions, and closures.
  • Check for No-Ops on arrays, closures, constants, properties, variables, unary operators, and binary operators.
  • Check for unused/dead/unreachable code. (Pass in --dead-code-detection)
  • Check for unused use statements.
  • Check for classes, functions, and methods being redefined.
  • Check for sanity with class inheritance (e.g. checks method signature compatibility). Phan also checks for final classes/methods being overridden, that abstract methods are implemented, and that the implemented interface is really an interface (and so on).
  • Supports namespaces, traits, and variadics.
  • Supports Union Types.
  • Supports generic arrays such as int[], UserObject[], array<int,UserObject>, etc..
  • Supports array shapes such as array{key:string,otherKey:?stdClass}, etc. (internally and in PHPDoc tags) as of Phan >= 0.12.0.
  • The upcoming 0.12.3 release will support indicating that fields of an array shape are optional via array{requiredKey:string,optionalKey?:string} (useful for @param)
  • Supports phpdoc type annotations.
  • Supports inheriting phpdoc type annotations.
  • Supports checking that phpdoc type annotations are a narrowed form (E.g. subclasses/subtypes) of the real type signatures
  • Supports inferring types from assert() statements and conditionals in if elements/loops.
  • Supports @deprecated annotation for deprecating classes, methods and functions
  • Supports @internal annotation for elements (such as a constant, function, class, class constant, property or method) as internal to the package in which its defined.
  • Supports @suppress <ISSUE_TYPE> annotations for suppressing issues.
  • Supports magic @property annotations (partial) (@property <union_type> <variable_name>)
  • Supports magic @method annotations (@method <union_type> <method_name>(<union_type> <param1_name>))
  • Supports class_alias annotations (experimental, off by default)
  • Supports indicating the class to which a closure will be bound, via @phan-closure-scope (example)
  • Supports analysis of closures and return types passed to array_map, array_filter, and other internal array functions. (as of Phan 0.10.1+/0.8.9+)
  • Offers extensive configuration for weakening the analysis to make it useful on large sloppy code bases
  • Can be run on many cores. (requires pcntl)
  • Can run in the background (daemon mode), to then quickly respond to requests to analyze the latest version of a file. This can also act as a linter in the Language Server Protocol. Parts of the language server implementation are based on felixfbecker/php-language-server. While running in the background, Phan can be used from various editors.
  • Output is emitted in text, checkstyle, json, pylint, csv, or codeclimate formats.
  • Can run user plugins on source for checks specific to your code. Phan includes various plugins you may wish to enable for your project.

Usage:

Usage: ./phan [options] [files...]
 -f, --file-list <filename>
  A file containing a list of PHP files to be analyzed

 -l, --directory <directory>
  A directory that should be parsed for class and
  method information. After excluding the directories
  defined in --exclude-directory-list, the remaining
  files will be statically analyzed for errors.

  Thus, both first-party and third-party code being used by
  your application should be included in this list.

  You may include multiple `--directory DIR` options.

 --exclude-file <file>
  A file that should not be parsed or analyzed (or read
  at all). This is useful for excluding hopelessly
  unanalyzable files.

 -3, --exclude-directory-list <dir_list>
  A comma-separated list of directories that defines files
  that will be excluded from static analysis, but whose
  class and method information should be included.

  Generally, you'll want to include the directories for
  third-party code (such as "vendor/") in this list.

 --include-analysis-file-list <file_list>
  A comma-separated list of files that will be included in
  static analysis. All others won't be analyzed.

  This is primarily intended for performing standalone
  incremental analysis.

 -d, --project-root-directory </path/to/project>
  Hunt for a directory named .phan in the provided directory
  and read configuration file .phan/config.php from that path.

 -r, --file-list-only
  A file containing a list of PHP files to be analyzed to the
  exclusion of any other directories or files passed in. This
  is unlikely to be useful.

 -k, --config-file
  A path to a config file to load (instead of the default of
  .phan/config.php).

 -m <mode>, --output-mode
  Output mode from 'text', 'json', 'csv', 'codeclimate', 'checkstyle', or 'pylint'

 -o, --output <filename>
  Output filename

 --init
   [--init-level=3]
   [--init-analyze-dir=path/to/src]
   [--init-analyze-file=path/to/file.php]
   [--init-no-composer]

  Generates a `.phan/config.php` in the current directory
  based on the project's composer.json.
  The logic used to generate the config file is currently very simple.
  Some third party classes (e.g. in vendor/)
  will need to be manually added to 'directory_list' or excluded,
  and you may end up with a large number of issues to be manually suppressed.
  See https://github.com/phan/phan/wiki/Tutorial-for-Analyzing-a-Large-Sloppy-Code-Base

  [--init-level] affects the generated settings in `.phan/config.php`
    (e.g. null_casts_as_array).
    `--init-level` can be set to 1 (strictest) to 5 (least strict)
  [--init-analyze-dir] can be used as a relative path alongside directories
    that Phan infers from composer.json's "autoload" settings
  [--init-analyze-file] can be used as a relative path alongside files
    that Phan infers from composer.json's "bin" settings
  [--init-no-composer] can be used to tell Phan that the project
    is not a composer project.
    Phan will not check for composer.json or vendor/,
    and will not include those paths in the generated config.
  [--init-overwrite] will allow 'phan --init' to overwrite .phan/config.php.

 --color
  Add colors to the outputted issues. Tested in Unix.
  This is recommended for only the default --output-mode ('text')

 -p, --progress-bar
  Show progress bar

 -q, --quick
  Quick mode - doesn't recurse into all function calls

 -b, --backward-compatibility-checks
  Check for potential PHP 5 -> PHP 7 BC issues

 --target-php-version {7.0,7.1,7.2,native}
  The PHP version that the codebase will be checked for compatibility against.
  For best results, the PHP binary used to run Phan should have the same PHP version.
  (Phan relies on Reflection for some param counts
   and checks for undefined classes/methods/functions)

 -i, --ignore-undeclared
  Ignore undeclared functions and classes

 -y, --minimum-severity <level in {0,5,10}>
  Minimum severity level (low=0, normal=5, critical=10) to report.
  Defaults to 0.

 -c, --parent-constructor-required
  Comma-separated list of classes that require
  parent::__construct() to be called

 -x, --dead-code-detection
  Emit issues for classes, methods, functions, constants and
  properties that are probably never referenced and can
  possibly be removed.

 -j, --processes <int>
  The number of parallel processes to run during the analysis
  phase. Defaults to 1.

 -z, --signature-compatibility
  Analyze signatures for methods that are overrides to ensure
  compatibility with what they're overriding.

 --disable-plugins
  Don't run any plugins. Slightly faster.

 --plugin <pluginName|path/to/Plugin.php>
  Add an additional plugin to run. This flag can be repeated.
  (Either pass the name of the plugin or a relative/absolute path to the plugin)

 --strict-param-checking
  Enables the config option `strict_param_checking`.

 --strict-property-checking
  Enables the config option `strict_property_checking`.

 --strict-return-checking
  Enables the config option `strict_return_checking`.

 --strict-type-checking
  Equivalent to
  `--strict-param-checking --strict-property-checking --strict-return-checking`.

 --use-fallback-parser
  If a file to be analyzed is syntactically invalid
  (i.e. "php --syntax-check path/to/file" would emit a syntax error),
  then retry, using a different, slower error tolerant parser to parse it.
  (And phan will then analyze what could be parsed).
  This flag is experimental and may result in unexpected exceptions or errors.
  This flag does not affect excluded files and directories.

 --allow-polyfill-parser
  If the `php-ast` extension isn't available or is an outdated version,
  then use a slower parser (based on tolerant-php-parser) instead.
  Note that https://github.com/Microsoft/tolerant-php-parser
  has some known bugs which may result in false positive parse errors.

 --force-polyfill-parser
  Use a slower parser (based on tolerant-php-parser) instead of the native parser,
  even if the native parser is available.
  Useful mainly for debugging.

 -s, --daemonize-socket </path/to/file.sock>
  Unix socket for Phan to listen for requests on, in daemon mode.

 --daemonize-tcp-port <default|1024-65535>
  TCP port for Phan to listen for JSON requests on, in daemon mode.
  (e.g. 'default', which is an alias for port 4846.)
  `phan_client` can be used to communicate with the Phan Daemon.

 -v, --version
  Print phan's version number

 -h, --help
  This help information

 --extended-help
  This help information, plus less commonly used flags
  (E.g. for daemon mode)



No comments

Powered by Blogger.