Phpstan Sarif Formatter Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer (ensure compatibility with PHPStan 2.x):

   composer require --dev jbelien/phpstan-sarif-formatter
   

   Requires PHPStan 2.x (verified compatibility). Install PHPStan 2.x via:

   composer require --dev phpstan/phpstan "^2.0"
   

2. First Use Case Run PHPStan 2.x with SARIF output:

   vendor/bin/phpstan analyse src --error-format=SarifJson
   

   Outputs a .sarif file (e.g., phpstan-results.sarif) for tools like GitHub Advanced Security, SonarQube, or VS Code.

3. Where to Look First

   • PHPStan 2.x Docs: Review PHPStan 2.x migration guide for SARIF-specific changes.
   • Example Config: Update phpstan.neon to PHPStan 2.x syntax (e.g., parameters instead of includes):

     parameters:
         level: 5
         rules:
             PhpStan\Rules\Arrays\ArrayShapeRule: strict
     

   • Tooling: Pair with phpstan-baseline (updated for PHPStan 2.x) or phpstan-extension-installer.

Implementation Patterns

Workflow Integration

1. CI/CD Pipelines (PHPStan 2.x)

   • GitHub Actions: Updated for PHPStan 2.x:

     - name: Run PHPStan 2.x
       run: vendor/bin/phpstan analyse --error-format=SarifJson -c phpstan.neon
     - name: Upload SARIF
       uses: actions/upload-artifact@v3
       with:
         name: phpstan-results
         path: phpstan-results.sarif
     

   • SonarQube: Use sonar.phpstan.reportPaths (PHPStan 2.x generates SARIF identically to v1.x).

2. Local Development

   • VS Code: Use the SARIF Viewer extension (no changes needed).
   • CLI Parsing: PHPStan 2.x SARIF output remains JSON-compatible:

     $sarif = json_decode(file_get_contents('phpstan-results.sarif'), true);
     foreach ($sarif['runs'][0]['results'] as $result) {
         if ($result['level'] === 'error') {
             echo "Error in {$result['locations'][0]['physicalLocation']['artifactLocation']['uri']}\n";
         }
     }
     

3. Custom Reporting

   • Slack Notifications: Parse SARIF as before; PHPStan 2.x rule IDs remain consistent (e.g., PhpStan\Rules\Arrays\ArrayShapeRule).
   • HTML Reports: Use Blade or similar to generate dashboards (no SARIF schema changes).

Configuration Tips (PHPStan 2.x)

• Rule Prioritization: Update phpstan.neon to PHPStan 2.x syntax:

  parameters:
      level: 5
      rules:
          PhpStan\Rules\Arrays\ArrayShapeRule: strict
  

• Baseline Files: Use phpstan-baseline (v2.x) to exclude known issues:

  vendor/bin/phpstan analyse --generate-baseline --error-format=SarifJson
  

Gotchas and Tips

Pitfalls

1. PHPStan 2.x Migration

   • Breaking Changes: PHPStan 2.x removes includes in favor of parameters. Update configs:

     - includes: vendor/phpstan/phpstan/src/Rules
     + parameters:
     +     rules:
     +         PhpStan\Rules\Arrays\ArrayShapeRule: strict
     

   • Rule Namespaces: PHPStan 2.x uses fully qualified names (e.g., PhpStan\Rules\... instead of Arrays\ArrayShapeRule). Verify SARIF rule IDs match.

2. Performance Overhead

   • SARIF generation in PHPStan 2.x may still add ~10–30% runtime. Use --memory-limit:

     vendor/bin/phpstan analyse --error-format=SarifJson --memory-limit=1G
     

   • Tip: Cache SARIF results for unchanged codebases (e.g., node_modules/.cache/phpstan.sarif).

3. Tooling Compatibility

   • GitHub SARIF Upload: Ensure the SARIF file is named phpstan-results.sarif (GitHub’s default expectation).
   • SonarQube: PHPStan 2.x SARIF output is backward-compatible, but explicitly set:

     sonar.phpstan.reportPaths=phpstan-results.sarif
     

Debugging

• Invalid SARIF: Validate output with SARIF Validator:

  npx @microsoft/sarif-vscode validate phpstan-results.sarif
  

• Missing Issues: Ensure --error-format=SarifJson is the last flag (order matters in PHPStan 2.x).
• Rule ID Mismatches: Use phpstan diagnose to list available rules and verify SARIF mappings:

  vendor/bin/phpstan diagnose
  

Extension Points

1. Custom Rules (PHPStan 2.x)

   • Extend Jbelien\PhpStanSarifFormatter\SarifFormatter to override rule IDs for PHPStan 2.x:

     class CustomSarifFormatter extends SarifFormatter {
         protected function getRuleId(string $ruleName): string {
             return match ($ruleName) {
                 'PhpStan\Rules\Arrays\ArrayShapeRule' => 'custom-array-shape-v2',
                 default => parent::getRuleId($ruleName),
             };
         }
     }
     

   • Register via phpstan.neon:

     services:
         - Jbelien\PhpStanSarifFormatter\CustomSarifFormatter
     

2. Dynamic Rule Mapping

   • Override getToolComponent() to customize SARIF metadata for PHPStan 2.x rules:

     protected function getToolComponent(): array {
         return [
             'name' => 'Custom PHPStan 2.x',
             'informationUri' => 'https://github.com/your/repo',
             'rules' => [
                 'PhpStan\Rules\Arrays\ArrayShapeRule' => [
                     'id' => 'array-shape-v2',
                     'name' => 'Array Shape Rule (PHPStan 2.x)',
                     'helpUri' => 'https://phpstan.org/rules/arrays/array-shape',
                 ],
             ],
         ];
     }
     

3. Parallel Execution

   • Combine with phpstan-parallel (PHPStan 2.x compatible) for large codebases:

     vendor/bin/phpstan analyse --parallel --error-format=SarifJson
     

   • Warning: SARIF merging may require post-processing to avoid duplicate entries. Use --generate-baseline to stabilize outputs.