Datatablesbundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require sg/datatablesbundle
   

   Add to bundles.php (Symfony <5.0) or config/bundles.php (Symfony ≥5.0):

   return [
       // ...
       Sg\DataTablesBundle\SgDataTablesBundle::class => ['all' => true],
   ];
   

2. Basic Controller Usage Create a controller with a getDataTablesData() method:

   use Sg\DataTablesBundle\DataTables;
   use Sg\DataTablesBundle\DataTables\DataTablesFactory;
   
   class MyController extends Controller
   {
       public function myAction(DataTablesFactory $factory)
       {
           $dataTables = $factory->createStandardDataTable();
           $dataTables->setEntityClass('App\Entity\MyEntity');
   
           return $dataTables->getDataTablesData();
       }
   }
   

3. First Template Integration Use the datatables Twig helper in your template:

   {{ datatables({
       'src': path('my_route'),
       'columns': [
           { 'data': 'id' },
           { 'data': 'name' },
           { 'data': 'email' }
       ]
   }) }}
   

Implementation Patterns

Common Workflows

1. Entity-Based DataTables

$dataTables = $factory->createStandardDataTable();
$dataTables->setEntityClass('App\Entity\User');
$dataTables->setSearchableColumns(['firstName', 'lastName', 'email']);
$dataTables->setOrderableColumns(['firstName', 'lastName', 'createdAt']);

2. Custom Query Builder

$dataTables = $factory->createStandardDataTable();
$dataTables->setEntityClass('App\Entity\Order');
$dataTables->setQueryBuilder(function (QueryBuilder $qb) {
    $qb->andWhere('o.status = :status')
       ->setParameter('status', 'pending');
});

3. Column Customization

$dataTables->setColumns([
    'id' => [
        'title' => 'ID',
        'width' => '5%',
        'render' => function ($value) {
            return '<a href="/orders/' . $value . '">' . $value . '</a>';
        }
    ],
    'total' => [
        'title' => 'Total',
        'render' => function ($value, $row) {
            return '$' . number_format($value, 2);
        }
    ]
]);

4. Server-Side Processing

$dataTables = $factory->createStandardDataTable();
$dataTables->setEntityClass('App\Entity\Product');
$dataTables->setServerSide(true); // Enable server-side processing

5. Integration with Forms

{{ form_start(form) }}
    {{ form_widget(form) }}
    {{ datatables({
        'src': path('product_datatable'),
        'columns': columns,
        'serverSide': true,
        'ajax': {
            'data': function(d) {
                d.custom_param = $('#my_form').serialize();
                return d;
            }
        }
    }) }}
{{ form_end(form) }}

Advanced Patterns

1. Dynamic Entity Loading

$dataTables = $factory->createStandardDataTable();
$dataTables->setEntityClassResolver(function (Request $request) {
    $entity = $request->query->get('entity');
    return 'App\Entity\\' . ucfirst($entity);
});

2. Custom Actions

$dataTables->setActions([
    'edit' => [
        'title' => 'Edit',
        'url' => function ($row) {
            return path('edit_product', ['id' => $row['id']]);
        }
    ],
    'delete' => [
        'title' => 'Delete',
        'class' => 'btn-danger',
        'url' => function ($row) {
            return path('delete_product', ['id' => $row['id']]);
        },
        'confirm' => 'Are you sure?'
    ]
]);

3. Event Listeners

$dataTables->addListener('preProcess', function (DataTables $dataTables) {
    $dataTables->setSearchableColumns(['name', 'description']);
});

4. Export Functionality

$dataTables->setExportable(true);
$dataTables->setExportColumns(['id', 'name', 'price']);

Gotchas and Tips

Common Pitfalls

1. Deprecated Methods

   • Avoid using setDataTable(); use setEntityClass() or setQueryBuilder() instead.
   • setColumns() now expects an associative array, not a simple array.

2. Query Builder Conflicts

   • Ensure your custom QueryBuilder includes all necessary JOINs and WHERE clauses for filtering, sorting, and pagination to work correctly.
   • Example of a broken setup:

     // ❌ Missing JOIN for related entities
     $qb->select('u.id, u.name');
     

   • Correct setup:

     // ✅ Include all necessary fields and relations
     $qb->select('u.id, u.name, a.address')
        ->leftJoin('u.address', 'a');
     

3. Server-Side Processing Overhead

   • Server-side processing (setServerSide(true)) can be resource-intensive. Optimize with:
     • Proper indexing on filtered/sorted columns.
     • Limiting loaded associations (->leftJoin()->addSelect()).

4. Twig Template Issues

   • Ensure the sg_datatables Twig extension is loaded. If using Symfony Flex, this should be automatic.
   • If using custom column rendering, escape output to prevent XSS:

     {# ✅ Safe rendering #}
     {{- datatables_column('name', 'render')|e('html_attr') -}}
     

5. Caching Headaches

   • Avoid caching routes that serve DataTables data, as it can lead to stale or incorrect data display.

Debugging Tips

1. Enable Query Logging Add to config/packages/dev/doctrine.yaml:

   doctrine:
       dbal:
           logging: true
           profiling: true
   

   Check logs for generated SQL queries to verify filtering/sorting/pagination.

2. Inspect Request Data Dump the incoming request data to ensure DataTables parameters are received:

   public function myAction(Request $request, DataTablesFactory $factory)
   {
       dump($request->query->all());
       // ...
   }
   

3. Validate Column Names Ensure column names in setColumns() match the entity properties or aliases in your QueryBuilder.

4. Check for Deprecated Features The bundle is unmaintained; test thoroughly if using features not documented in the latest release (2022-03-03).

Extension Points

1. Custom Data Providers Implement Sg\DataTablesBundle\DataTables\DataProviderInterface for non-Doctrine data sources:

   class CustomDataProvider implements DataProviderInterface
   {
       public function count($request)
       {
           // Return total count
       }
   
       public function fetch($request)
       {
           // Return filtered/sorted/paginated data
       }
   }
   

   Register with:

   $dataTables->setDataProvider($customProvider);
   

2. Override Twig Helpers Extend the Twig environment to customize the datatables function:

   $twig->addFunction(new \Twig\TwigFunction('custom_datatables', function ($options) {
       // Custom logic
       return new \Twig\Markup($html, 'UTF-8');
   }));
   

3. Add Custom JavaScript Extend the default DataTables initialization:

   {{ datatables({
       'src': path('my_route'),
       'js': [
           'dataTables.ext.js',
           'custom_script.js'
       ],
       'initComplete': 'function() { console.log("Initialized!"); }'
   }) }}
   

4. Integrate with API Platform Use the bundle for server-side processing while leveraging API Platform for entity management:

   $dataTables->setEntityClass('ApiPlatform\Entity\Product');
   $dataTables->setPaginationEnabled(false); // Use API Platform's pagination
   

Configuration Quirks

1. Default Values

   • setServerSide(false) by default (client-side processing).
   • setSearchableColumns([]) means no columns are searchable unless specified.
   • setOrderableColumns([]) disables sorting unless columns are defined.

2. Localization

   • The bundle uses default DataTables language. Override via Java