Phpstan Shim Laravel Package

## Getting Started
### Minimal Steps
1. **Migrate to Modern PHPStan**:
   Since `phpstan/phpstan-shim` is **obsolete** (replaced by `phpstan/phpstan` PHAR), uninstall it and upgrade to the latest `phpstan/phpstan` (v0.12+):
   ```bash
   composer remove phpstan/phpstan-shim
   composer require --dev phpstan/phpstan:^0.12

• The PHAR distribution (phpstan.phar) is now the default—no shim required.

2. First Use Case: Run static analysis directly via the PHAR:

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

   • Replace app with your target directory (e.g., app/Http).
   • Use --level=5 for production-grade checks (adjust as needed).

3. Verify PHAR Execution: Ensure the PHAR runs without shim dependencies:

   php vendor/bin/phpstan --version
   

Where to Look First

• Official Docs: PHPStan 0.12+ Guide (PHAR-focused).
• Migration Notes: PHPStan 0.12 Release.
• Laravel Integration: Use phpstan-baseline.neon for suppressing known issues (e.g., Laravel’s dynamic properties).
• PHAR Troubleshooting: Check GitHub Issues for PHAR-specific problems.

Implementation Patterns

Workflows

1. PHAR-Based CI/CD: Update your composer.json scripts to leverage the PHAR:

   "scripts": {
     "test": [
       "@phpstan"
     ],
     "phpstan": "phpstan analyse app --level=5 --memory=1G"
   }
   

   • Run via composer test in CI (GitHub Actions, etc.).
   • Note: The PHAR is self-contained—no vendor/ dependencies.

2. Incremental Analysis with PHAR: Generate a baseline to suppress false positives:

   vendor/bin/phpstan analyse app --level=5 --generate-baseline
   

   • Store phpstan-baseline.neon in .gitignore if shared across devs.

3. Laravel-Specific Rules: Extend PHPStan’s config (phpstan.neon) with Laravel extensions:

   includes:
     - vendor/phpstan/phpstan-doctrine/extension.neon
     - vendor/phpstan/phpstan-laravel/extension.neon
   

   • PHAR Note: Extensions must still be installed via Composer (e.g., phpstan/phpstan-laravel).

Integration Tips

• IDE Support: Configure IDEs (PHPStorm/VSCode) to use the PHAR directly:

  // .phpstorm.meta.php
  <?php
  namespace PHPSTORM_META {
      override(type(phpstan\Phar\PhpStan::class), map([
          '$cli' => type('string')
      ]));
  }
  

• Parallel Execution: Use --parallel for large codebases (PHPStan 0.12+):

  vendor/bin/phpstan analyse app --level=5 --parallel --temp-dir=/tmp/phpstan
  

• Custom Rules: Create project-specific rules and reference them in phpstan.neon:

  services:
    - MyApp\Rules\CustomRule
  

  • PHAR Compatibility: Ensure rules are autoloaded via Composer.

Gotchas and Tips

Pitfalls

1. PHAR Dependency Removal:

   • Symptom: Composer errors if vendor/phpstan or phpstan-shim remnants exist.
   • Fix: Follow migration steps exactly (delete vendor/phpstan, vendor/bin/phpstan, and composer.lock).
   • Verify: Run composer why-not phpstan/phpstan to confirm no conflicts.

2. Legacy Config Incompatibility:

   • Issue: Old phpstan.neon files may use deprecated syntax (e.g., parameters instead of services).
   • Fix: Update to PHPStan 0.12+ config format.
   • Example:

     # Old (deprecated)
     parameters:
       level: 5
     
     # New (0.12+)
     level: 5
     

3. PHAR Path Issues:

   • Symptom: phpstan.phar not found or permission errors.
   • Fix:
     • Ensure vendor/bin/phpstan is executable:

       chmod +x vendor/bin/phpstan
       

     • Use absolute paths in CI/CD:

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

4. False Positives in Laravel:

   • Common Cases:
     • Dynamic properties (e.g., $request->input()).
     • Laravel’s magic methods (e.g., __call, __get).
   • Fix:
     • Use @var annotations or @phpstan-ignore-line.
     • Example:

       /** @var \Illuminate\Http\Request $request */
       $request->input('key'); // No error
       

Debugging

• PHAR Verbose Mode: Debug PHAR execution with:

  vendor/bin/phpstan analyse --verbose
  

• Error Code Lookup: PHPStan errors include codes (e.g., ParameterShouldBeType). Resolve them via:

  grep "ParameterShouldBeType" vendor/phpstan/phpstan/src/Rules/
  

• Baseline Corruption:
  • Symptom: phpstan-baseline.neon causes analysis to fail.
  • Fix: Regenerate it or manually edit to remove invalid entries.

Extension Points

1. PHAR Customization:

   • Override the PHAR’s default behavior by creating a custom wrapper script:

     #!/bin/bash
     php vendor/bin/phpstan analyse "$@" --memory=2G
     

   • Save as custom-phpstan and use it in CI.

2. Template Rules for Blade: Extend PHPStan to support Blade templates by creating a custom rule:

   class BladeDynamicPropertyRule extends Rule
   {
       public function getNodeType(): string { return BladeDynamicProperty::class; }
       // Implement logic to ignore Laravel's dynamic properties
   }
   

   • Register in phpstan.neon:

     services:
       - MyApp\Rules\BladeDynamicPropertyRule
     

3. Performance Optimization:

   • Exclude Directories:

     excludeFiles:
       - tests/**
       - vendor/**
       - storage/**
     

   • Memory Limits: Increase for large apps:

     vendor/bin/phpstan analyse --memory=4G
     

   • Cache Results: Use --cache-results to speed up repeated runs:

     vendor/bin/phpstan analyse --cache-results --cache-results-dir=/tmp/phpstan-cache
     

NO_UPDATE_NEEDED was **not** applicable—this assessment was fully updated to reflect the PHAR migration and PHPStan 0.12 changes.