Phpstan Laravel Package

Getting Started

Minimal Setup

1. Installation: Add the package via Composer in your Laravel project:

   composer require ibexa/phpstan --dev
   

   Ensure your project meets Ibexa DXP requirements (PHP 8.1+, Laravel 9+).

2. Configuration: Copy the default PHPStan config from the package:

   vendor/bin/phpstan generate-config ibexa-phpstan.neon
   

   Place it in your project root (e.g., phpstan.neon) and extend it with Laravel-specific rules:

   includes:
       - vendor/ibexa/phpstan/ibexa.neon
       - phpstan.neon.dist  # Laravel's default config (if using larastan)
   

3. First Run: Execute PHPStan with Ibexa’s rules:

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

   Focus on src/ or app/ for Laravel-specific checks.

First Use Case

Static Analysis for Ibexa DXP Integration: If your Laravel app interacts with Ibexa DXP (e.g., via the Ibexa Connect API), use this package to catch:

• Type mismatches in Ibexa-specific return types (e.g., Content, Location).
• Undefined Ibexa service method calls.
• Deprecated Ibexa API usage.

Example:

// Check for Ibexa ContentService type safety
$content = $contentService->loadContent($contentId); // PHPStan flags if $contentId is not int|string

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline: Add PHPStan to your Laravel CI (e.g., GitHub Actions):

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

   Set --level=5 (maximum) for strict checks during PRs.

2. Laravel-Specific Rules: Combine with larastan for Laravel-centric checks:

   extends:
       - larastan.neon
       - ibexa.neon
   

3. Custom Rules: Extend Ibexa’s rules for Laravel:

   // app/Rules/IbexaLaravelRule.php
   use Ibexa\PhpStan\Rules\IbexaRule;
   use PhpStan\Rules\Rule;
   
   class IbexaLaravelRule extends IbexaRule implements Rule {
       public function getNodeType(): string { return 'PhpStan\Node\Expr\MethodCall'; }
       public function processNode(Node $node, Scope $scope) { /* Custom logic */ }
   }
   

   Register in phpstan.neon:

   services:
       - IbexaLaravelRule
   

Common Patterns

Gotchas and Tips

Pitfalls

1. False Positives:

   • Ibexa’s dynamic methods (e.g., ContentService->loadContent()) may trigger MethodNotFound errors.
   • Fix: Use @method PHPDoc annotations or suppress with:

     suppress:
         - MethodNotFound: Ibexa\Contracts\Core\Repository\Values\Content\Content
     

2. Laravel-Ibexa Conflicts:

   • If using both larastan and ibexa/phpstan, conflicts may arise in rule precedence.
   • Fix: Explicitly order extends in phpstan.neon:

     extends:
         - ibexa.neon  # First to avoid Laravel overrides
         - larastan.neon
     

3. Missing Ibexa Autoloading:

   • If Ibexa classes aren’t autoloaded, PHPStan fails to resolve types.
   • Fix: Ensure composer dump-autoload is run post-install.

Debugging Tips

1. Isolate Rules: Test Ibexa-specific rules alone:

   vendor/bin/phpstan analyse --level=5 --rules=Ibexa\PhpStan\Rules src
   

2. Verbose Output: Use --debug to trace rule application:

   vendor/bin/phpstan analyse --debug
   

3. Custom Error Formats: For CI, use --error-format=json or github for PR annotations.

Extension Points

1. Add Custom Ibexa Types: Extend PHPStan’s type system for Ibexa-specific classes:

   // app/PhpStan/Extension/IbexaExtension.php
   use Ibexa\Contracts\Core\Repository\Values\Content\Content;
   use PhpStan\Type\ObjectType;
   
   class IbexaExtension implements Extension {
       public function getClassReflectionExtensions(): array {
           return [
               new ClassReflectionExtension(
                   Content::class,
                   new ObjectType(Content::class)
               ),
           ];
       }
   }
   

   Register in phpstan.neon:

   services:
       - IbexaExtension
   

2. Override Ibexa Rules: Disable or modify Ibexa’s rules via suppress or custom implementations:

   suppress:
       - Ibexa\PhpStan\Rules\DeprecatedMethod: Ibexa\Contracts\Core\Repository\Values\Content\*
   

3. Laravel Facades: If using Ibexa via Laravel facades (e.g., Ibexa::contentService()), add PHPDoc:

   /**
    * @return \Ibexa\Contracts\Core\Repository\ContentService
    */
   public static function contentService() { ... }
   

Pro Tips

• Pair with phpstan-baseline: Baseline current state to ignore legacy Ibexa code:

  vendor/bin/phpstan analyse --generate-baseline
  

• Focus on Critical Paths: Prioritize analysis for:
  • Ibexa service layers (app/Services/Ibexa*).
  • API controllers interacting with Ibexa.
• Leverage Ibexa’s PHPDoc: Use @var annotations for Ibexa return types to reduce false positives:

  /**
   * @return \Ibexa\Contracts\Core\Repository\Values\Content\Content[]
   */
  public function getContents(): array { ... }