Laravel Blade X Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-blade-x
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Spatie\BladeX\BladeServiceProvider"
   

2. First Component: Create a Blade file at resources/views/components/my-alert.blade.php:

   <div class="alert alert-{{ $type }}">
       {{ $slot ?? $message }}
   </div>
   

   Use it in a view:

   <x-my-alert type="error" message="Something went wrong!" />
   

3. Key Directories:

   • Components live in resources/views/components/ (auto-discovered).
   • Default namespace: x- prefix (e.g., <x-my-alert />).

Implementation Patterns

Core Workflows

1. Component Structure:

   • Basic: Single file (alert.blade.php → <x-alert />).
   • Multi-file: Split into alert.blade.php (view) + alert.php (logic).

     // resources/views/components/alert.php
     public function mount($type) {
         $this->type = $type;
     }
     

2. Slot Content:

   <x-card>
       <h1>Title</h1>
       <p>Content</p>
   </x-card>
   

   <!-- card.blade.php -->
   <div class="card">
       {{ $slot }}
   </div>
   

3. Dynamic Attributes:

   <x-button class="btn-primary" :disabled="$disabled" />
   

   <!-- button.blade.php -->
   <button {{ $attributes }}>
       {{ $slot }}
   </button>
   

4. Reusable Logic: Use mount() in PHP components to pre-process data:

   public function mount($user) {
       $this->fullName = $user->name;
   }
   

5. Conditional Rendering:

   @if($show)
       <x-component />
   @endif
   

Integration Tips

• Form Components: Combine with Laravel Collective or Livewire.

  <x-form.input type="email" name="email" />
  

• Layouts: Use nested components for consistent headers/footers.
• Testing: Mock components in PHPUnit:

  $this->blade->render('<x-alert />', ['type' => 'success']);
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts:

   • Avoid naming conflicts with Laravel’s native components (e.g., <x-auth />).
   • Use explicit namespaces if needed:

     <x-namespace::component />
     

2. Caching Issues:

   • Clear Blade cache after adding new components:

     php artisan view:clear
     

3. Deprecated in Laravel 7+:

   • Migrate to native Blade components:

     <!-- Old (Blade-X) -->
     <x-alert />
     
     <!-- New (Laravel 7+) -->
     @component('alert') @endcomponent
     

4. Slot Fallback:

   • $slot ?? $default may not work as expected; use @isset($slot) for checks.

Debugging

• Missing Components:

  • Verify the file exists in resources/views/components/ (case-sensitive).
  • Check for typos in the component name (e.g., <x-Alert /> vs. alert.blade.php).

• Attribute Binding:

  • Use :attribute for dynamic values (e.g., :id="$id").
  • Raw attributes: {{ $attributes->merge(['data-test' => 'true']) }}.

Extension Points

1. Custom Directories: Configure in config/blade-x.php:

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

2. Global Components: Register in AppServiceProvider:

   Blade::component('alert', AlertComponent::class);
   

3. Stacks: Use @stack for deferred content:

   <x-layout>
       @stack('scripts')
   </x-layout>
   

   @push('scripts')
       <script>...</script>
   @endpush
   

4. Legacy Migration:

   • Replace @include with <x-component />.
   • Convert data arrays to attributes:

     <!-- Old -->
     @include('alert', ['type' => 'error'])
     
     <!-- New -->
     <x-alert type="error" />