Table Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require artflow-studio/table
   

   The package auto-registers with Laravel (no manual service provider registration needed).

2. First Use Case: Basic Table Create a Livewire component with the @AFtable directive:

   // app/Livewire/UsersTable.php
   use ArtflowStudio\Table\Traits\Table;
   
   class UsersTable extends LivewireComponent
   {
       use Table;
   
       public function table()
       {
           return User::query();
       }
   
       public function columns()
       {
           return [
               'id' => 'ID',
               'name' => 'Name',
               'email' => 'Email',
           ];
       }
   }
   

   Render it in a Blade view:

   @AFtable('livewire:users-table')
   

3. Where to Look First

   • Generator Tool: Visit /aftable/generator for interactive docs and code snippets.
   • Package Docs: Focus on the Table trait and its methods (table(), columns(), filters()).
   • Example Components: Check the vendor/artflow-studio/table/src/Examples directory for real-world usage patterns.

Implementation Patterns

Core Workflows

1. Model-Based Tables

   public function table()
   {
       return User::query()
           ->with(['posts' => fn($q) => $q->limit(1)]) // N+1 prevention
           ->when($this->search, fn($q) => $q->where('name', 'like', "%{$this->search}%"));
   }
   

2. Static/Array Mode

   public function table()
   {
       return collect([
           ['id' => 1, 'name' => 'John'],
           ['id' => 2, 'name' => 'Jane'],
       ]);
   }
   

3. Column Customization

   • Basic Columns:

     return ['name', 'email'];
     

   • Raw Templates (Blade/Closures):

     return [
         'name' => fn(User $user) => view('custom.name', ['user' => $user]),
         'status' => fn(User $user) => "<span class='{$user->status_class}'>{$user->status}</span>",
     ];
     

   • Computed Columns:

     return [
         'full_name' => fn(User $user) => "{$user->first_name} {$user->last_name}",
     ];
     

4. Filters and Search

   public function filters()
   {
       return [
           'search' => ['type' => 'text', 'label' => 'Search'],
           'status' => ['type' => 'select', 'label' => 'Status', 'options' => ['active', 'inactive']],
           'date_range' => ['type' => 'dateRange', 'label' => 'Created At'],
       ];
   }
   

5. Events and Actions

   #[On('delete')]
   public function deleteUser($id)
   {
       User::find($id)->delete();
       $this->table->reset();
   }
   

   Blade:

   @AFtable('livewire:users-table')
       @column('actions')
           <button wire:click="delete({{ $user->id }})">Delete</button>
       @endcolumn
   @endAFtable
   

6. Export Integration

   public function export()
   {
       return $this->table->export('csv');
   }
   

   Blade:

   <button wire:click="export">Export CSV</button>
   

Integration Tips

• Tailwind/Bootstrap: Use the theme() method to customize classes:

  public function theme()
  {
      return [
          'table' => 'bg-white border',
          'th' => 'bg-gray-50',
          'td' => 'px-4 py-2',
      ];
  }
  

• Lazy Loading: For large datasets, use #[Computed] to cache queries:

  #[Computed]
   public function table()
   {
       return User::query()->paginate(10);
   }
  

• Reusability: Extend the Table trait in a base component for shared logic:

  class BaseTable extends LivewireComponent
  {
      use Table;
  
      public function table()
      {
          return $this->model::query();
      }
  }
  

Gotchas and Tips

Pitfalls

1. N+1 Queries

   • Issue: Forgetting to eager-load relations in table() can cause performance issues.
   • Fix: Always use with() or loadMissing():

     return User::with(['posts', 'comments'])->query();
     

2. Column Mismatch

   • Issue: If columns() returns keys that don’t match the query results, the table may render incorrectly.
   • Fix: Use fn() closures for dynamic or computed columns:

     return ['full_name' => fn(User $user) => "{$user->first_name} {$user->last_name}"];
     

3. Livewire State Persistence

   • Issue: Filters/search terms may not persist after page reloads if not properly bound.
   • Fix: Declare public properties for filters:

     public $search;
     public $status = 'active';
     

4. Blade Raw Output

   • Issue: Using {!! !!} in raw columns can lead to XSS vulnerabilities.
   • Fix: Sanitize user-generated content or use |escape:

     return ['description' => fn(User $user) => e($user->description)];
     

5. Generator Tool Limitations

   • Issue: The /aftable/generator tool may not reflect all customizations (e.g., themes).
   • Fix: Manually override methods like theme() or columns().

Debugging

• Query Logging: Enable Laravel’s query logging to verify N+1 prevention:

  \DB::enableQueryLog();
  $this->table->toBase()->get();
  \Log::info(\DB::getQueryLog());
  

• Livewire State: Use dd($this->all()) to inspect component state.
• Blade Errors: Check for syntax errors in raw columns by temporarily replacing them with static strings.

Configuration Quirks

1. Default Sorting

   • Override with defaultSort():

     public function defaultSort()
     {
         return ['name', 'asc'];
     }
     

2. Pagination

   • Customize via perPage():

     public function perPage()
     {
         return 20;
     }
     

3. Export Formats

   • Ensure dependencies are installed for PDF/Excel:

     composer require barryvdh/laravel-snappy maatwebsite/excel
     

Extension Points

1. Custom Directives Extend the @AFtable directive by publishing the package’s views:

   php artisan vendor:publish --tag=aftable.views
   

   Then modify resources/views/vendor/aftable/table.blade.php.

2. Hooks Use Livewire’s #[On] events for custom logic:

   #[On('tableInitialized')]
   public function onTableInitialized()
   {
       // Run after table loads
   }
   

3. Static Methods Access the table instance via $this->table for advanced use cases:

   #[On('rowClick')]
   public function handleRowClick($row)
   {
       $this->table->setSelected($row['id']);
   }