Getting Started

Install the package via Composer in your Laravel project's development dependencies:

composer require --dev contributte/phpstan

First Steps

Configure PHPStan: Extend your existing phpstan.neon configuration to include Contributte's rules. Place this in your project root or config directory:
```
includes:
    - vendor/contributte/phpstan/extension.neon
```
Run PHPStan: Execute the analysis with a strict level (e.g., 5) to catch potential issues:
```
vendor/bin/phpstan analyse --level=5
```
Review Output: Focus on high-severity issues first (e.g., type errors, deprecated APIs). Use the --error-format=github flag for CI-friendly output.

First Use Case

Laravel Service Container Validation: Contributte’s rules often include checks for service container bindings, dependency injection, and Laravel-specific patterns. Run PHPStan on your app/Providers/ directory to validate:

Proper type hints in service bindings.
Correct use of bind(), singleton(), and when() methods.
Resolvable dependencies in constructors.

Example command:

vendor/bin/phpstan analyse app/Providers --level=5

Implementation Patterns

Workflow Integration

CI/CD Pipeline: Add PHPStan to your CI workflow (e.g., GitHub Actions) to enforce rules pre-merge:

# .github/workflows/phpstan.yml
jobs:
  phpstan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
      - run: composer install --dev
      - run: vendor/bin/phpstan analyse --level=5 --error-format=github

Pre-Commit Hooks: Use tools like phpstan/extension-installer or roave/security-advisories to run PHPStan locally before commits:
```
composer require --dev phpstan/extension-installer
vendor/bin/phpstan install
```
IDE Integration: Configure your IDE (e.g., PHPStorm, VSCode) to use PHPStan for real-time feedback:
- PHPStorm: Enable "PHPStan" under Settings > Languages & Frameworks > PHP > Quality Tools.
- VSCode: Install the "PHPStan" extension and add to settings.json:
```
"phpstan.executablePath": "vendor/bin/phpstan",
"phpstan.level": 5
```

Laravel-Specific Patterns

Eloquent Model Checks: Use Contributte’s rules to validate:

Proper use of $fillable, $guarded, and $casts.
Type safety in model attributes (e.g., Carbon instances, custom casts).

Example phpstan.neon snippet:

parameters:
    level: 5
extends:
    - phpstan/recommended
rules:
    - Contributte\PHPStan\Rules\Laravel\DisallowDynamicPropertiesRule
    - Contributte\PHPStan\Rules\Laravel\TypeMismatchInFillableRule

Blade Template Analysis: If Contributte includes Blade-specific rules, configure PHPStan to analyze Blade files:
```
vendor/bin/phpstan analyse resources/views --level=5
```

Service Container Validation: Validate service bindings and dependencies:

includes:
    - vendor/contributte/phpstan/extension.neon
parameters:
    checkedContainerServices: true

Gradual Adoption

Start with Level 3: Begin with --level=3 to avoid overwhelming the team with false positives.
```
vendor/bin/phpstan analyse --level=3
```
Exclude Problematic Areas: Temporarily exclude directories or files with known issues:
```
excludes:
    - app/OldLegacyCode/
    - tests/
```
Fix Issues Iteratively: Address high-priority issues (e.g., type errors) first, then refine rules over time.

Gotchas and Tips

Common Pitfalls

False Positives in Laravel:
- Dynamic Properties: Laravel uses __get()/__set() for dynamic properties (e.g., in models). Contributte’s DisallowDynamicPropertiesRule may flag these. Exclude or suppress:
```
rules:
    - Contributte\PHPStan\Rules\Laravel\DisallowDynamicPropertiesRule@-
```
- Magic Methods: Rules targeting strict type hints may conflict with Laravel’s magic methods (e.g., __call(), __invoke()). Use @phpstan-ignore annotations:
```
// @phpstan-ignore-next-line
$result = $model->__call('nonExistentMethod', []);
```
Configuration Overrides:
- Contributte’s extension.neon may override your existing PHPStan config. Review merged settings:
```
vendor/bin/phpstan diagnose
```
PHPStan Version Mismatch:
- Ensure compatibility between contributte/phpstan and your phpstan/phpstan version. Pin versions in composer.json:
```
"require-dev": {
    "phpstan/phpstan": "^1.10.0",
    "contributte/phpstan": "^0.3.0"
}
```
Performance in Large Codebases:
- PHPStan can be slow on large projects. Optimize with:
  - Parallel analysis: --parallel.
  - Focused runs: Target specific directories (e.g., app/Http/).
  - Cache results: --generate-report=html for debugging.

Debugging Tips

Isolate Rule Issues: Run PHPStan with a single rule to debug:

vendor/bin/phpstan analyse --rules=Contributte\PHPStan\Rules\Laravel\*

Use @phpstan-ignore: Temporarily suppress false positives in problematic files:
```
// @phpstan-ignore-file
```
Check Rule Documentation: Contributte’s rules may lack detailed docs. Inspect the source for context:
```
grep -r "class.*Rule" vendor/contributte/phpstan
```

Extension Points

Custom Rules: Extend Contributte’s rules by creating your own PHPStan extensions. Example structure:
```
/app/Rules/
  /PHPStan/
    MyCustomRule.php
```
Then include in phpstan.neon:
```
includes:
    - app/Rules/PHPStan/MyCustomRule.neon
```

Modify Contributte’s Config: Override specific rules in your phpstan.neon:

rules:
    Contributte\PHPStan\Rules\Laravel\StrictPropertyTypesRule:
        severity: warning

Community Contributions:
- Report issues or request new Laravel-specific rules on Contributte’s GitHub.
- Fork the package to add custom rules for your team’s needs.

Laravel-Specific Quirks

Facade Usage: Contributte’s rules may not fully understand Laravel Facades (e.g., Route::, Cache::). Exclude or use @phpstan-ignore:
```
// @phpstan-ignore-next-line
Route::get('/', fn() => view('welcome'));
```
Dynamic Method Calls: Laravel’s macro() and mixin() features can trigger false positives. Example:
```
// @phpstan-ignore-next-line
Str::macro('customMethod', fn() => 'value');
```
Service Provider Initialization: PHPStan may not resolve service container bindings during static analysis. Use @var annotations:
```
/** @var \Illuminate\Contracts\Container\Container $container */
$container = app();
```

Configuration Tips

Level-Based Workflow: Use different PHPStan levels for development vs. CI:
- Dev: --level=3 (lenient).
- CI: --level=5 (strict).
Exclude Tests: Avoid noise from test files:
```
excludes:
    - tests/
```
Focus on Critical Paths: Prioritize analysis of high-impact directories:
```
vendor/bin/phpstan analyse app/Http app/Models --level=5
```

Maintenance

Update Dependencies: Regularly update contributte/phpstan and phpstan/phpstan to benefit from new rules and fixes:
```
composer update --dev phpstan/phpstan contributte/phpstan
```
Review Rule Changes: Check Contributte’s release notes for breaking changes or new features.
Document Exclusions: Main

Phpstan Laravel Package