Blade Capture Directive Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require ryangjchandler/blade-capture-directive
   

   No additional configuration is required—just use the directive in your Blade templates.

2. First Use Case:

   @capture('header')
       <h1>Welcome</h1>
       <p>This is a reusable header.</p>
   @endcapture
   
   @header
   

   This renders the captured content where @header is invoked.

3. Where to Look First:

   • Package README (if available).
   • Blade template files for @capture/@endcapture usage examples.
   • Laravel’s resources/views directory for immediate testing.

Implementation Patterns

Common Workflows

1. Reusable Components: Use @capture to define modular sections (e.g., headers, footers, alerts) and reuse them across views without duplicating markup.

   @capture('alert', ['type' => 'success'])
       <div class="alert alert-{{ $type }}">{{ $slot }}</div>
   @endcapture
   
   @alert('User saved!')
   

2. Dynamic Content Injection: Pass variables into captured blocks via @capture arguments:

   @capture('user-card', $user)
       <div class="card">
           <img src="{{ $user->avatar }}">
           <h3>{{ $user->name }}</h3>
       </div>
   @endcapture
   
   @user-card($currentUser)
   

3. Conditional Rendering: Combine with Blade’s @if for context-aware partials:

   @capture('sidebar')
       @if(auth()->check())
           <nav>...</nav>
       @endif
   @endcapture
   

4. Layout Integration: Use in master layouts to avoid repetition:

   @extends('layouts.app')
   
   @section('content')
       @capture('meta')
           <meta name="description" content="{{ $pageDescription }}">
       @endcapture
   
       @meta
       {{ $slot }}
   @endsection
   

Integration Tips

• Avoid Overuse: Reserve @capture for truly reusable snippets. Overuse can reduce readability.
• Naming Conventions: Use descriptive names (e.g., @capture('dashboard-header')).
• Pair with Components: Combine with Laravel’s @component for complex logic:

  @capture('modal-trigger')
      <button @click="openModal">{{ $label }}</button>
  @endcapture
  
  <x-modal>
      @modal-trigger('Delete')
      <!-- Modal content -->
  </x-modal>
  

Gotchas and Tips

Pitfalls

1. Scope Leaks: Variables defined inside @capture are not automatically available outside. Pass them explicitly:

   @capture('stats', $metrics)
       <p>Users: {{ $metrics['users'] }}</p>
   @endcapture
   

2. Nested Directives: Avoid nesting @capture inside other directives (e.g., @foreach). It can lead to unexpected output or errors.

3. Caching Quirks: If using Blade caching (php artisan view:cache), recapture partials after changes:

   php artisan view:clear
   

4. Dynamic Names Collisions: Dynamically named captures (e.g., @capture($dynamicName)) may conflict. Prefer static names for clarity.

Debugging

• Check for Typos: Ensure @capture and @endcapture are properly closed.
• Inspect Output: Use @dump inside @capture to debug variables:

  @capture('debug-data', $data)
      @dump($data)
  @endcapture
  

• Disable Caching: Temporarily disable Blade caching to test changes:

  // config/view.php
  'cache' => env('APP_DEBUG'),
  

Extension Points

1. Custom Directives: Extend the package by creating your own directives (e.g., @slot-capture for named slots):

   // app/Providers/BladeServiceProvider.php
   Blade::directive('slot-capture', function ($name) {
       return "<?php echo \$__env->startCapture(); ?>@capture({$name})";
   });
   

2. Global Variables: Inject global variables into captures via a service provider:

   Blade::composer('*', function ($view) {
       $view->with('globalVar', 'value');
   });
   

3. Testing: Mock captures in PHPUnit:

   $this->blade->share('capturedContent', fn() => '<p>Mocked</p>');
   $this->blade->render('@capturedContent');