Orchid Livewire Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require livewire/livewire alexsabur/orchid-livewire:^5.3
   php artisan vendor:publish --tag=orchid-livewire-assets
   

   Ensure you’re using a compatible Orchid version (12–14 for ^5.3).

2. First Use Case: Convert an Orchid Table or Screen to Livewire by extending Orchid\Livewire\LivewireTable or Orchid\Livewire\LivewireScreen:

   use AlexSabur\OrchidLivewire\LivewireTable;
   
   class MyLivewireTable extends LivewireTable
   {
       public function columns(): array
       {
           return [
               'id' => 'ID',
               'name' => 'Name',
           ];
       }
   }
   

   Register the component in routes/web.php:

   Route::get('/livewire-table', \App\Livewire\MyLivewireTable::class);
   

3. Key Files:

   • app/Livewire/ – Store custom Livewire components.
   • resources/views/vendor/orchid-livewire/ – Override default views (if published).

Implementation Patterns

Core Workflows

1. Table Integration:

   • Extend LivewireTable for CRUD tables with built-in pagination, sorting, and filtering.
   • Override query() to customize Eloquent queries:

     public function query(): Builder
     {
         return Model::query()->where('active', true);
     }
     

   • Use withSearch() for global search:

     public function columns(): array
     {
         return [
             'name' => (new TextColumn('name'))
                 ->withSearch()
                 ->sortable(),
         ];
     }
     

2. Screen Integration:

   • Extend LivewireScreen for forms or dashboards:

     class UserProfile extends LivewireScreen
     {
         public $name;
     
         public function mount()
         {
             $this->name = auth()->user()->name;
         }
     
         public function updateProfile()
         {
             auth()->user()->update(['name' => $this->name]);
         }
     }
     

   • Leverage Orchid’s form helpers (e.g., Input, Select) within Livewire templates.

3. Hybrid Approach:

   • Mix Orchid’s admin panel with Livewire for dynamic UI:

     // In a Screen
     public function render()
     {
         return view('livewire.my-component')
             ->layout('orchid::layouts.main');
     }
     

4. Asset Management:

   • Publish assets to customize Livewire’s Alpine.js or Tailwind integration:

     php artisan vendor:publish --tag=orchid-livewire-assets
     

   • Override resources/views/vendor/orchid-livewire/table.blade.php for table-specific changes.

Integration Tips

• Authentication: Use Orchid’s auth middleware in Livewire components:

  public function mount()
  {
      $this->authorize('view-dashboard');
  }
  

• Dependencies: Inject Orchid services (e.g., Orchid\Platform\Dashboard) via constructor:

  public function __construct(public Dashboard $dashboard) {}
  

• Testing: Use Livewire’s testing helpers alongside Orchid’s:

  $this->livewire(MyLivewireTable::class)
       ->assertSee('Expected Text');
  

Gotchas and Tips

Pitfalls

1. Version Mismatches:

   • Orchid 1.x → orchid-livewire:^3.0
   • Orchid 11.x → orchid-livewire:^4.0
   • Orchid 12–14 → orchid-livewire:^5.3 Fix: Clear vendor/ and node_modules/ if upgrading.

2. Asset Conflicts:

   • Publishing both orchid-livewire and livewire assets may duplicate Alpine.js. Fix: Exclude one in webpack.mix.js or use mix.disableNotifications().

3. Livewire State Persistence:

   • Orchid’s session-based auth may interfere with Livewire’s state. Fix: Use protected $persistent = true; in components needing session persistence.

4. CSRF Token Issues:

   • Orchid’s CSRF middleware may block Livewire’s XHR requests. Fix: Ensure VerifyCsrfToken excludes Livewire routes:

     protected $except = [
         'livewire/*',
     ];
     

Debugging

• Livewire Hooks: Use wire:ignore on Orchid-specific elements (e.g., modals) to prevent reactivity conflicts.
• Logs: Check storage/logs/livewire.log for Livewire-specific errors.
• Blade Debugging: Add @debug($this) in Livewire templates to inspect component state.

Extension Points

1. Custom Columns: Extend AlexSabur\OrchidLivewire\Columns\Column for reusable column types:

   class StatusColumn extends Column
   {
       public function render()
       {
           return view('livewire::columns.status', ['value' => $this->value]);
       }
   }
   

2. Event Handling: Listen to Orchid events within Livewire:

   public function boot()
   {
       event(new \Orchid\Events\RegisteredUser());
   }
   

3. API Endpoints: Use Livewire’s wire:submit with Orchid’s API resources:

   public function save()
   {
       $resource = new UserResource(auth()->user());
       return response()->json($resource);
   }
   

4. Localization: Override translations in resources/lang/vendor/orchid-livewire/. Example:

   'livewire' => [
       'actions' => [
           'edit' => 'Custom Edit Text',
       ],
   ],