Grid Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require sylius/grid
   

   Publish the configuration (if needed):

   php artisan vendor:publish --provider="Sylius\Grid\GridServiceProvider"
   

2. Basic Usage Define a grid in a service class (e.g., ProductGrid):

   use Sylius\Grid\Grid;
   use Sylius\Grid\GridDefinition;
   use Sylius\Grid\GridInterface;
   
   class ProductGrid implements GridInterface
   {
       public function getDefinition(): GridDefinition
       {
           return GridDefinition::create()
               ->setSource(new ProductSource()) // Custom source class
               ->addField('name')
               ->addField('price')
               ->addSorting('name', 'price')
               ->addFilter('name', 'contains')
               ->addAction('edit', 'Edit', '/products/{id}/edit');
       }
   }
   

3. First Use Case Inject the grid into a controller and render it in a view:

   use Sylius\Grid\GridRenderer;
   
   class ProductController
   {
       public function index(GridRenderer $gridRenderer, ProductGrid $productGrid)
       {
           return $gridRenderer->render($productGrid);
       }
   }
   

Implementation Patterns

Core Workflows

1. Grid Definition

   • Fields: Define columns with metadata (e.g., addField('name')->setLabel('Product Name')).
   • Sorting: Use addSorting('field', 'direction') (e.g., addSorting('price', 'desc')).
   • Filters: Add filters with operators (e.g., addFilter('price', 'gt', 100)).
   • Actions: Define clickable actions (e.g., addAction('view', 'View', '/products/{id}')).

2. Custom Sources Extend AbstractSource to fetch data:

   use Sylius\Grid\Source\AbstractSource;
   
   class ProductSource extends AbstractSource
   {
       public function getEntities(string $direction = null, ?int $offset = null, ?int $limit = null)
       {
           return ProductRepository::all()->paginate($limit, $offset);
       }
   }
   

3. Dynamic Grids Use GridDefinition::create()->setSource(new DynamicSource($context)) for runtime configurations.

4. Twig Integration Render grids in views with:

   {{ render(controller('Sylius\Grid\GridRenderer', {grid: productGrid})) }}
   

Integration Tips

• Symfony Forms: Bind grid filters to form fields for persistence.
• APIs: Use GridRenderer with JsonResponse for JSON output.
• Events: Listen to GridEvent for pre/post-processing (e.g., GridEvent::PRE_LOAD).

Gotchas and Tips

Common Pitfalls

1. Source Mismatch

   • Ensure getEntities() returns a Collection or Paginator compatible with pagination.
   • Fix: Cast results to Collection if needed:

     return new Collection($rawResults);
     

2. Filter Operator Conflicts

   • Custom operators (e.g., in, not_in) require explicit type hints in addFilter().
   • Fix: Use addFilter('field', 'operator', $value, $type) with FilterType::STRING, FilterType::NUMERIC, etc.

3. Sorting Ambiguity

   • Fields without unique names (e.g., duplicate name in relations) may break sorting.
   • Fix: Use fully qualified names (e.g., addSorting('product.name')).

4. Caching Issues

   • Grid definitions are cached by default. Clear cache after changes:

     php artisan cache:clear
     

Debugging Tips

• Log Grid Events: Add a listener to GridEvent::PRE_LOAD:

  public function onPreLoad(GridEvent $event) {
      \Log::debug('Grid data:', $event->getGrid()->getSource()->getEntities());
  }
  

• Check Configuration: Validate config/grid.php for custom settings (e.g., default_limit).

Extension Points

1. Custom Filters Extend AbstractFilter and register via GridServiceProvider:

   $this->grid->addFilterType('custom', CustomFilter::class);
   

2. Override Rendering Replace the default renderer by binding a custom GridRenderer:

   $this->app->bind(GridRenderer::class, CustomGridRenderer::class);
   

3. Dynamic Field Mapping Use FieldDefinition::setMapper() to transform data before rendering:

   ->addField('price')
     ->setMapper(function ($value) {
         return '$' . number_format($value, 2);
     })