Grids Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require nayjest/grids
   

   Publish the config file:

   php artisan vendor:publish --provider="Nayjest\Grids\GridsServiceProvider"
   

2. Basic Usage: Define a grid in a controller:

   use Nayjest\Grids\Grids;
   use Nayjest\Grids\DataProviders\Eloquent;
   
   public function index()
   {
       $grid = Grids::make('users')
           ->add(Eloquent::source('App\Models\User'))
           ->columns([
               'id', 'name', 'email'
           ]);
   
       return view('users.index', ['grid' => $grid]);
   }
   

3. First View: Render the grid in a Blade template:

   {!! $grid !!}
   

   Or use a specific theme:

   {!! $grid->render('bootstrap') !!}
   

First Use Case: Quick Eloquent Grid

Create a paginated, sortable grid for a Post model:

$grid = Grids::make('posts')
    ->add(Eloquent::source('App\Models\Post'))
    ->columns([
        'id' => 'ID',
        'title' => 'Title',
        'created_at' => 'Created At',
    ])
    ->paginate(10)
    ->sortable(['title', 'created_at']);

Implementation Patterns

Core Workflow

1. Define Grid: Use Grids::make() to instantiate a grid with a unique key (e.g., 'users').

   $grid = Grids::make('users')->add(Eloquent::source(User::class));
   

2. Configure Columns:

   $grid->columns([
       'id' => 'ID',
       'name' => 'Name',
       'email' => 'Email',
   ]);
   

3. Add Features:

   $grid->paginate(20)
       ->sortable(['name', 'email'])
       ->filterable(['name', 'email'])
       ->exportable(['csv', 'excel']);
   

4. Render:

   {!! $grid->render('bootstrap') !!}
   

Integration Tips

• Dynamic Data Sources: Use closures for dynamic queries:

  $grid->add(Eloquent::source(function() {
      return User::where('active', true);
  }));
  

• Custom Views: Override default views by publishing assets:

  php artisan vendor:publish --tag=grids-views
  

  Then modify resources/views/vendor/grids/....

• Caching: Enable caching for performance:

  $grid->cache(60); // Cache for 60 seconds
  

• Themes: Extend or create new themes by copying the bootstrap theme from vendor/nayjest/grids/src/Themes/Bootstrap.

Advanced Patterns

• Nested Grids: Embed grids within grids for hierarchical data:

  $grid->column('posts', function($user) {
      return Grids::make('posts')
          ->add(Eloquent::source($user->posts))
          ->columns(['title'])
          ->paginate(5);
  });
  

• Conditional Logic: Use closures for dynamic column visibility:

  $grid->column('status', function($user) {
      return $user->active ? 'Active' : 'Inactive';
  });
  

• API Integration: Return grid data as JSON for SPAs:

  return response()->json($grid->toArray());
  

Gotchas and Tips

Common Pitfalls

1. Key Conflicts: Ensure grid keys (e.g., 'users') are unique per page to avoid parameter conflicts. Use namespaced keys (e.g., 'admin.users') if multiple grids share a route.

2. Pagination Issues: If pagination breaks, check for:

   • Missing paginate() call.
   • Conflicts with route parameters (e.g., ?page=2 vs. grid pagination).
   • Custom query builders overriding default pagination logic.

3. Sorting/Filtering Quirks:

   • Case Sensitivity: Eloquent sorting may be case-sensitive. Use ->orderByRaw("LOWER(column)") for case-insensitive sorts.
   • Filter Conflicts: Ensure filterable columns match database column names or use custom callbacks:

     $grid->filterable(['name'], function($query, $value) {
         return $query->where('name', 'like', "%{$value}%");
     });
     

4. Caching Gotchas:

   • Caching applies to the entire grid state (data + UI). Clear cache manually if data changes unexpectedly:

     $grid->cache(300)->remember('grid_key');
     

Debugging Tips

1. Inspect Grid State: Dump the grid object to debug configuration:

   dd($grid->toArray());
   

2. Check Data Provider: Verify the data source is correct:

   $grid->add(Eloquent::source(User::query()->toSql())); // Log SQL
   

3. Theme Overrides: If themes break, ensure:

   • Published views exist in resources/views/vendor/grids.
   • No syntax errors in custom theme files.

4. Event Listeners: Use Grids::listen() to debug grid events:

   Grids::listen('beforeRender', function($grid) {
       \Log::info('Grid rendered:', $grid->toArray());
   });
   

Extension Points

1. Custom Components: Extend the component system by creating new classes in app/Grids/Components:

   namespace App\Grids\Components;
   use Nayjest\Grids\Components\Component;
   
   class CustomExport extends Component {
       // Implement logic
   }
   

   Register in config/grids.php:

   'components' => [
       'custom_export' => \App\Grids\Components\CustomExport::class,
   ],
   

2. Data Provider Extensions: Add support for new data sources (e.g., API clients) by extending Nayjest\Grids\DataProviders\DataProvider.

3. Theme Customization: Override theme files or extend the Theme class:

   namespace App\Grids\Themes;
   use Nayjest\Grids\Themes\Theme;
   
   class CustomTheme extends Theme {
       public function renderHeader() { ... }
   }
   

   Register in config/grids.php:

   'themes' => [
       'custom' => \App\Grids\Themes\CustomTheme::class,
   ],
   

Performance Tips

1. Lazy Loading: Use ->lazy() for large datasets to reduce memory usage:

   $grid->add(Eloquent::source(User::query()->lazy()));
   

2. Selective Columns: Limit columns in queries to reduce load:

   $grid->add(Eloquent::source(User::select(['id', 'name', 'email'])));
   

3. Disable Features: Turn off unused features (e.g., sorting) for static grids:

   $grid->disableSorting()->disablePagination();