Ui Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require ekyna/table-bundle:0.7.x-dev
   

   Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3):

   Ekyna\Bundle\TableBundle\EkynaTableBundle::class => ['all' => true],
   

2. First Use Case Create a table type for an entity (e.g., Brand):

   mkdir -p src/Acme/DemoBundle/Table/Type
   touch src/Acme/DemoBundle/Table/Type/BrandType.php
   

   Define the table structure (see README excerpt for a basic example).

3. Twig Integration Use the table in a Twig template:

   {{ table('acme_demo_brand', {'source': app.doctrine.orm.entity_manager.getRepository('AcmeDemoBundle:Brand')}) }}
   

4. Routing Add a route to render the table:

   # config/routes.yaml
   acme_demo_brand_table:
       path: /brands
       controller: Ekyna\Bundle\TableBundle\Controller\TableController::indexAction
       defaults:
           table: 'acme_demo_brand'
   

Implementation Patterns

Workflows

1. Entity-Centric Tables

   • Extend AbstractTableType for each entity.
   • Use TableBuilderInterface to define columns, filters, and actions.
   • Example:

     $tableBuilder
         ->addColumn('id', Column\NumberType::class)
         ->addColumn('title', Column\TextType::class, ['label' => 'Brand Name'])
         ->addFilter('title', Filter\TextType::class, ['label' => 'Search'])
         ->addAction('edit', 'fa-edit', 'acme_demo_brand_edit', ['id' => 'id']);
     

2. Dynamic Configuration

   • Use OptionsResolver to customize table behavior per context:

     public function configureOptions(OptionsResolver $resolver)
     {
         $resolver->setDefaults([
             'source' => null,
             'pagination' => ['limit' => 20],
         ]);
     }
     

3. Reusable Components

   • Create base table types for common entities (e.g., UserType, ProductType).
   • Extend them for specific use cases:

     class AdminBrandType extends BrandType
     {
         public function buildTable(TableBuilderInterface $tableBuilder)
         {
             parent::buildTable($tableBuilder);
             $tableBuilder->addColumn('createdAt', Column\DateType::class);
         }
     }
     

4. Integration with Forms

   • Use table data in forms (e.g., for bulk actions):

     {{ form_start(form) }}
         {{ form_widget(form.bulkAction) }}
         <button type="submit">Apply</button>
     {{ form_end(form) }}
     

5. API-Driven Tables

   • Replace EntitySource with ApiSource for remote data:

     $tableBuilder->setSource(new ApiSource('https://api.example.com/brands'));
     

Gotchas and Tips

Pitfalls

1. Bundle Registration

   • Forgetting to register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3) will cause silent failures.
   • Fix: Verify the bundle is listed under all or the correct environment.

2. Source Configuration

   • If source is not set in the Twig template or controller, the table will render empty.
   • Fix: Always pass a valid Source (e.g., EntitySource or ArraySource):

     {{ table('acme_demo_brand', {'source': brandsRepository.findAll()}) }}
     

3. Column/Filter Naming

   • Column names must match entity properties (case-sensitive). Underscores in entity fields (e.g., created_at) require snake_case in the table type:

     $tableBuilder->addColumn('created_at', Column\DateType::class);
     

4. Caching Issues

   • Table configurations are cached. Changes to buildTable() may not reflect immediately.
   • Fix: Clear the cache:

     php bin/console cache:clear
     

5. Doctrine Lifecycle Conflicts

   • If the entity manager is not properly injected, EntitySource may fail.
   • Fix: Pass the entity manager explicitly:

     $source = new EntitySource($entityManager, Brand::class);
     

Debugging

1. Enable Debug Mode

   • Set EKYNA_TABLE_DEBUG: true in .env to log table-building steps:

     EKYNA_TABLE_DEBUG=true
     

2. Check Table Events

   • Listen to ekyna_table.build events to inspect the table builder:

     // src/EventListener/TableListener.php
     public function onBuildTable(TableEvent $event)
     {
         dump($event->getTableBuilder());
     }
     

3. Validate Twig Usage

   • Ensure the table service ID matches the type name (e.g., acme_demo_brand for BrandType).
   • Fix: Use dump(app.get('ekyna_table.table_manager')->getTables()) to list available tables.

Tips

1. Custom Column Types

   • Extend AbstractColumnType for specialized columns (e.g., StatusColumnType):

     class StatusColumnType extends AbstractColumnType
     {
         public function buildView(ColumnView $view, array $options)
         {
             $value = $view->getValue();
             $view->vars['statusClass'] = $value === 'active' ? 'success' : 'danger';
         }
     }
     

2. Bulk Actions

   • Use Action\BulkType for row-level actions:

     $tableBuilder->addBulkAction('delete', 'fa-trash', 'acme_demo_brand_delete_bulk');
     

3. Localization

   • Override labels/placeholders in translations:

     # translations/messages.en.yaml
     ekyna_table:
         brand:
             title: "Brand Name"
             filters:
                 title: "Search by name"
     

4. Performance

   • Use DQL filters for large datasets:

     $tableBuilder->addFilter('title', Filter\DQLType::class, [
         'query' => 'PARTIAL(title, :value)',
         'parameters' => ['value' => '%' . $value . '%'],
     ]);
     

5. Testing

   • Mock TableBuilderInterface in unit tests:

     $tableBuilder = $this->createMock(TableBuilderInterface::class);
     $tableBuilder->expects($this->once())->method('addColumn');
     $brandType = new BrandType();
     $brandType->buildTable($tableBuilder);