Eloquenttable Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require stevebauman/eloquenttable:1.1.*
   

   For Laravel 5, add the service provider to config/app.php:

   'Stevebauman\EloquentTable\EloquentTableServiceProvider',
   

   Publish the config (optional but recommended for customization):

   php artisan vendor:publish --provider="Stevebauman\EloquentTable\EloquentTableServiceProvider"
   

2. Apply the Trait: Add TableTrait to your Eloquent model:

   use Stevebauman\EloquentTable\TableTrait;
   
   class Book extends Model {
       use TableTrait;
   }
   

3. First Use Case: In your controller, fetch records:

   $books = Book::all();
   return view('books.index', compact('books'));
   

   In your Blade view, define columns and render:

   {!! $books->columns(['id' => 'ID', 'title' => 'Title'])->render() !!}
   

Implementation Patterns

Core Workflow

1. Column Definition: Use columns() to map model attributes to table headers:

   $books->columns([
       'id' => 'ID',
       'title' => 'Title',
       'author' => 'Authored By'
   ]);
   

2. Relationship Handling: Use means() to specify relationship paths (dot notation):

   $books->means('owned_by', 'user.first_name');
   

   Customize relationship display with modify():

   $books->modify('owned_by', function($user, $book) {
       return $user->first_name . ' ' . $user->last_name;
   });
   

3. Styling and Attributes:

   • Add table-level attributes:

     $books->attributes(['class' => 'table table-striped']);
     

   • Modify cell attributes:

     $books->modifyCell('owned_by', function($user) {
         return ['class' => $user->role];
     });
     

   • Modify row attributes:

     $books->modifyRow('user_row', function($book) {
         return ['id' => 'book-' . $book->id];
     });
     

4. Sorting:

   • Controller: Handle sorting via query parameters:

     $books = Book::orderBy(Input::get('field'), Input::get('sort'))->get();
     

   • View: Enable sortable columns:

     $books->sortable(['id', 'title']);
     

5. Pagination:

   • Laravel 4: Use showPages() (deprecated in L5):

     $books->showPages();
     

   • Laravel 5: Manually render pagination:

     {!! $books->appends(request()->query())->links() !!}
     

6. Relationship Tables: For hasMany relationships, chain columns() directly:

   $book->authors->columns(['name' => 'Name', 'email' => 'Email']);
   

Integration Tips

• Blade Escaping: Wrap render() in {!! !!} to output raw HTML.
• Dynamic Columns: Fetch column definitions from a config file or database.
• Reusable Components: Create a Blade component for consistent table rendering:

  @component('components.table', ['items' => $books, 'columns' => ['id', 'title']])
  @endcomponent
  

Gotchas and Tips

Pitfalls

1. Laravel 5 Pagination:

   • showPages() is non-functional in Laravel 5. Use Laravel’s native links() method instead.
   • Example:

     {!! $books->appends(request()->except('page'))->links() !!}
     

2. Relationship Caching:

   • Eager-load relationships to avoid N+1 queries:

     $books = Book::with('user', 'publisher')->get();
     

3. Sorting Icons:

   • Default icons (e.g., fa-sort) require Font Awesome. Customize via config or override the sortIcon() method.

4. Deprecated Methods:

   • Avoid showPages() in Laravel 5. Use render() + manual pagination links.

5. HTML Escaping:

   • Unescaped output in modify() closures may cause XSS. Use e() or htmlspecialchars() if needed.

Debugging

• Empty Table: Verify:
  • Columns match model attributes/relationships.
  • Relationships are loaded (e.g., with()).
  • No typos in means() paths (e.g., user.first_name vs. user.firstName).
• Broken Styling: Check:
  • Table attributes (e.g., class="table").
  • CSS conflicts (e.g., !important overrides).
• Sorting Issues:
  • Ensure controller handles Input::get('field') and Input::get('sort').
  • Validate sortable columns exist in the model.

Extension Points

1. Custom Renderers: Override the render() method in a child trait to modify HTML structure:

   trait CustomTableTrait {
       public function render() {
           return '<div class="custom-table">' . parent::render() . '</div>';
       }
   }
   

2. Dynamic Column Logic: Use modify() for conditional rendering:

   $books->modify('status', function($status) {
       return $status === 'active' ? '<span class="label label-success">Active</span>' : 'Inactive';
   });
   

3. Event Hooks: Extend the package by listening to Eloquent events (e.g., retrieved) to pre-process data before table generation.

4. Localization: Override column headers dynamically:

   $books->modify('title', function($title) {
       return trans('labels.book_title');
   });
   

Performance

• Avoid Over-Fetching: Limit columns to essential data to reduce memory usage.
• Lazy Loading: For large datasets, use chunking or cursor pagination instead of paginate().
• Caching: Cache table configurations if columns/attributes rarely change:

  $cachedColumns = cache()->remember('book_table_columns', 60, function() {
      return ['id', 'title', 'created_at'];
  });