Bladestan Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tomasvotruba/bladestan --dev
   

2. Configure PHPStan: Add to phpstan.neon:

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

3. Run Analysis:

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

First Use Case

Debugging Undefined Blade Variables:

• Run phpstan analyze on a controller returning a view with missing data:

  return view('dashboard', ['user' => $user]); // Missing 'posts' key
  

• Output:

  ------ -----------------------------------------------------------
   Line   resources/views/dashboard.blade.php
  ------ -----------------------------------------------------------
   10     Undefined variable $posts.
          passed in: DashboardController.php:15
  ------ -----------------------------------------------------------
  

• Fix: Add $posts to the view data or update the template.

Implementation Patterns

Workflow Integration

1. CI/CD Pipeline: Add to phpstan job in GitHub Actions:

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

   • Best Practice: Fail builds on max level to enforce strict Blade validation.

2. Local Development:

   • Use phpstan analyze --error-format=blade in pre-commit hooks (e.g., with husky).
   • Shortcut: Create an alias in composer.json:

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

3. Livewire Component Validation:

   • Analyze props and dynamic components:

     <x-my-component :user="$user" /> <!-- Validates $user exists -->
     

   • Output: Flags missing props or invalid types.

4. Template Inheritance:

   • Detect missing @extends or @section definitions:

     @extends('layouts.app') <!-- Missing file or incorrect path -->
     

Advanced Patterns

1. Custom Error Filtering:

   • Suppress false positives in phpstan.neon:

     errorLevel[Bladestan\Rule\MissingTemplateRule] = ignore
     

2. Mail Template Analysis:

   • Validate email templates (e.g., resources/views/emails/welcome.blade.php) by ensuring they’re included in View::make() calls.

3. Dynamic Includes:

   • Analyze @include with dynamic paths:

     @include($templatePath) <!-- Validates $templatePath is a valid view -->
     

4. Shared Data Validation:

   • Check shared data in View::share():

     View::share('config', $config); // Validates $config is passed to all views
     

Gotchas and Tips

Common Pitfalls

1. Cache Invalidation:

   • Issue: PHPStan cache may not update after adding new Blade templates.
   • Fix: Run with --clear-cache or configure in phpstan.neon:

     cacheDirectory = ./phpstan-cache
     

2. Livewire Component Namespaces:

   • Issue: Livewire components not found if namespace is misconfigured.
   • Fix: Ensure livewire.component.namespace in config/livewire.php matches your components.

3. Dynamic Blade Logic:

   • Issue: Complex @if/@foreach conditions may not be fully analyzed.
   • Workaround: Simplify logic or use type hints in controllers.

4. False Positives:

   • Issue: $errors or $slot variables may trigger false alarms.
   • Fix: Exclude specific rules:

     errorLevel[Bladestan\Rule\UndefinedVariableRule] = ignore
     

Debugging Tips

1. Verbose Output:

   • Use --verbose to debug template parsing:

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

2. Line Number Accuracy:

   • Issue: Errors may point to incorrect lines in nested @include files.
   • Fix: Ensure all @include paths are absolute (e.g., @include('partials.header')).

3. PHPStan Version Conflicts:

   • Issue: Compatibility issues with PHPStan < 2.0.
   • Fix: Pin version in composer.json:

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

Extension Points

1. Custom Rules:

   • Extend Bladestan\Rule\* to add project-specific validation (e.g., required fields in forms).

2. Error Formatting:

   • Override the formatter in phpstan.neon:

     errorFormatter = Bladestan\ErrorFormatter\CustomFormatter
     

3. Template Paths:

   • Customize paths in config/view.php to include package views:

     'paths' => [
         resource_path('views'),
         base_path('vendor/package/views'),
     ],
     

4. Livewire Props:

   • Validate props dynamically by extending Bladestan\Livewire\LivewireExtension.