Phpstan Generic Rules Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require --dev korbeil/phpstan-generic-rules
   

   Ensure phpstan is installed and configured in your project.

2. Basic Configuration Extend your phpstan.neon to include the rules:

   includes:
       - vendor/korbeil/phpstan-generic-rules/extension.neon
   

3. First Use Case Run PHPStan with the new rules:

   vendor/bin/phpstan analyse src
   

   Focus on catching generic type-related issues (e.g., array vs list, mixed misuse).

Implementation Patterns

Common Workflows

1. Strict Typing Enforcement Use rules like Generic\Type\ArrayShapeRule to enforce strict array shapes:

   // phpstan.neon
   services:
       PhpStan\Rules\Generic\Type\ArrayShapeRule:
           parameters:
               allowedTypes: ['string', 'int']
   

2. Generic Type Validation Validate generic classes (e.g., Collection<T>) with Generic\Type\GenericClassRule:

   // Example: Enforce Collection<string>
   $collection = new Collection(['a', 'b']); // Valid
   $collection = new Collection([1, 2]);     // Fails (int not allowed)
   

3. Integration with Custom Rules Combine with existing PHPStan rules (e.g., NoUnusedImportsRule) for layered validation.

Best Practices

• Incremental Adoption: Start with level: 5 in phpstan.neon and gradually enable stricter rules.
• Customize Rules: Override defaults in phpstan.neon for project-specific needs (e.g., allowed mixed types).
• CI/CD Hooks: Fail builds on new violations to enforce consistency.

Gotchas and Tips

Pitfalls

1. Performance Overhead Generic rules add analysis time. Run in CI with --memory-limit=1G if needed.

2. False Positives

   • Rule Generic\Type\MixedTypeRule may flag legitimate mixed usage (e.g., dynamic APIs).
   • Fix: Whitelist types or adjust rule parameters.

3. Neon Configuration Conflicts Ensure includes in phpstan.neon don’t duplicate or override rules unintentionally.

Debugging Tips

• Isolate Rules: Test one rule at a time by commenting out others in extension.neon.
• Verbose Output: Use --error-format=github for actionable feedback.
• Rule Documentation: Check the PHPStan docs for rule-specific examples.

Extension Points

1. Custom Rules Extend korbeil/phpstan-generic-rules by creating a child rule class (e.g., CustomGenericRule). Example:

   use PhpStan\Rules\Generic\GenericRule;
   
   class CustomGenericRule extends GenericRule {
       public function getNodeType(): string { return 'PhpStan\Node\GenericNode'; }
       // ...
   }
   

2. Parameter Tuning Adjust rule parameters dynamically via environment variables (e.g., ALLOWED_GENERIC_TYPES).

3. Plugin Integration Pair with phpstan/phpstan-doctrine for ORM-specific generic type checks.