Parser Reflection Laravel Package

Technical Evaluation

Architecture Fit

• PHP 8.2+ Hard Requirement: The package now mandates PHP 8.2+, aligning with Laravel 10+ but breaking compatibility with Laravel 9.x (PHP 8.0+). This is a strategic shift—Laravel’s official PHP policy now requires PHP 8.1+, making this a non-issue for new projects but a blocker for legacy Laravel 9.x apps.
• Attribute-First Design: The PHP 8+ attributes support (PR #130) and AST-preserving resolution (PR #137) make this package a cornerstone for Laravel’s attribute-based ecosystem (e.g., #[Route], #[Middleware], #[Cacheable]). This is a critical upgrade for modern Laravel static analysis.
• Unary Expressions & New Syntax: Support for UnaryMinus/UnaryPlus (PR #141) and new expressions in defaults (PR #154) improves analysis of:
  • Laravel’s fluent method chains (e.g., Str::of($value)->limit(10)).
  • Custom macros with arithmetic operations (e.g., Collection::macro('negate', fn($items) => array_map(fn($i) => -$i, $items))).
• PHP 8.4+ Compatibility: Fixes for getModifiers() (PR #152) and nullable types (PR #146) ensure future-proofing for Laravel’s upcoming PHP 8.4+ adoption.

Updated Use Cases:

• Attribute Validation: Mandatory for Laravel 10+ projects using #[Route], #[Middleware], or custom attributes (e.g., #[ApiResource]).
• Macro & Helper Analysis: Detect unsafe patterns in Laravel’s fluent APIs (e.g., Model::query()->where() with dynamic conditions).
• Deprecation Enforcement: Auto-detect usage of legacy syntax (e.g., Route::get() vs. #[Get]).
• Performance Profiling: AST-preserving resolution enables precise method call graphs for Laravel’s service container bindings.

Conflicts:

• Legacy Laravel 9.x: No longer supported due to PHP 8.2+ requirement. Teams must upgrade or use nikic/php-parser as a fallback.
• Dynamic Proxies: While AST resolution improves accuracy, Laravel’s runtime-generated proxies (e.g., Illuminate\Foundation\Application) may still require hybrid static/runtime analysis.
• False Positives: The new expression support (PR #154) could introduce edge cases for complex default values (e.g., public function __construct(public array $items = [new class()])).

Integration Feasibility

• Lower Coupling: The AST-preserving architecture reduces false positives for Laravel’s dynamic patterns (e.g., __call(), __getStatic()), making it more reliable than pure reflection.
• Attribute Support: Directly enables analysis of Laravel’s attribute-based features without workarounds, reducing manual validation overhead.
• Migration Path:
  • Laravel 10+: Seamless integration for attribute routing, middleware, and macros.
  • Laravel 9.x: Not recommended—requires PHP 8.2+ upgrade, which may not be feasible for all teams.
  • Legacy Apps: Must use hybrid analysis (static + runtime reflection) or switch to nikic/php-parser.

Updated Risks:

Key Questions

1. PHP Version Compatibility:
   • Can your Laravel app upgrade to PHP 8.2+? If not, this package is incompatible—evaluate alternatives like nikic/php-parser.
2. Attribute Adoption:
   • Are you using Laravel’s attribute-based routing/middleware? If yes, this package is now a direct fit.
3. Dynamic Features:
   • Do you rely on runtime-generated classes (e.g., Model observers, event listeners)? If so, plan for hybrid analysis.
4. Performance Impact:
   • How will AST-preserving resolution affect parsing time for your codebase? Test with laravel/framework.
5. Tooling Stack:
   • Will this replace phpstan or supplement it? Consider integrating with pestphp/pest for test-level analysis.
6. Legacy Codebase:
   • If stuck on Laravel 9.x, can you incrementally upgrade PHP while maintaining compatibility?

Integration Approach

Stack Fit

• Best Fit:
  • Attribute Validation: Pre-deployment checks for #[Route], #[Middleware], or custom attributes.
  • Macro Analysis: Detect unsafe usage in Str::macro(), Collection::macro().
  • CI/CD Gates: Block merges with invalid attribute syntax (e.g., missing path in #[Route]).
  • Performance Profiling: Analyze Laravel’s service container bindings via AST call graphs.
• Hybrid Workflow:
  • Use this package for static attribute/macro analysis.
  • Fall back to ReflectionClass for runtime dynamic features (e.g., __callStatic in Model).
• Poor Fit:
  • Real-time request processing (use runtime reflection instead).
  • Laravel 9.x (PHP 8.0) without attribute support.

Migration Path

1. Upgrade Laravel/PHP:
   • Target Laravel 10+ (PHP 8.2+) for full attribute support.
   • For Laravel 9.x, assess whether a PHP 8.2 upgrade is feasible—if not, use nikic/php-parser.
2. Incremental Rollout:
   • Start with attribute validation (e.g., php artisan analyze:attributes).
   • Gradually add macro/method analysis and performance profiling.
3. Hybrid Implementation:

   // Example: Service to combine static and runtime analysis
   class HybridAnalyzer {
       public function analyzeClass(string $class): array {
           $staticData = (new ParserReflection($class))->getAST();
           $runtimeData = new ReflectionClass($class);
   
           return [
               'static' => [
                   'attributes' => $staticData->getAttributes(),
                   'methods' => $staticData->getMethods(),
               ],
               'runtime' => [
                   'dynamic_calls' => $this->detectDynamicCalls($runtimeData),
               ],
           ];
       }
   
       private function detectDynamicCalls(ReflectionClass $class): array {
           // Fallback for __call(), __callStatic(), etc.
           return array_filter($class->getMethods(), fn($m) =>
               $m->isPublic() && in_array($m->getName(), ['__call', '__callStatic'])
           );
       }
   }
   

Compatibility

• Laravel Versions:
  • Laravel 10+: Full support for attributes; test with laravel/framework’s attribute tests.
  • Laravel 9.x: Not recommended—PHP 8.2+ required.
  • Legacy: Use nikic/php-parser instead.
• PHP Versions:
  • Minimum: PHP 8.2 (hard requirement).
  • Recommended: PHP 8.3+ for new expression support (e.g., new class() in defaults).
• Dependencies:
  • Conflict Risk: Low, but test with phpstan/pest for overlapping AST parsing.
  • Composer: Enforce PHP 8.2+ with:

    {
      "config": {
        "platform-check": true,
        "platform": {
          "php": "8.2"
        }
      }
    }
    

Sequencing

1. Pre-Analysis Setup:
   • Configure .parserignore to exclude:
     • vendor/
     • bootstrap/cache/
     • Generated classes (e.g., app/Models/{Model}.php if using php artisan make:model with events).
2. Core Integration:
   • Create a custom Artisan command:

     php artisan make