Livewire Datatables Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require mediconesystems/livewire-datatables
   

   For Laravel 9, also run:

   composer require psr/simple-cache:^1.0 maatwebsite/excel
   

2. Publish Assets (if needed):

   php artisan vendor:publish --provider="MedicOneSystems\LivewireDatatable\LivewireDatatableServiceProvider"
   

3. Basic Usage: Create a Livewire component:

   php artisan make:livewire Admin/UserTable
   

4. Define Datatable in Component:

   use MedicOneSystems\LivewireDatatable\LivewireDatatable;
   
   public function datatable()
   {
       return LivewireDatatable::create()
           ->setModel(User::class)
           ->addColumn('name')
           ->addColumn('email')
           ->setPrimaryKey('id')
           ->setSearch(['name', 'email']);
   }
   

5. Render in Blade:

   <livewire:admin.user-table />
   

First Use Case

Build a user management table with search, sorting, and pagination:

public function datatable()
{
    return LivewireDatatable::create()
        ->setModel(User::class)
        ->addColumn('name')
        ->addColumn('email')
        ->addColumn('created_at', 'Date')
        ->setPrimaryKey('id')
        ->setSearch(['name', 'email'])
        ->setPerPage(10);
}

Implementation Patterns

Core Workflows

1. Data Binding

• Model Binding: Use setModel() to bind to an Eloquent model.

  ->setModel(User::class)
  

• Query Builder Binding: Use setQuery() for raw queries.

  ->setQuery(User::where('active', 1))
  

2. Column Configuration

• Basic Columns:

  ->addColumn('name')
  ->addColumn('email')
  

• Formatted Columns (using callbacks):

  ->addColumn('name', 'Name', function ($value) {
      return ucfirst($value);
  })
  

• Computed Columns:

  ->addColumn('full_name', 'Full Name', function ($row) {
      return $row->first_name . ' ' . $row->last_name;
  })
  

3. Filtering

• Simple Search:

  ->setSearch(['name', 'email'])
  

• Boolean Filter:

  ->addBooleanFilter('active')
  

• Date Filter:

  ->addDateFilter('created_at')
  

• Select Filter (dropdown):

  ->addSelectFilter('role', ['admin', 'user', 'moderator'])
  

4. Sorting

• Default Sort:

  ->setDefaultSort('name', 'asc')
  

• Computed Sort (for non-database columns):

  ->addSort('full_name', 'Full Name')
  

5. Pagination & Actions

• Per-Page Control:

  ->setPerPage(20)
  

• Bulk Actions:

  ->addBulkAction('Delete', 'deleteSelected', 'danger')
  

  public function deleteSelected()
  {
      User::whereIn('id', $this->getSelected())->delete();
  }
  

6. Column Groups

• Group related columns:

  ->addColumnGroup('Contact', [
      'email',
      'phone',
  ])
  

7. Exporting

• Add export buttons:

  ->addExport('CSV')
  ->addExport('Excel')
  

Integration Tips

Livewire Component Structure

// UserTable.php
public function datatable()
{
    return LivewireDatatable::create()
        ->setModel(User::class)
        ->addColumn('name')
        ->addColumn('email')
        ->addColumn('created_at', 'Date')
        ->setPrimaryKey('id')
        ->setSearch(['name', 'email'])
        ->setPerPage(10);
}

public function deleteSelected()
{
    User::whereIn('id', $this->getSelected())->delete();
    session()->flash('message', 'Users deleted successfully.');
}

Blade Template

<div>
    @if (session()->has('message'))
        <div class="mb-4 p-4 bg-green-100 text-green-800">
            {{ session('message') }}
        </div>
    @endif

    <livewire:admin.user-table />
</div>

Complex Query Builder

For advanced filtering (e.g., combined conditions):

public function datatable()
{
    return LivewireDatatable::create()
        ->setModel(User::class)
        ->addColumn('name')
        ->addColumn('email')
        ->setQuery(function ($query) {
            return $query->where('active', true)
                        ->whereHas('roles', function ($q) {
                            $q->where('name', 'admin');
                        });
        });
}

Gotchas and Tips

Pitfalls

1. Tailwind/Alpine Dependencies:

   • Ensure tailwindcss and alpinejs are properly installed and configured.
   • If styles don’t load, check your resources/js/app.js for Alpine initialization:

     import Alpine from 'alpinejs';
     window.Alpine = Alpine;
     Alpine.start();
     

2. Model vs. Query Builder:

   • If using setQuery(), ensure the query returns the expected columns (or use addColumn with callbacks).
   • Avoid mixing setModel() and setQuery() in the same datatable.

3. Primary Key Mismatch:

   • If setPrimaryKey() is omitted, the datatable defaults to id. Ensure this matches your model’s primary key.

4. Bulk Actions:

   • Always validate $this->getSelected() to avoid SQL errors:

     if (!$this->getSelected()) {
         session()->flash('error', 'No items selected.');
         return;
     }
     

5. Performance with Large Datasets:

   • Use setPerPage() to limit initial load size.
   • For complex queries, add indexes to filtered columns.

6. Column Naming Conflicts:

   • If a column name conflicts with a method (e.g., created_at), use aliases:

     ->addColumn('created_at', 'Date Created')
     

Debugging

1. Query Logs: Enable Laravel query logging to inspect generated SQL:

   \DB::enableQueryLog();
   $this->datatable()->getQuery()->toSql();
   dd(\DB::getQueryLog());
   

2. Livewire Hooks: Use mount() or updated() to debug component state:

   public function mount()
   {
       \Log::info('Datatable mounted', $this->datatable()->getQuery()->toSql());
   }
   

3. Alpine/JS Issues:

   • Check browser console for Alpine errors.
   • Ensure no duplicate Alpine initializations in your layout.

Tips

1. Reusable Datatables: Create a base component for shared functionality:

   // BaseDatatable.php
   public function configure()
   {
       return LivewireDatatable::create()
           ->setPerPage(15)
           ->setSearch(['name', 'email'])
           ->addExport('CSV');
   }
   

2. Dynamic Columns: Load columns dynamically based on user roles:

   if (auth()->user()->isAdmin()) {
       $datatable->addColumn('deleted_at', 'Deleted At');
   }
   

3. Custom Filters: Extend the filter system with custom logic:

   ->addFilter('custom_filter', function ($query, $value) {
       return $query->where('status', $value);
   })
   

4. Tailwind Styling: Override default styles by publishing the config:

   php artisan vendor:publish --tag=livewire-datatables-config
   

   Then customize resources/css/livewire-datatables.css.

5. Localization: Use Laravel’s localization features for filter labels:

   ->addSelectFilter('role', ['admin', 'user'], function () {
       return [
           'admin' => __('Admin'),
           'user' => __('User'),
       ];
   })
   

6. Testing: Use Livewire’s testing helpers to assert datatable behavior:

   $this->livewire(UserTable::class)
       ->assertDispatchedBrowserEvent('datatable-updated');
   

7. Caching: For static data, cache the query result:

   ->setQuery(function ($query) {
       return cache()->remember('users.datatable', now()->addHours(1), function () {