Bladestan Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

   composer require --dev tomasvotruba/bladestan
   

   Keep it in require-dev so template analysis runs in local checks and CI without becoming a production dependency.

2. Configuration:

   • If you use PHPStan’s extension installer, Bladestan should be auto-configured.
   • Otherwise, include it manually in phpstan.neon:

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

3. First run:

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

   This surfaces Blade template errors with template paths and line numbers, for example:

   Line 15 app/Views/post_codex.blade.php: Call to undefined method App\Entity\Post::getContent().
   

First Use Case: Catching Undefined Methods in Blade

A Blade template calls a method that does not exist on the model:

{{ $post->getContent() }}

Run:

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

Fix by either adding getContent() to Post or updating the template to use the correct property/method, e.g. {{ $post->content }}.

Implementation Patterns

Daily Workflow Integration

1. Pre-commit hooks: Run Bladestan before committing template changes:

   # .husky/pre-commit
   vendor/bin/phpstan analyze --error-format=blade --level=5
   

2. CI/CD pipeline: Block template regressions in CI:

   # .github/workflows/ci.yml
   - name: Run Bladestan
     run: vendor/bin/phpstan analyze --error-format=blade --level=5
   

3. IDE integration: Use PHPStan’s IDE integrations to get faster feedback while editing PHP and Blade-adjacent code. Configure the IDE integration to use the same PHPStan config as CI.

Advanced Patterns

1. Customizing PHPStan Rules for Blade

Configure PHPStan paths and ignores in phpstan.neon:

parameters:
    level: 5
    paths:
        - app
        - resources/views
    excludePaths:
        - tests

Use project-level PHPStan ignores for known false positives rather than weakening the whole analysis level.

2. Analyzing Specific Templates

Target critical templates such as emails or admin views:

vendor/bin/phpstan analyze --error-format=blade resources/views/emails resources/views/admin

3. Livewire Component Validation

Bladestan can analyze Livewire component templates:

<!-- resources/views/livewire/counter.blade.php -->
<div>Count: {{ $count }}</div>

As of 0.11.8, Livewire tag attribute keys are camelized before component PHP is generated, and component data is no longer truncated when attribute values contain brackets. Upgrade to 0.11.8+ if you analyze Livewire templates with kebab-case attributes or bracketed attribute data.

4. Combining with Other Tools

• Use Bladestan for static analysis and Blade formatting/linting tools for style.
• Run analysis after formatting so both checks use the final template contents:

  ./vendor/bin/pint && ./vendor/bin/phpstan analyze --error-format=blade
  

Integration Tips

1. Laravel packages: Ensure package views are discoverable through your package’s Laravel metadata:

   "extra": {
       "laravel": {
           "views": "resources/views"
       }
   }
   

2. Dynamic Blade includes: For @include($dynamicView), static analysis may not resolve the template. Prefer static includes where possible, or validate the dynamic view name at the controller level.

3. Mailables: Bladestan can analyze mail templates referenced from Mailables:

   // app/Mail/OrderShipped.php
   public function build()
   {
       return $this->view('emails.orders.shipped');
   }
   

   Run analysis to catch undefined data passed to resources/views/emails/orders/shipped.blade.php.

Gotchas and Tips

Pitfalls

1. False positives with dynamic data: Dynamic or loosely typed data may be flagged incorrectly. Cast or normalize data before passing it to the view:

   public function show(User $user)
   {
       return view('user.profile', [
           'userData' => $user->data instanceof Arrayable ? $user->data->toArray() : [],
       ]);
   }
   

2. Caching issues: PHPStan result caches can become stale when templates change. If results look out of date, rerun without cache:

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

3. Livewire component namespaces: If Livewire components are not resolved, verify your Livewire component namespace configuration matches the application namespace.

4. Non-HTML templates: Non-HTML templates such as .txt or .md mail templates may not be fully analyzed. Exclude them if they cause noise, or validate required data explicitly in PHP.

5. Livewire attribute parsing (fixed in 0.11.8): If you are on an older release, Livewire attributes with bracketed values or kebab-case keys may produce incomplete or incorrectly generated component PHP. Upgrade to 0.11.8+ before debugging those cases as application issues.

Debugging Tips

1. Verbose output:

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

2. Isolate a template:

   vendor/bin/phpstan analyze --error-format=blade resources/views/post_codex.blade.php
   

3. Formatter fallback: If the Blade formatter behaves unexpectedly with your PHPStan version, run normal PHPStan output and filter for rendered template references:

   vendor/bin/phpstan analyze | grep -A 2 -B 2 "rendered in:"
   

Extension Points

1. Custom PHPStan rules: Add project-specific rules for Blade-related conventions and register them in phpstan.neon.

2. Ignoring specific errors: Use PHPStan’s standard ignore mechanism for known false positives, scoped as narrowly as possible:

   parameters:
       ignoreErrors:
           - '#Call to an undefined method App\\Models\\Post::legacyMethod\(\)#'
   

3. Post-processing errors: Use PHPStan’s error formatter API if you need custom Blade error output. Register the formatter and run PHPStan with your custom --error-format.