Phpstan Rules Laravel Package

Product Decisions This Supports

• Standardize Static Analysis with Lower Rollout Friction: The auto-loading model via phpstan/extension-installer (introduced in 14.17.0) now extends to two new rule-set groups, modern and collections, both enabled by default. Teams get broader baseline enforcement without maintaining includes: blocks, strengthening the case for standardizing code quality across squads.
• Controlled Adoption Instead of All-or-Nothing Rollout: Rule sets remain gated by symplify.* parameters. Default-on sets now include naming, complexity, configurable, static, symfony, symfonyConfig, doctrine, phpunit, plus the new modern and collections; mocks and ctor stay off. PMs can sequence quality initiatives by risk and team readiness — and, importantly, explicitly disable groups that don't fit a given repo (e.g., collections for non-Doctrine services).
• Shift Left on Quality with Easier CI/CD Integration: New rules target high-cost defect classes — untyped Doctrine Collection usage, missing repository return types, nullable getters returning non-nullable types, controller helpers leaking as public "actions," and mocks returning values that contradict native return types. These are caught at analysis time rather than in review or production.
• Domain-Model Integrity for Doctrine-Heavy Products: The collections group (4 rules) enforces generic docblocks and Collection return types on to-many associations. For products where entity/repository contracts underpin reporting, search, or API serialization, this meaningfully reduces "bare Collection" ambiguity and downstream type errors.
• API/Contract Hygiene: NoReadonlyApiParamRule and NullablePropertyGetterMustReturnNullableRule codify subtle but real correctness constraints, useful for libraries or shared internal packages where reflection and nullability surprises are expensive.
• Framework Modernization: NoPublicNonActionMethodInControllerRule (Symfony), RepositoryMethodMustHaveReturnTypeRule (Doctrine), and the new modern group (trait, reference, dynamic-name, foreach-ception rules) support migration and modernization goals by enforcing current conventions.
• Noise Reduction / Maintenance Discipline: Four rules were removed as too specific or not relevant (ExplicitExpectsMockMethodRule, NoMockOnlyTestRule, NoRepositoryCallInDataFixtureRule, NoDuplicateNonRepeatableAttributeRule), and FormTypeClassNameRule moved into the naming set. Fewer bespoke rules means less config to justify and maintain.
• Developer Experience (DX): Group-level toggles (the README now explicitly recommends preferring groups over individual rules) keep phpstan.neon short and make trialing rules incremental.
• Upgrade/Migration Planning: This is a behavior-changing release for existing adopters. New default-on groups will surface new errors immediately after upgrade, and any config referencing the four removed rules must be cleaned up. This is a planned remediation task, not a reason to defer adoption.

When to Consider This Package

• Adopt if:

  • Your team uses Symfony, Doctrine, or PHPUnit and wants framework-specific best practices enforced mechanically.
  • You maintain a large codebase (legacy or modern) and need scalable static analysis with manageable rollout controls.
  • Your roadmap includes clean architecture (DDD, hexagonal) or a Symfony 6+/Doctrine 3+ migration.
  • You want to reduce ignored PHPStan errors (MaximumIgnoredErrorCountRule) or enforce naming/convention consistency.
  • You want Doctrine Collection typing discipline across entities and repositories — a common source of latent type bugs.
  • Your CI/CD lacks strict static analysis, or you want a lower-friction way to standardize PHPStan rules across repositories.
  • You are willing to use phpstan/extension-installer and remove manual includes: for this package's rule sets.

• Look elsewhere if:

  • Your stack is non-PHP, or Laravel-only without Symfony/Doctrine. Note the trade-off changed slightly: the new modern group and NullablePropertyGetterMustReturnNullableRule are framework-agnostic, so Laravel teams gain some value — but symfony, symfonyConfig, doctrine, collections, and phpunit-specific rules assume a different stack. In practice, a Laravel team would run mostly with those groups disabled, which weakens the case versus a Laravel-native toolset (e.g., Larastan + Pint + Rector).
  • You need performance-critical analysis runs; this package adds overhead, and two newly default-on groups increase it further.
  • Your team resists strict conventions (namespace suffixes, forbidden patterns, generic docblocks) due to legacy constraints.
  • You already have a mature custom PHPStan setup with equivalent or stricter rules.
  • Your focus is runtime behavior rather than static analysis.

• Migration notes for 14.19.0 (stacking on 14.17.0):

  • New default-on groups: modern and collections are enabled by default. Expect new PHPStan errors on first run after upgrade. Either budget a remediation pass or set symplify.modern: false / symplify.collections: false to stage adoption.
  • Removed rules: if any config references ExplicitExpectsMockMethodRule, NoMockOnlyTestRule, NoRepositoryCallInDataFixtureRule, or NoDuplicateNonRepeatableAttributeRule, remove those entries. Inline rule identifier constants were also inlined into each rule (#348) — verify any custom references to those constants.
  • FormTypeClassNameRule moved into the naming set; check per-rule overrides if you had customized it.
  • Forbidden-function list changed: curl_* and array_walk removed. If your policy depended on blocking curl_*, add an explicit custom rule — this is a reduction in coverage worth flagging.
  • Still required from 14.17.0: remove manual includes of these rule sets and symplify-rules.neon to avoid duplicated-include failures; use symplify.* toggles. rector-rules.neon (including the new PreferGenericTemplateOnSameUnionTypeRule) remains opt-in.
  • Prefer group toggles over individual rule toggles, per the package's own README guidance — individual toggles are the most likely thing to break across releases (as the removals show).

How to Pitch It (Stakeholders)

For Executives: "This package automates a large set of code-quality checks for our Symfony/Doctrine stack, reducing defects and onboarding time. The latest release broadens coverage where bugs are expensive: it enforces strict typing on Doctrine collections and repository return types, correct nullability on getters, and prevents test mocks from returning values that contradict real types. Rollout stays low-risk — rule sets auto-load and are toggled with simple symplify.* parameters, so we can enable the newer checks per team rather than all at once. Two new groups switch on by default, so we should plan a short remediation pass on upgrade; four narrow rules were removed, which reduces maintenance. MIT-licensed and maintained by the Symplify team."

For Engineering Leaders: *"Symplify's PHPStan rules let us enforce best practices at scale without writing custom logic. 14.19.0 adds substance, not just config:

• New default-on groups: modern (traits, references, dynamic names, foreach-ception) and collections (Doctrine Collection typing — 4 rules covering getters, properties, params, and return docblocks).
• New correctness rules: repository methods must declare return types; nullable property getters must return nullable types; @api params must not be readonly; mocked willReturn() must match the mocked method's native return type; controllers must keep helpers private.
• Cleanup: four over-specific rules removed and FormTypeClassNameRule moved to the naming set — one less reason to hand-maintain per-rule overrides. Prefer group toggles over individual rule toggles.
• Watch items: new default-on groups will produce new errors immediately — stage with symplify.modern: false / symplify.collections: false if needed. curl_* was removed from the forbidden-function list, so that policy now needs a custom rule if we relied on it. Any config naming the removed rules must be cleaned up.
• CI/CD consistency: hard limits on ignored errors plus shared rule sets across repos. Sequence it as: upgrade → clean removed-rule references → run PHPStan → triage new violations → tune symplify.* to match readiness."*

For Developers: "Think of it as a linter for PHPStan — it catches things your IDE and code review miss. 14.19.0 brings two new default-on groups: modern (trait/reference/dynamic-name/foreach issues) and collections, which stops you from using bare Collection without a generic docblock like @var Collection<int, Item>. It also flags repository methods without return types, nullable getters declared non-nullable, readonly on @api params, controller helpers that should be private, and mocks whose willReturn() value doesn't match the method's native return type. Config is still toggles in phpstan.neon; groups are encouraged over individual rules. Heads-up on upgrade: the new groups are on by default so expect new errors, four old rules were deleted (remove them from any configs), and FormTypeClassNameRule moved into the naming set. Run phpstan analyse locally and keep CI aligned."