Php Parser Laravel Package

Product Decisions This Supports

• Build vs. buy for any code-intelligence feature. If a roadmap item involves "understand PHP source without running it," this is the buy decision. nikic/php-parser is the de facto reference implementation — PHPStan, Psalm, Rector, PHP-CS-Fixer, and most Laravel upgrade tooling sit on top of it. Writing your own lexer/grammar is a multi-quarter effort with permanent maintenance drag; adopting this collapses that to an integration task.
• Automated upgrade and migration tooling. Parsing PHP 7.x through 8.6 (including partial function application, typed constants, asymmetric visibility, dynamic class constant fetch) means you can ship a "Laravel/PHP version upgrade" assistant, codemods for deprecated APIs, or in-house Rector rules without being blocked every time PHP ships a release.
• Static analysis and custom lint rules. Accurate AST + name resolution + constant-expression evaluation is enough to build architectural guardrails (e.g., "controllers must not touch Eloquent models directly," "no env() outside config," "no DB::raw() with interpolated input") as enforceable CI rules rather than code-review folklore.
• Code generation and scaffolding. The AST builders plus pretty printer let you generate idiomatic, correctly-formatted PHP — useful for richer make: commands, DTO/resource generators, or schema-driven boilerplate that must be valid and readable, not string-concatenated.
• Formatting-preserving refactors. The pretty printer can rewrite a file while keeping the developer's existing style, so automated changes land as minimal diffs. This is the difference between a codemod developers accept and one that gets reverted for whitespace noise.
• Security and dependency scanning. AST-driven detection of dangerous sinks (unserialize, dynamic includes, eval, raw SQL construction) is far more precise than regex and produces far fewer false positives — directly relevant to a security-review or compliance feature.
• Partial-AST handling for messy real-world code. Error recovery means you can analyze codebases containing syntax errors or newer-than-supported syntax instead of failing the whole run — important for a hosted/CI product scanning customer repositories you don't control.
• Roadmap sequencing signal. The changelog shows the maintainer tracking PHP releases (8.5, 8.6) within weeks. That means "support the newest PHP" is not a roadmap line item you need to own.

When to Consider This Package

Adopt when:

• You need to read or write PHP source as structured data: analysis, transformation, generation, or migration.
• Correctness matters — you need line/column positions, resolved namespaced names, and version-aware parsing rather than pattern matching.
• You want to emit modified code that preserves the original author's formatting.
• You're building on or extending the existing PHP tooling ecosystem (Rector rules, PHPStan extensions, PHP-CS-Fixer fixers) — those all speak this AST already.
• You need to parse code targeting a PHP version different from the one you run on.
• You can tolerate a library, not a framework: it has no service provider, no Laravel facade, no config file. You will write the integration layer.

Look elsewhere when:

• The requirement is simple text search, grep-style rules, or template substitution. A parser is overkill and slower.
• You need runtime behavior, not static structure — reflection, container introspection, or actually executing the code answers different questions.
• You need type inference, not just syntax. This gives you an AST; PHPStan or Psalm give you a type system on top of it. Buy that layer, don't rebuild it.
• An off-the-shelf tool already covers the use case: Laravel Pint for style, Rector for framework upgrades, PHPStan/Psalm for analysis. Wrapping them is usually cheaper than authoring rules from scratch.
• Your transformation pipeline must be language-agnostic — this is PHP-only by design.
• You can't absorb major-version migrations. v4 → v5 is a real breaking change with an upgrade guide; pinning and planning is required.
• Throughput is extreme and you're parsing millions of files per hour — budget for it: disable Xdebug in the parsing workers, reuse parser objects, and consider caching serialized ASTs (JSON encode/decode is supported) rather than reparsing.

Adoption criteria checklist: confirm your supported PHP runtime (v5 requires PHP ≥ 7.4), confirm the PHP language versions you must parse, decide your version-pinning and upgrade cadence, and confirm BSD-3-Clause is compatible with your distribution model (it is for essentially all commercial uses, including SaaS and redistributed packages).

How to Pitch It (Stakeholders)

For executives: This is a mature, low-risk, free (BSD-3-Clause) dependency that is effectively the industry standard for understanding PHP code programmatically — it underpins PHPStan, Psalm, Rector, and PHP-CS-Fixer, and is maintained by a PHP core contributor with 17k+ GitHub stars and a steady release cadence through PHP 8.6. Buying this instead of building means we skip roughly a year of parser engineering and inherit the ecosystem's compatibility work for free. It unlocks a class of features (automated upgrades, enforced architecture rules, precise security scanning, high-quality code generation) that are otherwise out of reach for a small team; the cost is integration effort plus a planned migration whenever the library cuts a major version. The strategic risk of not adopting is that we either build a worse parser or ship regex-based tooling with high false-positive rates that erodes developer trust.

For engineering: Treat this as infrastructure, not a feature. Expect a learning curve around the node/visitor model and the pretty printer's formatting-preservation contract. We should: pin to a major version and track releases; isolate parsing behind a thin internal service so a future v6 migration is one adapter, not a thousand call sites; keep parsing out of request paths (run it in queue workers/jobs with Xdebug off); and lean on the AST builders and error recovery rather than hand-constructing nodes or assuming input parses cleanly. Where Rector or PHPStan already solve the problem, extend those instead of duplicating their rule engines.