Phpstan Exception Rules Laravel Package

Getting Started

1. Install via Composer: composer require --dev pepakriz/phpstan-exception-rules
2. Enable the ruleset in your phpstan.neon:

   includes:
       - vendor/pepakriz/phpstan-exception-rules/rules.neon
   

3. First use case: Run PHPStan on a legacy codebase to surface methods with missing @throws — especially public methods, service constructors, and API endpoints where exception contracts matter most.

Implementation Patterns

• Gradual adoption: Start with stricter rules only for newly written code (e.g., via per-file excludes or layered configs) to avoid overwhelming legacy analysis output.
• API layer enforcement: Use this primarily for DTOs, controllers, and service interfaces where exceptions are part of the public contract — set allowMissingThrows: false for these namespaces.
• Automated fixes via Rector: Pair with rector/rector to auto-add @throws for methods where exceptions are guaranteed (e.g., all try { return $client->request(); } catch (\Exception $e) { throw $e; }).
• CI gate: Add a check that fails if any new methods introduce unreported exceptions (compare baseline vs. live output in PRs).

Gotchas and Tips

• ⚠️ Dead code risk: The package only analyzes @throws and inferred exceptions — it won’t detect runtime-only exceptions (e.g., throw new \Error). Complement with runtime test coverage.
• Annotation drift: If you already have inconsistent @throws, running this may produce noisy false positives — generate a baseline (phpstan generate-baseline) and treat @throws as “living documentation” updated incrementally.
• Trait + inheritance quirks: Rules may miss overridden methods where parent @throws are inconsistent — verify via --debug or use parameters.leverageInheritance: true (if supported by version).
• Extension hook: Rules use PHPStan’s ExceptionTagMethodReflectionExtension — custom method wrappers or dynamic callable proxies may need explicit @throws even if inferred trivially.