Phpstan Rules Laravel Package

Getting Started

Install the package as a development dependency:

composer require --dev ergebnis/phpstan-rules

If you use phpstan/extension-installer, the rules are auto-loaded via rules.neon. Otherwise, include it manually in your phpstan.neon:

includes:
  - vendor/ergebnis/phpstan-rules/rules.neon

Start using the rules — they’re opinionated but practical: enforce strict types, forbid eval, disallow nullable types, require final on classes, and more. Run vendor/bin/phpstan analyze to see immediate feedback.

Implementation Patterns

• Onboarding new projects: Include rules.neon in the PHPStan config of new repositories to enforce consistent quality from day one.
• Gradual adoption: Temporarily disable conflicting rules (e.g., final: enabled: false) in phpstan.neon while migrating legacy code, then incrementally re-enable.
• ** PHPUnit-specific projects**: Leverage testCaseWithSuffix and noExtends (allowing TestCase) to enforce naming and composition best practices in test suites.
• Pre-commit hook integration: Wrap phpstan in a Git hook to block commits violating these rules — especially useful for declare(strict_types=1), noEval, and noErrorSuppression.
• Custom rule overrides: Extend or tweak rules via config parameters (e.g., classesAllowedToBeExtended, allowAbstractClasses) rather than disabling entire categories.

Gotchas and Tips

• noIsset can be aggressive: Using isset() for array-key checking (e.g., isset($arr['key'])) is common practice. Consider disabling noIsset or selectively ignoring specific uses via // @phpstan-ignore (though that’ll trigger noPhpstanIgnore if you have that enabled).
• declare(strict_types=1) enforcement: Applies to non-empty files only — omit the directive in files with only declare(strict_types=1); and docblocks, and PHPStan will let it slide.
• final class exceptions: Doctrine entities (via annotations or attributes) are exempted automatically — don’t manually override unless you're using a custom metadata driver.
• Nullable types: Rules like noParameterWithNullableTypeDeclaration and noNullableReturnTypeDeclaration help enforce non-nullable-first design but may cause noise in transitional codebases. Disable selectively or use union types (int|null → int) once nullable inputs are handled upstream.
• Extension config keys are unique: The package scopes all config under parameters.ergebnis.*, so avoid collisions with other PHPStan rules. Double-check indentation in phpstan.neon when disabling/adjusting — a common YAML pitfall.
• No phpstan-ignore comments allowed: noPhpstanIgnore catches all @phpstan-ignore* docblocks. Use only in exceptional cases and ensure you document why in a PR comment, not in code — otherwise the tool itself penalizes its workaround.