Bladestan Laravel Package

Technical Evaluation

Release reviewed: Bladestan 0.11.8 is a patch release with bug fixes only. No breaking changes, deprecations, new configuration requirements, or migration steps were identified. The release improves reliability in Livewire/Blade parsing edge cases and import handling, so it warrants a minor assessment refresh but not a change in adoption strategy.

Architecture Fit

• Static Analysis Extension: Bladestan extends PHPStan to analyze Blade templates while reusing PHPStan’s rule, cache, and reporting architecture. This remains a strong fit for teams already standardizing on PHPStan.
• Laravel-Specific Coverage: It shifts Blade runtime failures—undefined methods, missing variables, syntax issues—into static analysis. This is especially valuable for Laravel views, mail templates, and Livewire components.
• Modular Design: Operates as a standalone PHPStan extension without modifying Laravel core or Blade compiler behavior.
• Modern Laravel Support: Maintained for Laravel 10–12, Livewire 3.3–4.0, and PHP 8.1+. The 0.11.8 fixes specifically improve Livewire attribute parsing and Blade import handling.
• Cache Invalidation: Prior cache-invalidation work remains important for CI/CD correctness. 0.11.8 does not change cache behavior but reduces parser-level false results.
• Release-Specific Improvement: 0.11.8 fixes:
  • Truncated component data when attribute values contain brackets.
  • Broken use function import bubble-up.
  • Livewire tag attribute key camelization before component PHP generation. These reduce false positives/negatives in Livewire-heavy and imported-function-heavy Blade templates.

Technical Risk

• False Positives/Negatives: Dynamic includes such as @include($dynamicPartial) can still trigger false positives. Livewire attribute parsing risk is modestly reduced by 0.11.8, but complex Livewire components should remain a pilot validation target.
• Complex Template Logic: Heavy @php blocks, custom directives, and runtime-generated view data may not be fully analyzable. Risk is low for typical Blade usage but remains for highly dynamic templates.
• IDE Integration: The custom --error-format=blade output may not be natively parsed by all IDE plugins. CLI usage or PHPStan-native output remains the safer default.
• Performance Overhead: Blade analysis adds PHPStan execution cost. Large codebases should use parallel execution and exclude third-party or generated views where appropriate.
• Dependency on PHPStan: Bladestan is not useful without PHPStan. Adoption should be framed as “PHPStan + Bladestan = Blade safety net,” not as a standalone tool.
• Patch Compatibility Risk: 0.11.8 appears low risk because it is patch-level and bug-fix oriented. Teams pinned to ^0.11 can adopt it through normal dependency updates.

Key Questions

1. PHPStan Adoption
   • Is PHPStan already used? If not, is the team willing to adopt it as a prerequisite?
   • Are existing PHPStan configurations likely to conflict with Bladestan’s rules?
2. Template Complexity
   • What percentage of Blade templates use dynamic includes, custom directives, or complex @php blocks?
   • Do we have Livewire templates with bracketed attribute values or camelized attribute keys affected by the 0.11.8 fixes?
3. CI/CD Integration
   • Should Bladestan be a blocking CI check or informational-only during rollout?
   • How will errors be surfaced: GitHub PR comments, CI logs, Slack alerts, or IDE integration?
4. Error Handling
   • What false-positive threshold is acceptable before enabling blocking checks?
   • Should specific rules, such as undefinedMethod, be ignored for selected classes or directories?
5. Maintenance
   • Who owns PHPStan/Bladestan upgrades if Laravel, Livewire, or PHP versions advance?
   • Should the package be pinned to ^0.11 and updated through normal patch/minor review?

Integration Approach

Stack Fit

• PHPStan Integration
  • Preferred: install via PHPStan’s extension installer.
  • Fallback: include manually in phpstan.neon:

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

  • Customize via a project-specific PHPStan config such as phpstan-blade.neon.
• Laravel Compatibility
  • Bladestan reads Laravel view paths from configuration rather than relying on hardcoded paths.
  • Supports standard Blade views, mail templates, Livewire component views, and dynamic includes.
  • 0.11.8 improves Livewire attribute handling, which strengthens stack fit for Livewire-heavy applications.
• Toolchain Synergy
  • Run alongside existing PHPStan rules:

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

  • Continue leveraging PHPStan result caching and prior cache invalidation behavior.

Migration Path

1. Assessment Phase
   • Audit existing Blade templates with a trial run:

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

   • Review false positives and adjust level or ignoreErrors.
2. Configuration
   • Add Bladestan under require-dev:

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

   • Configure PHPStan inclusion via extension installer or manual include.
3. CI/CD Integration
   • Add a CI step:

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

   • Start non-blocking, then promote to blocking after false positives are tuned.
4. Developer Workflow
   • Add a local script:

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

   • Educate developers on interpreting Blade-specific error output and line links.

Compatibility

• Laravel Versions: Officially supports Laravel 10–12. Laravel 9 may work but is untested.
• Livewire: Supports Livewire 3.3–4.0. 0.11.8 specifically improves Livewire attribute parsing and camelization behavior.
• PHP Versions: Requires PHP 8.1+, aligned with Laravel 10+.
• Template Types: Standard Blade views, mail templates, Livewire views, and dynamic includes.
• Exclusions: Exclude generated or third-party views via PHPStan paths / excludePaths:

  excludePaths:
      - vendor
      - storage/framework/views
  

• Release Compatibility: 0.11.8 is patch-level and should be compatible with existing ^0.11 configuration.

Sequencing

1. Phase 1: Pilot
   • Run Bladestan in non-blocking mode for 1–2 sprints.
   • Include Livewire templates with bracketed attribute values and camelized attributes in validation.
2. Phase 2: CI Enforcement
   • Gradually enable blocking checks for critical templates or high-risk paths.
   • Tune PHPStan levels and ignore rules based on pilot results.
3. Phase 3: Full Integration
   • Add PR checks, local developer scripts, and team documentation.
   • Monitor false positives and update Bladestan through normal patch/minor dependency review.

Operational Impact

Maintenance

• Low Effort: Bladestan is MIT-licensed and actively maintained. Pin to ^0.11 and review patch/minor releases normally.
• Upgrade Path: 0.11.8 is a low-risk patch. No configuration changes are required.
• Ownership: Assign a maintainer for PHPStan/Bladestan upgrades and CI configuration.

Support

• Primary Support: Upstream package maintainers and PHPStan documentation.
• Internal Support: The team owning static analysis/CI should own triage of false positives and configuration tuning.
• Release Support: Patch releases such as 0.11.8 should be adopted through routine dependency update review, with special attention to Livewire and import-related templates.

Scaling

• Execution Cost: Use --parallel and PHPStan caching for large codebases.
• Scope Control: Exclude generated, vendor, or low-value templates to keep CI times reasonable.
• CI Strategy: Run Bladestan in parallel with existing PHPStan jobs where CI infrastructure permits.

Failure Modes

• False Positives Blocking CI: Mitigate by starting non-blocking, tuning ignoreErrors, and gradually promoting checks.
• Dynamic Template Limits: Dynamic includes and runtime-generated data may remain partially unanalyzable; document exceptions.
• IDE Format Gaps: Custom Blade error format may not render in all IDE plugins; default to CLI or PHPStan-native output where needed.
• Dependency Breakage: PHPStan major upgrades or Laravel/Livewire version changes may require Bladestan updates; pin versions and review upgrade notes.
• Livewire Parsing Edge Cases: 0.11.8 fixes several known cases, but complex Livewire attributes should remain in regression testing.

Ramp-up

• Phase 1: Run non-blocking and collect baseline errors/false positives.
• Phase 2: Tune configuration and fix high-risk Blade errors.
• Phase 3: Enable blocking CI checks for critical paths.
• Phase 4: Expand coverage and educate developers on local usage.
• Enablement Materials: Short runbook covering PHPStan levels, Bladestan error interpretation, exclusion patterns, and escalation for false positives.