Bladestan Laravel Package

Technical Evaluation

Architecture Fit

• Static Analysis Extension: Bladestan extends PHPStan’s core functionality to analyze Blade templates, leveraging PHPStan’s existing architecture for rule definition, caching, and reporting. This ensures consistency with the broader static analysis ecosystem and avoids redundant tooling.
• Laravel-Specific Coverage: Addresses a critical pain point in Laravel development—Blade template errors (e.g., undefined methods, missing variables, syntax issues) that typically manifest only at runtime. By shifting these checks left, it aligns with Laravel’s emphasis on proactive quality.
• Modular Design: Operates as a standalone extension without modifying Laravel’s core or requiring changes to existing Blade compiler logic. It integrates via PHPStan’s extension system, minimizing architectural coupling.
• Modern Laravel Support: Actively maintained for Laravel 10–12, Livewire 3.3–4.0, and PHP 8.1+, ensuring compatibility with current and near-future Laravel versions. Supports edge cases like dynamic components, Livewire attributes, and non-HTML mail templates.
• Cache Invalidation: Recent updates (e.g., PR #174) ensure PHPStan’s result cache is invalidated when Blade templates change, preventing stale analysis results—a critical feature for CI/CD pipelines.

Technical Risk

• False Positives/Negatives: Blade templates often use dynamic or runtime-generated content (e.g., @include($dynamicPartial)), which may trigger false positives. Mitigation: Configure PHPStan’s ignoreErrors or level settings to tune sensitivity (e.g., ignore undefinedMethod for specific classes).
• Complex Template Logic: Templates with heavy client-side logic (e.g., @php blocks with complex expressions) may not be fully analyzable. Risk is low for most use cases, but edge cases (e.g., custom Blade directives) might require manual review.
• IDE Integration: While the CLI provides clickable error links, IDE plugins (e.g., PHPStorm) may not natively support the custom --error-format=blade output. Workaround: Use the CLI or configure PHPStan’s IDE integration to parse the custom format.
• Performance Overhead: Static analysis of Blade templates adds computational cost, though negligible for most projects. For large codebases, consider:
  • Running Bladestan in parallel with other PHPStan rules.
  • Excluding non-critical templates (e.g., third-party views) via paths configuration.
• Dependency on PHPStan: Bladestan is useless without PHPStan. If the team resists adopting PHPStan, this package becomes a blocking dependency. Mitigation: Frame it as a bundled feature (e.g., "PHPStan + Bladestan = Blade safety net").

Key Questions

1. PHPStan Adoption:
   • Is PHPStan already used in the project? If not, what’s the team’s appetite for adding it?
   • Are there existing PHPStan configurations that might conflict with Bladestan’s rules?
2. Template Complexity:
   • What percentage of Blade templates are dynamic (e.g., @include($variable)) vs. static? Dynamic templates may yield more false positives.
   • Are there custom Blade directives or complex @php logic that might not be fully supported?
3. CI/CD Integration:
   • Should Bladestan run in CI as a blocking check (fail builds on errors) or informational (log warnings)?
   • How will results be surfaced to developers (e.g., GitHub PR comments, Slack alerts)?
4. Error Handling:
   • What’s the acceptable threshold for false positives? Should certain rules (e.g., undefinedMethod) be ignored for specific classes?
   • How will template-specific errors (e.g., missing @endsection) be prioritized vs. PHPStan’s other rules?
5. Maintenance:
   • Who will own updates if Laravel/Livewire versions evolve beyond Bladestan’s support?
   • Should the package be pinned to a specific version or allowed to auto-update?

Integration Approach

Stack Fit

• PHPStan Integration:
  • Primary Path: Use PHPStan’s extension installer to auto-configure Bladestan. This is the recommended approach and requires no manual phpstan.neon edits.
  • Fallback: Manually include the extension via:

    includes:
        - ./vendor/tomasvotruba/bladestan/config/extension.neon
    

  • Customization: Override default rules by extending the included extension.neon in a project-specific config (e.g., phpstan-blade.neon).
• Laravel Compatibility:
  • Automatic Detection: Bladestan reads template paths from Laravel’s config/view.paths, avoiding hardcoded assumptions.
  • Livewire/Symfony: Supports Livewire components (via config/livewire.php) and Symfony mail templates (e.g., resources/views/emails/*.blade.php).
  • Facade Support: Analyzes Response::view() and View::make() calls, including data passed via with(), withShare(), etc.
• Toolchain Synergy:
  • Parallel Execution: Run Bladestan alongside existing PHPStan rules for comprehensive analysis:

    vendor/bin/phpstan analyze --memory-limit=1G --parallel
    

  • Caching: Leverage PHPStan’s result cache for faster iterations (cache invalidates automatically on template changes, per PR #174).

Migration Path

1. Assessment Phase:
   • Audit existing Blade templates for common issues (e.g., undefined methods, missing @endsection) using a trial run:

     composer require --dev tomasvotruba/bladestan
     vendor/bin/phpstan analyze --error-format=blade --level=5
     

   • Review false positives/negatives and adjust PHPStan’s level or ignoreErrors as needed.
2. Configuration:
   • Add Bladestan to composer.json under require-dev:

     "require-dev": {
         "tomasvotruba/bladestan": "^0.11"
     }
     

   • Configure PHPStan to include the extension (preferred: extension installer).
3. CI/CD Integration:
   • Add a step to run Bladestan in CI (e.g., GitHub Actions):

     - name: Blade Template Analysis
       run: vendor/bin/phpstan analyze --error-format=blade --level=5
     

   • Configure to fail builds on errors (or warnings, depending on team preference).
4. Developer Workflow:
   • Add a make or npm script for local analysis:

     "scripts": {
         "test:bladestan": "phpstan analyze --error-format=blade"
     }
     

   • Educate the team on interpreting the custom error format (e.g., post_codex.blade.php:15 links).

Compatibility

• Laravel Versions: Officially supports 10–12; likely works with 9.x but untested.
• Livewire: Supports 3.3–4.0; check for breaking changes if using newer versions.
• PHP Versions: Requires PHP 8.1+ (aligned with Laravel 10+).
• Template Types: Analyzes:
  • Standard Blade views (resources/views/*.blade.php).
  • Mail templates (resources/views/emails/*.blade.php).
  • Livewire component views (resources/views/livewire/*.blade.php).
  • Dynamic includes (e.g., @include($partial)).
• Exclusions: Can ignore specific paths or files via PHPStan’s paths or excludePaths:

  paths:
      - app
      - config
      - routes
      - tests
  excludePaths:
      - vendor
      - storage/framework/views
  

Sequencing

1. Phase 1: Pilot (1–2 Sprints)
   • Run Bladestan in a non-blocking mode (log warnings only) to identify issues and false positives.
   • Prioritize fixing critical errors (e.g., undefined methods that could cause runtime crashes).
2. Phase 2: CI Enforcement (3–4 Sprints)
   • Gradually enable blocking checks in CI, starting with high-risk templates (e.g., critical paths).
   • Use level settings to control strictness (e.g., level: 5 for all rules, or level: 3 for select files).
3. Phase 3: Full Integration (Ongoing)
   • Integrate Bladestan into PR workflows (e.g., GitHub checks).
   • Add custom error formatting to IDEs (e.g., PHPStorm) for better DX.
   • Monitor false positives and refine configurations.

Operational Impact

Maintenance

• Low Effort:
  • Dependency Management: Bladestan is MIT-licensed and actively maintained. Pin to a specific version (e.g., ^0.11) to avoid surprises.
  • Configuration Drift: Minimal risk of drift; changes are backward-compatible (e.g., new Laravel versions are supported via minor releases).
• Upgrade Path:
  • Follow