Open-source project
phan/phan avatar
phan/phan

Phan 6 checks PHP 8.1 to 8.5 and stays quiet when it cannot prove a fault

Phan is a static analyzer for PHP. Phan prefers to avoid false-positives and attempts to prove incorrectness rather than correctness.

5,622 stars366 forksPHPNOASSERTION

At a glance

What is it?
Phan is a PHP static analyzer built to avoid false positives rather than to prove correctness, aimed at teams that want type and compatibility findings without drowning in them. It ships as a Composer package, reads phpdoc types closely, and needs PHP 8.1 with the php-ast extension.
Who is it for?
Adopt Phan when your PHP codebase has docblock types worth trusting and you want compatibility checking across PHP 8.1 to 8.5 without a flood of speculative reports. Do not adopt it as a correctness proof, and think twice if php-ast cannot be installed, since the --allow-polyfill-parser fallback parses doc comments slightly differently.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly PHP, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • phan/phan5,622 ★ · -3
Star history
Repository2026-09-232026-11-15
phan/phan5.6k5.6k

-3 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

One composer line, a PHP 8.1 floor and a native parser extension

Phan 6 wants a recent PHP and a native extension. It requires PHP 8.1 or newer, the php-ast extension for parsing, and php-ast 1.1.3 or later if you are on PHP 8.4. The syntax it analyses runs from PHP 8.1 to 8.5. Installation is a single Composer line:

bash
composer require phan/phan

The extension is a real requirement rather than a suggestion. Without it you can fall back to a pure PHP parser with the CLI option --allow-polyfill-parser, and the README warns that parsing of doc comments differs slightly in that mode. That difference lands exactly where Phan does most of its type reasoning, because the annotations it consumes live in doc comments. Installing php-ast itself is a separate job with its own instructions, so on a locked down build image this is where the setup usually stalls.

phan --init writes .phan/config.php and bundles the stubs

The first run writes a configuration file, not a report. `phan --init` creates a `.phan/config.php` file with recommended settings and the bundled stubs, and you can write that file by hand instead if you prefer. Analysis then runs through the vendor binary:

bash
phan --init
./vendor/bin/phan

Stubs are the part that pays off early. Phan includes built in stubs for enhanced type checking of PHP extensions, so a call into an extension function can be checked against a known signature instead of being treated as unknown. The .phan/ directory at the top of this repository is where the project configures itself, which is the fastest way to see what a settled setup looks like. A fresh package and a codebase that has never been annotated are not the same starting point, which is why the wiki points at incrementally strengthening analysis rather than asking you to enable every check on day one.

Prove incorrectness, not correctness, and keep the loud checks behind flags

The goal is stated in the opening line of the README: Phan prefers to minimize false positives and attempts to prove incorrectness rather than correctness. Everything else follows from that. Type information has to be available or deducible before Phan will judge a call, it has a good but not comprehensive understanding of flow control, and it tracks values in a few use cases, arrays, integers and strings among them. A branch it cannot follow is a branch it says nothing about.

That is why the noisier analyses sit behind flags instead of defaults. Dead, unused and unreachable code need --dead-code-detection. Unused variables and parameters need --unused-variable-detection. Redundant or impossible conditions and pointless casts need --redundant-condition-detection. Unused use statements are in the set that --automatic-fix can rewrite for you. Expect silence where Phan lacks type information, and do not read that silence as a clean bill of health.

Eight PHP minor releases are in range, and nothing below 8.1 is named

Backward compatibility checking is a first class feature here, not an extension. Phan checks PHP 8.5, 8.4, 8.3, 8.2 and 8.1 backward compatibility, and separately flags features that were not supported in earlier PHP 8.x minor releases, naming property hooks, readonly classes, enums, union types and match expressions as examples. That is the difference between catching a call to an 8.4 only function at analysis time and finding out after deploy.

The ceiling is as concrete as the floor. The supported syntax range stops at PHP 8.5, so a 9.0 construct is outside what Phan can check, and the feature list names no compatibility target below 8.1, which means a legacy 7.x branch gets nothing from these checks. If your deployment matrix spans several minor releases, this is the check worth paying for; if you are on one fixed version, it is close to a no op.

Array shapes and generics arrive through doc comments, and can be wrong

The type vocabulary Phan reads is wide. There is support for union types, generic types through @template, generic arrays such as int[], UserObject[] and array<int,UserObject>, and array shapes such as array{key:string,otherKey:?stdClass}, both internally and in PHPDoc tags. Optional shape fields use the question mark suffix, array{requiredKey:string,optionalKey?:string}, which is what makes a shape usable in @param. Multi line @param, @var and @return annotations are normalized before parsing, so nested arrays and generics can be spread over several lines.

On top of that, Phan inherits phpdoc annotations, checks that an annotation is a narrowed form of the real signature, infers types from assert() statements and from conditionals in if elements and loops, and honours @deprecated, @internal, @suppress ISSUE_TYPE, and the magic @property and @method annotations.

The parser is a Composer fork override, not a vendored subtree

Phan relies on phan/phan-tolerant for the fallback parser and for the language server mapping, and it is consumed as the Composer package microsoft/tolerant-php-parser, overridden to that fork through the repository entry in composer.json rather than carried as a vendored subtree. Running the tolerant parser's own PHPUnit suites means installing its dev dependencies and invoking PHPUnit from inside the dependency directory:

bash
composer install
cd vendor/microsoft/tolerant-php-parser
composer install
php -d zend.assertions=1 -d assert.exception=1 vendor/bin/phpunit --testsuite invariants,api

To move the parser to a newer commit, adjust the constraint in composer.json or run composer update microsoft/tolerant-php-parser, then commit the resulting lockfile change. That makes the parser an ongoing maintenance commitment rather than a version bump: whoever upgrades Phan owns a fork override, a lockfile diff, and those two test suites.

Four license files sit beside src/, plugins/ and two entry points

The layout says how much surface there is. src/ holds the analyzer, plugins/ holds plugins, phan and phan_client are the entry points, internal/, tool/, test/ and tests/ carry the code and its suites, and phpcs.xml, phpunit.xml, phpdoc.dist.xml, .editorconfig and .codeclimate.yml cover style and CI. V6_GENERICS.md, Phan-AGENTS.md, CLAUDE.md, MAINTAINERS.md, NEWS.md and DCO.txt sit at the top level next to composer.json and composer.lock.

Licensing needs the same care. The repository ships LICENSE plus LICENSE.LANGUAGE_SERVER, LICENSE.PHPSTORM_STUBS and LICENSE.PHP_PARSER, and the project metadata asserts no single license, so read the file that covers the part you vendor instead of assuming the top level one covers everything. The default branch is v6, release 6.0.11 shipped on 2026-10-15 after 6.0.10 on 2026-10-12 and 6.0.9 on 2026-10-11, and the last push landed on 2026-11-01.

Editorial conclusion

Adopt Phan when your PHP codebase has docblock types worth trusting and you want compatibility checking across PHP 8.1 to 8.5 without a flood of speculative reports. Do not adopt it as a correctness proof, and think twice if php-ast cannot be installed, since the --allow-polyfill-parser fallback parses doc comments slightly differently. Before turning flags on, decide which checks your team can afford to act on, check which of the four LICENSE files covers the component you vendor, and remember that the parser is a fork override pinned in composer.json: moving it means editing the constraint and committing the lockfile. The last push was 2026-11-01 and release 6.0.11 shipped on 2026-10-15.

Frequently asked questions

What PHP version does Phan 6 need to run?

PHP 8.1 or newer, plus the php-ast extension. For PHP 8.4 support you need php-ast 1.1.3 or later, and Phan analyses syntax from PHP 8.1 through PHP 8.5.

Can Phan run without the php-ast extension installed?

Yes, through the CLI option --allow-polyfill-parser, which falls back to a pure PHP parser. The README notes there are slight differences in the parsing of doc comments in that mode.

How do I set up a new Phan project and run the first analysis?

Run phan --init to create a .phan/config.php file with recommended settings and bundled stubs, then run analysis through ./vendor/bin/phan. You can also create that config file by hand instead.

Which Phan checks stay off until you pass a flag?

Unused, dead and unreachable code need --dead-code-detection, unused variables and parameters need --unused-variable-detection, and redundant or impossible conditions plus pointless casts need --redundant-condition-detection. Unused use statements fall under --automatic-fix.

Why does Phan report so little on code that looks wrong?

Phan prefers to minimize false positives and attempts to prove incorrectness rather than correctness. It needs type information to be available or deducible, has a good but not comprehensive understanding of flow control, and tracks values in a few use cases such as arrays, integers and strings.

Official sources

  1. Issues
  2. phan/phan on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/phan-phan.svg)](https://hysenlabs.com/projects/phan-phan)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/phan-phan.svg)](https://hysenlabs.com/projects/phan-phan)

Was this useful?