Phpstan Rules Laravel Package

Getting Started

Install the package as a development dependency with composer require --dev ergebnis/phpstan-rules. Include its built-in rules.neon configuration in your main phpstan.neon (automatically handled if using phpstan/extension-installer). Start by running vendor/bin/phpstan analyze to see the new rules in action — they enforce strict, modern PHP idioms, so expect immediate feedback on patterns like missing declare(strict_types=1), non-final classes, or null default values. The simplest first win is enabling declareStrictTypesRule, which ensures every file opt-in to strict typing.

Implementation Patterns

• Gradual adoption: Use parameters.ergebnis.*.enabled: false to temporarily disable rules during migration (e.g., disable FinalRule while refactoring legacy codebases), then enable gradually.
• Template for new projects: Run phpstan-rules on fresh repos to enforce idioms like NoNamedArgumentRule (avoiding brittle named args), NoEvalRule, and TestCaseWithSuffixRule for consistent test names.
• Customization per domain: Override noExtends.classesAllowedToBeExtended to permit base entities from frameworks (e.g., Symfony’s AbstractController) while blocking arbitrary inheritance elsewhere.
• CI enforcement: Add a dedicated phpstan-rules check in CI with --error-format=github for actionable PR comments, using the -c flag to point to a dedicated phpstan-rules.neon that extends rules.neon but overrides exclusions as needed.

Gotchas and Tips

• Conflict with phpstan/phpstan-strict-rules: Both define NoNullableReturnTypeDeclarationRule — ensure your config loads ergebnis/phpstan-rules after to prevent subtle override issues.
• False positives with doctrine annotations: The FinalRule intentionally skips Doctrine entities annotated with @ORM\Entity — ensure your annotations are correct and up-to-date, otherwise false negatives may occur.
• noIssetRule pitfalls: This rule blocks isset() entirely — consider adding #phpstan-ignore-next-line# for performance-critical null checks on arrays where array_key_exists() is too expensive.
• Refactoring with IDE support: Pair FinalRule and NoExtendsRule with IDE features (e.g., PhpStorm’s "Make final" quick fix) to streamline refactoring.
• Debugging config: Run vendor/bin/phpstan analyse -c vendor/ergebnis/phpstan-rules/rules.neon to verify the ruleset is correctly loaded, especially if extension-installer fails silently.