Phpstan Extension Laravel Package

Getting Started

• Install as a dev dependency:

  composer require --dev php-static-analysis/phpstan-extension
  

• Check the package's own composer.json and README first. Repository metadata is unavailable, so verify the supported PHPStan/PHP versions and the exact extension config file (extension.neon vs rules.neon) in vendor/php-static-analysis/phpstan-extension.
• Register it in phpstan.neon:

  includes:
      - vendor/php-static-analysis/phpstan-extension/extension.neon
  

• Look first at:
  • vendor/php-static-analysis/phpstan-extension/README.md
  • vendor/php-static-analysis/phpstan-extension/extension.neon
  • vendor/php-static-analysis/phpstan-extension/src/Attribute/
  • package tests for supported attribute targets and examples
• First use case: replace one local @phpstan-ignore comment on a legacy or framework-magic method with the package's attribute, then run:

  vendor/bin/phpstan analyse --debug
  

  Confirm the error disappears only where expected and still appears elsewhere.

Implementation Patterns

• Use attributes as narrow, intentional suppressions at the boundary: a single method, property, or class where PHPStan cannot infer behavior. Prefer the smallest scope available.
• Keep reasons and identifiers in the attribute where supported:

  #[StaticAnalysis\Suppress('Called dynamically by the router')]
  public function dispatch(): void
  {
  }
  

  The exact attribute class and arguments must come from the package source.
• Use attributes for framework seams: magic methods, generated proxies, container accessors, ORM hydration, and legacy entry points. Avoid annotating whole namespaces or broad application layers.
• Combine attributes with a baseline. Use PHPStan's baseline for bulk legacy noise; use attributes for deliberate, reviewed exceptions that should remain visible in code.
• Migrate incrementally: start with new code and actively touched legacy hotspots. Grep for the attribute during review to keep the exception list auditable.
• Ensure attribute classes are autoloadable during analysis. If attributes live in a separate package, require that package as a dev dependency too.
• In CI, pin both PHPStan and this extension, run phpstan analyse --no-progress, and include composer.lock in the cache key. PHPStan extension behavior can change with PHPStan internals.
• If the package does not cover a needed case, prefer writing a small custom PHPStan rule over forking the extension. The extension is only an attribute reader; custom rules are the safer extension point.

Gotchas and Tips

• The extension is silently inert if not included in phpstan.neon. Verify registration with a deliberate test error and confirm it is suppressed only when the extension is loaded.
• The include path is easy to get wrong. Inspect the package directory for the actual .neon file name before copying examples.
• Attributes require PHP 8+. Check the package's PHP constraint and run analysis on the oldest PHP version you support.
• Attribute targets matter. An attribute placed on an unsupported symbol may be ignored by the reader or rejected by PHP. Check the package tests for class, method, property, and parameter support.
• PHPStan result caches can hide config changes. After changing phpstan.neon, the extension version, or attribute usage, clear the cache:

  vendor/bin/phpstan clear-result-cache
  

• PHPStan extensions are tightly coupled to PHPStan internals. Treat PHPStan upgrades as coordinated upgrades and test in CI before merging.
• Because adoption is small and repository metadata is unavailable, pin the package version and review the source. MIT licensing helps, but low star count means less community validation.
• Do not let attributes become an invisible ignore list. Require a reason, keep suppressions local, and review new attributes in pull requests.
• If the package is dev-only but source code contains its attributes, confirm production behavior. PHP attributes are generally lazy, but any runtime reflection over attributes needs the attribute classes available.
• Debug with verbose PHPStan output:

  vendor/bin/phpstan analyse -c phpstan.neon --debug -v
  

  If the attribute still appears ignored, check the extension container registration and whether the attribute is on a node the package actually inspects.