Phpstan Symfony Laravel Package

Product Decisions This Supports

• Definition of Done / quality gate for PRs. This is a cheap, permanent addition to CI that catches a whole class of defects—unregistered service IDs, private services fetched directly from the container, wrong console arguments/options, invalid default values—before review. A PM can make "PHPStan at level N with the Symfony extension passes" a merge requirement without writing a spec.
• Build vs. buy. Buy. It is MIT-licensed, maintained under the PHPStan org, and a dev-only dependency. There is no credible reason to hand-roll container-aware type inference; the alternative is paying engineers to rediscover service wiring bugs in staging.
• Symfony upgrade and platform modernization roadmaps. The extension understands container XML dumps, @required/#[Required] autowiring, PHP config files (Symfony 5.3+), and console command structures. It is a leading indicator of upgrade breakage: run it against the next major Symfony version in a branch and the error delta becomes your migration backlog. This directly de-risks a framework upgrade epic and lets you scope it with evidence rather than estimates.
• Deprecation and refactor safety. Refactors that rename services, change message handler return types, or move logic into query buses are validated statically. The HandleTrait wrapper configuration means CQRS/query-bus abstractions stop being mixed and start being typed—this is the difference between a refactor you can measure and one you hope went well.
• Developer onboarding and IDE feedback. Correct return types for $container->get(), Controller::get(), ParameterBagInterface::get(), SerializerInterface::deserialize(), Request::getContent(), form errors, cache callbacks, and mailer envelopes propagate into the editor. New hires get accurate autocompletion and inline errors on day one instead of tribal knowledge.
• Adoption strategy decisions. PHPStan's level system plus baselines lets a PM choose between "ratchet one level per quarter" and "big-bang cleanup." The extension is compatible with incremental adoption, so this is a scheduling and staffing decision, not a technical blocker.
• Test-to-production feedback loop. Because it narrows KernelTestCase::getContainer() correctly and supports console application loaders, you can analyze test code and console tooling, not just src/. That extends the quality gate to the areas where wiring bugs most often hide.

When to Consider This Package

Adopt when:

• The product is a Symfony application (or a Symfony bundle) on a supported PHP version, and the team uses—or is willing to use—PHPStan 2.x.
• You already ship a var/cache/dev/*_KernelDevDebugContainer.xml artifact or can generate one in CI (container cache warmup in the pipeline). This is the single largest adoption prerequisite and worth validating with a spike before committing.
• The codebase makes meaningful use of the DI container, console commands, Messenger/CQRS buses, forms, or the serializer—the areas where the extension's type inference and rules pay off.
• You want to enforce service wiring correctness without runtime integration tests for every service. Static analysis is far cheaper per defect found.
• The team can absorb a baseline of pre-existing errors. Plan for an initial triage sprint; the ROI curve is steep after the first ratchet.

Look elsewhere or defer when:

• The stack is not Symfony (Laravel, plain PSR-11, or a custom framework). The extension's value is almost entirely framework-specific; plain PHPStan plus a Laravel equivalent is the right call.
• The team standardizes on Psalm. There is no equivalent path here, and running two analyzers is usually a net negative.
• The codebase is a large legacy monolith where a full run produces thousands of errors with no appetite for baselining and ratcheting. In that case, defer until there is an explicit engineering-quality initiative with owner and budget.
• PHPStan core cannot be upgraded. Release 2.1.0 requires PHPStan 2.3.0, so the extension's version is coupled to the analyzer's. If the platform is pinned to an older PHPStan, expect friction.
• The service is small and container-light (a handful of autowired classes, no console commands, no Messenger). The setup and CI wiring cost likely exceeds the defect-prevention benefit—use base PHPStan alone.
• CI cannot warm the Symfony cache or tolerate the extra job time. The consoleApplicationLoader and container XML dependencies make this a pipeline change, not a one-line composer require.

Practical adoption notes a PM should plan for: budget a spike to prove container XML generation in CI; decide up front whether constantHassers: false is acceptable (it hides genuine errors—default to leaving it on); and treat the scanDirectories/scanFiles settings for Symfony 5.3+ PHP config as required configuration, not optional polish.

How to Pitch It (Stakeholders)

For executives (one paragraph). This is a free, MIT-licensed, dev-only add-on that makes our static analysis Symfony-aware. In plain terms: it turns "the app starts and the tests pass" into "every service reference, console argument, and query-bus return type is verified automatically on every pull request." Setup is a Composer dev dependency plus a CI config line, with no runtime footprint and no production risk. The payoff is fewer container-wiring and configuration defects reaching staging, faster and safer Symfony upgrades, and a shorter ramp for new engineers—at effectively zero licensing cost. The main cost is engineering time to establish a clean baseline and keep the analyzer current.

For engineering leads. PHPStan alone does not understand Symfony's container, so $container->get() returns object/mixed and every downstream call is untyped. This extension supplies that missing type information: correct returns for ContainerInterface, Controller/AbstractController, ParameterBagInterface, Request::getContent(), InputBag, ResponseHeaderBag, serializer denormalization, form errors, cache callbacks, and HandleTrait::handle() via configurable wrappers. It also adds rules that flag unregistered services, private services fetched directly, and undefined or invalid console arguments and options, and it recognizes #[Required]/@required autowiring. Configuration is a container XML path plus optional console application loader and scanDirectories/scanFiles entries for PHP config. It is dev-only, MIT, and maintained by the PHPStan organization, so maintenance risk is low and the upgrade path tracks PHPStan releases—note that 2.1.0 requires PHPStan 2.3.0, so plan analyzer and extension upgrades together.

For the team doing the work. Start with a timeboxed spike: generate the dev container XML in CI, wire up extension.neon and rules.neon, and run at your current PHPStan level with a baseline. Publish the error count and top error categories—that number is the business case. Then ratchet: one level per sprint, no baseline growth allowed, and a rule that any new service or console command must analyze clean. Add consoleApplicationLoader early if console commands matter, and add messenger.handleTraitWrappers as soon as a query bus exists, since that converts mixed into real types across the codebase.

Risks and Mitigations (PM view)

• Pipeline coupling. Analysis depends on a warmed container cache and, for PHP 5.3+ PHP configs, on scanned directories and files. Mitigation: own the CI step explicitly and alert on cache-warmup failure rather than letting analysis silently degrade.
• Version coupling with PHPStan core. Extension releases track analyzer releases (2.1.0 requires PHPStan 2.3.0). Mitigation: upgrade analyzer and extension in the same PR, and pin both.
• Noise from constantHassers. Disabling it hides real errors. Mitigation: keep the default; only disable per-project with a documented justification.
• Maturity signal. The repository is documented and actively released, but it is a focused developer tool with a narrow scope rather than a large ecosystem project—evaluate it as infrastructure, not as a platform bet.
• Baseline drift. The failure mode is a baseline that grows quietly until the gate is meaningless. Mitigation: enforce "baseline count may only decrease," review the number in sprint metrics, and treat regressions as defects.