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 error reporting. This ensures consistency with the broader static analysis ecosystem and avoids redundant tooling.
• Laravel Ecosystem Alignment: Designed specifically for Laravel’s Blade templating engine, it addresses a critical pain point—runtime errors caused by undefined methods/variables in templates—by shifting validation left. Supports modern Laravel features (Livewire, Symfony components, facades) and aligns with Laravel’s dependency injection and view resolution patterns.
• Non-Invasive: Operates purely at the static analysis layer, requiring no changes to runtime code, Blade compiler, or Laravel’s core. Ideal for CI/CD integration without production impact.
• Extensibility: Built on PHPStan’s extension system, allowing future customization (e.g., adding project-specific Blade rules) without forking the package.

Technical Risk

• False Positives/Negatives: Blade templates often use dynamic data (e.g., @foreach($dynamicData as $item)), which may trigger false positives. Mitigation: Configure phpstan.neon to ignore known edge cases or suppress specific rules.
• Livewire/Component Complexity: Advanced Livewire components or dynamic Blade directives (e.g., @stack) may not be fully analyzed. Risk is low given the package’s active maintenance and recent Livewire 4.0 support.
• PHPStan Version Lock: Tied to PHPStan 2.0+ (per changelog). Ensure your project’s PHPStan version is compatible (check PHPStan’s upgrade guide).
• Template Path Resolution: Relies on Laravel’s view path configuration. Misconfigured view.paths or custom paths may require manual adjustments in extension.neon.

Key Questions

1. PHPStan Adoption: Is PHPStan already used in the project? If not, assess the effort to onboard it (e.g., configuration, rule set tuning).
2. CI/CD Integration: Where will Bladestan run? (e.g., pre-commit hooks, build stage). Requires defining thresholds for error severity (e.g., fail on "high" severity only).
3. Template Diversity: Are templates highly dynamic (e.g., user-generated content, heavy client-side rendering)? If so, evaluate the signal-to-noise ratio of static analysis.
4. Livewire/Component Usage: Does the project use complex Livewire components or custom Blade directives? Validate coverage with the package’s Livewire support docs.
5. Performance Impact: For large codebases, measure the runtime of phpstan analyze with Bladestan enabled. Cache invalidation (per PR #174) may require tuning.
6. Error Handling: How will teams address suppressed errors (e.g., @phpstan-ignore-next-line)? Document a process to avoid "ignoring" critical issues.

Integration Approach

Stack Fit

• PHPStan-Centric: Bladestan is a PHPStan extension, so integration is optimal if:
  • PHPStan is already part of the stack (e.g., for PHP code analysis).
  • The team is familiar with PHPStan’s rule sets and configuration (phpstan.neon).
• Laravel-Specific: Works exclusively with Laravel’s Blade templates, making it a natural fit for Laravel monorepos or projects using Blade for views/emails.
• Complementary Tools: Pairs well with:
  • Laravel Pint: For Blade syntax/style consistency.
  • Psalm/Nunomaduro/Phpinsights: For broader static analysis.
  • Laravel Telescope: For runtime debugging (Bladestan reduces Telescope noise by catching issues early).

Migration Path

1. Prerequisite Check:
   • Verify PHPStan is installed (composer show phpstan/phpstan).
   • Ensure Laravel ≥10 and PHP ≥8.1 (check composer.json).
2. Installation:

   composer require --dev tomasvotruba/bladestan
   

3. Configuration:
   • Option A (Recommended): Use PHPStan’s extension installer:

     vendor/bin/phpstan extension:install tomasvotruba/bladestan
     

   • Option B: Manually include in phpstan.neon:

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

4. Customization (Optional):
   • Override default rules in phpstan.neon:

     services:
         - Bladestan\BladeRuleSetLevel
     

   • Configure error formatting:

     vendor/bin/phpstan analyze --error-format=blade
     

5. CI/CD Setup:
   • Add to build script (e.g., .github/workflows/ci.yml):

     - name: Run Bladestan
       run: vendor/bin/phpstan analyze --level=max --error-format=blade
     

   • Define failure conditions (e.g., exit on "high" severity only).

Compatibility

• Laravel Versions: Tested on Laravel 10–12 (per changelog). For older versions, check GitHub issues or fork the package.
• PHPStan Versions: Requires PHPStan 2.0+. Verify compatibility with vendor/bin/phpstan --version.
• Blade Features: Supports:
  • Directives: @extends, @include, @includeIf, @foreach, @component, etc.
  • Livewire: Components, attributes, and props.
  • Facades: View::make(), Response::view().
  • Non-HTML templates: Emails (e.g., Mailable content()).
• Edge Cases: May require manual configuration for:
  • Custom Blade directives.
  • Dynamic template paths (e.g., view()->first()).
  • Heavy use of @php or @verbatim directives.

Sequencing

1. Pilot Phase:
   • Run Bladestan locally on a subset of templates (e.g., /resources/views/auth).
   • Review false positives/negatives and adjust phpstan.neon or suppress rules as needed.
2. Incremental Rollout:
   • Add to CI/CD for a single branch (e.g., feature/bladestan).
   • Monitor build times and error volume.
3. Full Adoption:
   • Integrate into pre-commit hooks (e.g., via Laravel Pint’s hooks).
   • Document the new workflow in the team’s static analysis guide.

Operational Impact

Maintenance

• Low Effort: Minimal maintenance required post-integration. Updates are released ~monthly (per GitHub activity).
• Dependency Management:
  • Pin the package version in composer.json to avoid breaking changes:

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

  • Monitor PHPStan major updates for compatibility (e.g., PHPStan 3.0).
• Rule Updates: Rarely need customization unless using unsupported Blade features. Contribute fixes upstream if needed.

Support

• Troubleshooting:
  • Common Issues:
    • False positives: Adjust phpstan.neon or suppress rules (e.g., phpstan-ignore-line).
    • Path resolution: Ensure view.paths in config/view.php is correct.
    • Livewire errors: Check Livewire compatibility notes.
  • Debugging: Use --debug flag for verbose output:

    vendor/bin/phpstan analyze --debug --error-format=blade
    

• Documentation:
  • Internal Runbook: Document:
    • How to run Bladestan locally/remotely.
    • How to suppress errors (with examples).
    • CI/CD failure modes (e.g., "high" vs. "medium" severity).
  • Onboarding: Add a section to the team’s static analysis guide covering Bladestan’s output format and clickable errors.

Scaling

• Performance:
  • Analysis Time: Bladestan adds ~10–30% overhead to PHPStan runs for large projects. Mitigate by:
    • Running in parallel with other static analysis tools.
    • Caching results (PHPStan’s cache is invalidated on template changes, per PR #174).
  • Memory Usage: Minimal impact; PHPStan’s memory limits apply.
• Large Codebases:
  • Incremental Analysis: Use PHPStan’s --generate-baseline to ignore existing issues during initial adoption.
  • Template Prioritization: Focus on high-traffic templates first (e.g., `/resources/views/home.blade.php