Phpstan Rules Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require symplify/phpstan-rules --dev
   composer require phpstan/extension-installer --dev
   

   Add to composer.json:

   {
       "extra": {
           "phpstan": {
               "extension-classes": ["Symplify\\PHPStanRules\\PHPStan\\Extension\\SymplifyPHPStanRulesExtension"]
           }
       }
   }
   

2. First Configuration: Add to phpstan.neon:

   includes:
       - vendor/symplify/phpstan-rules/config/naming-rules.neon
       - vendor/symplify/phpstan-rules/config/static-rules.neon
   

3. First Use Case: Run PHPStan on a single file to test:

   vendor/bin/phpstan analyse src/Controller/SomeController.php
   

Implementation Patterns

Workflows

1. Incremental Adoption:

   • Start with naming-rules and static-rules for low-risk improvements.
   • Gradually enable symfony-rules or doctrine-rules after verifying compatibility.

2. Rule Grouping:

   • Use includes in phpstan.neon to enable entire rule sets:

     includes:
         - vendor/symplify/phpstan-rules/config/code-complexity-rules.neon
         - vendor/symplify/phpstan-rules/config/symfony-rules.neon
     

3. Custom Rule Configuration:

   • Configure ParamNameToTypeConventionRule for type hints:

     services:
         - class: Symplify\PHPStanRules\Rules\Convention\ParamNameToTypeConventionRule
           arguments:
               paramNamesToTypes:
                   userId: int
     

4. Symfony/Doctrine Integration:

   • Enable doctrine-rules for Doctrine-specific checks (e.g., NoEntityOutsideEntityNamespaceRule).
   • Use symfony-rules for Symfony best practices (e.g., SingleRequiredMethodRule).

5. Test-Specific Rules:

   • Apply NoTestMocksRule to enforce direct class usage in tests:

     rules:
         - Symplify\PHPStanRules\Rules\PHPUnit\NoTestMocksRule
     

Integration Tips

• CI/CD Pipeline: Add PHPStan with symplify/phpstan-rules to your CI workflow to enforce consistency. Example (GitHub Actions):

  - name: PHPStan
    run: vendor/bin/phpstan analyse --level=5
  

• IDE Integration: Configure your IDE (PHPStorm) to use the same phpstan.neon for real-time feedback.

• Rector Pairing: Use Rector alongside PHPStan to auto-fix violations (e.g., ForbiddenNewArgumentRule).

Gotchas and Tips

Pitfalls

1. Rule Overlap:

   • Some rules (e.g., NoConstructorOverrideRule) may conflict with legacy code. Disable them temporarily:

     rules:
         Symplify\PHPStanRules\Rules\Complexity\NoConstructorOverrideRule: false
     

2. Performance Impact:

   • Enabling all 80+ rules may slow down analysis. Start with a subset (e.g., naming-rules + static-rules).

3. False Positives:

   • StringFileAbsolutePathExistsRule may fail in test environments. Exclude test directories:

     paths:
         - src
         - config
     ignorePaths:
         - tests
     

4. Configuration Overrides:

   • Custom rule arguments (e.g., forbiddenTypes in ForbiddenNewArgumentRule) must be explicitly defined in services; omitting them disables the rule.

5. Doctrine/ORM Quirks:

   • NoEntityOutsideEntityNamespaceRule may trigger for legacy projects. Use @phpstan-ignore-next-line for exceptions:

     #[phpstan-ignore-next-line]
     #[ORM\Entity]
     class LegacyEntity {}
     

Debugging

1. Rule-Specific Errors:

   • Check the rule’s class name in the error message (e.g., Symplify\PHPStanRules\Rules\ForbiddenFuncCallRule) and refer to its documentation in the README.

2. Extension Loading:

   • If rules aren’t applied, verify phpstan/extension-installer is configured in composer.json and run:

     composer dump-autoload
     

3. Ignoring Specific Violations:

   • Use @phpstan-ignore-line or @phpstan-ignore-next-line for one-off cases:

     #[phpstan-ignore-line]
     $result = @file_get_contents($path);
     

Extension Points

1. Custom Rules:

   • Extend the package by creating your own rules following the same pattern (e.g., Symplify\PHPStanRules\Rules\BaseRule).

2. Dynamic Configuration:

   • Use configurable-rules.neon to enable/disable rules dynamically based on environment variables:

     # phpstan.neon
     parameters:
         enabledRules:
             - Symplify\PHPStanRules\Rules\ForbiddenFuncCallRule
     

3. Rule Prioritization:

   • Combine with PHPStan’s level setting to prioritize critical rules:

     level: max
     rules:
         Symplify\PHPStanRules\Rules\Complexity\NoConstructorOverrideRule: error
     

4. Symfony Flex Integration:

   • For Symfony projects, leverage symfony-config-rules.neon to validate config files (e.g., YAML/JSON):

     includes:
         - vendor/symplify/phpstan-rules/config/symfony-config-rules.neon