Blaze Laravel Package

Getting Started

Minimal Steps

1. Installation: Add Blaze via Composer:

   composer require livewire/blaze:^1.0
   

2. Enable for a component: Add @blaze directive to any anonymous Blade component:

   @blaze
   <button>{{ $slot }}</button>
   

3. Clear compiled views:

   php artisan view:clear
   

4. Verify: Test rendering performance with a loop of 25,000 components (expect ~90%+ speedup).

First Use Case

Optimize a frequently rendered component like a button or icon:

@blaze
@props(['type' => 'button'])
<button {{ $attributes->merge(['type' => $type]) }}>
    {{ $slot }}
</button>

Where to Look First

• Documentation: Blaze GitHub README (focus on "Limitations" and "Optimization Strategies").
• Benchmark: Compare rendering times with/without Blaze using Benchmark::dd() or Xdebug.
• Configuration: Start with @blaze directives before optimizing entire directories.

Implementation Patterns

Core Workflow

1. Incremental Adoption:

   • Begin with @blaze on high-impact components (e.g., buttons, modals, cards).
   • Gradually expand to directories using Blaze::optimize() in AppServiceProvider.

   Blaze::optimize()->in(resource_path('views/components/ui'));
   

2. Strategy Selection:

   • Default (Function Compiler): Use for 90% of cases (no config needed).
   • Memoization (@blaze(memo: true)): Apply to static components (icons, avatars) rendered repeatedly.
   • Folding (@blaze(fold: true)): Reserve for fully static components (e.g., decorative elements).

3. Directory Optimization:

   Blaze::optimize()
       ->in(resource_path('views/components/buttons'), memo: true)
       ->in(resource_path('views/components/icons'), fold: true)
       ->in(resource_path('views/components/legacy'), compile: false);
   

Integration Tips

• Livewire Components: Blaze works seamlessly with Livewire. No changes needed to Livewire-specific syntax (e.g., @entangle, $wire:model).
• Shared Data: Access $__env->shared('key') instead of relying on View::share().
• Testing: Use Blaze::shouldCompile() in tests to mock Blaze behavior:

  Blaze::shouldCompile(false); // Disable Blaze for tests
  

Advanced Patterns

• Conditional Blaze: Dynamically enable Blaze based on environment:

  @if(app()->environment('production'))
      @blaze
  @endif
  

• Hybrid Rendering: Mix Blaze and non-Blaze components in the same view (Blaze components must be rendered via <x-component> tags).
• Custom Directives: Extend Blaze by creating custom directives (e.g., @blaze(debug: true) for development).

Gotchas and Tips

Pitfalls

1. Global State in Folded Components:

   • Error: Folding components that use auth(), session(), or now() will break.
   • Fix: Exclude such components from folding or refactor to pass state via props.
   • Detection: Blaze throws exceptions during compilation if it detects unsafe global state.

2. Dynamic Props in Folded Components:

   • Error: Folding aborts if @props receive dynamic values (e.g., :color="$dynamicValue").
   • Fix: Use Function Compiler (@blaze) or refactor to static props.

3. Slots with Dynamic Content:

   • Error: Slots containing dynamic logic (e.g., @if) may not fold correctly.
   • Fix: Mark slots as unsafe or avoid folding:

     @blaze(fold: true)
     @slot('dynamic', unsafe: true)
     

4. View Composers/Creators:

   • Error: Blaze ignores View::composer() and View::creator().
   • Fix: Move shared data to @props or $__env->shared().

5. Cross-Boundary @aware:

   • Error: Data won’t propagate between Blade and Blaze components.
   • Fix: Ensure both parent/child use Blaze or pass data explicitly via props.

Debugging

• Compilation Errors: Check storage/framework/views for Blaze-generated PHP files. Errors often appear as BlazeException with hints.
• Performance Regression: Use Benchmark::dd() to isolate slow components:

  use Livewire\Benchmark;
  Benchmark::dd(fn() => view('component'));
  

• Memoization Issues: Verify cache keys with Memo::key('component', ['prop' => 'value']).

Configuration Quirks

1. Cache Invalidation:

   • Clear views after changing Blaze directives:

     php artisan view:clear
     

   • For folded components, also clear the cache:

     php artisan cache:clear
     

2. Folding Whitelisting:

   • Blaze skips folding for components with:
     • @stack directives.
     • @once blocks.
     • Complex control structures (e.g., @foreach with dynamic conditions).

3. Environment-Specific Behavior:

   • Folding is disabled in local environment by default (set BLEZE_FOLD=false in .env to override).

Extension Points

1. Custom Compilers:

   • Extend Livewire\Blaze\Compilers\Compiler to add support for custom Blade directives or syntax.

2. Memoization Backends:

   • Replace the default Memo implementation by binding a custom Livewire\Blaze\Memo instance in the service provider.

3. Folding Rules:

   • Override folding behavior by extending Livewire\Blaze\Folding\FoldingAnalyzer to add/remove folding restrictions.

4. Directive Macros:

   • Register custom @blaze arguments:

   Blaze::macro('debug', function () {
       return function ($view) {
           // Custom logic
       };
   });
   

   Usage:

   @blaze(debug: true)