Datatable Bundle Laravel Package

Getting Started

This is a Symfony2 bundle, not a Laravel package, so treat the repo as a reference implementation and port the patterns into Laravel (usually yajra/laravel-datatables or a hand-rolled query builder). If you genuinely need it in a legacy Symfony2 app:

1. composer require waldo/datatable-bundle and register Waldo\DatatableBundle\WaldoDatatableBundle in AppKernel.php.
2. Import the bundle routing (waldo_datatable routes) in app/config/routing.yml — this exposes the Ajax endpoint that DataTables talks to.
3. Add minimal config under waldo_datatable (template, default theme, JS/CSS asset paths).
4. Annotate one entity (@Datatable) or define it in YAML — start with a single entity, no joins. User is the canonical first case.
5. In a controller, render the provided Twig template; include jQuery + DataTables JS on the page. The grid should now page/sort/search over your Doctrine entity via Ajax.

Where to look first: the bundle's Datatable service and its config/annotation parsing (Resources/config), then the Twig template, because that dictates the JSON contract the JS expects. For a Laravel dev, the fastest path is to read the annotation-to-DQL translation, then mirror it in a yajra Datatables::of() pipeline.

Implementation Patterns

• Annotation-driven columns. Columns are declared on the entity (field name, title, searchable/sortable, renderer). This is the bundle's core workflow — keep entity config colocated with the model.
• YAML alternative. For entities you don't want to pollute with annotations, mirror the same schema in bundle config. Useful when the entity lives in a shared vendor bundle.
• The Ajax endpoint pattern. DataTables sends draw, start, length, search[value], order[0][column], order[0][dir]. The bundle's controller translates these into LIMIT/OFFSET/ORDER BY/WHERE on a DQL query and returns {draw, recordsTotal, recordsFiltered, data}. If you port to Laravel, replicate exactly this JSON shape or the JS will silently render empty rows.
• Joins for relations. Declare joins in the datatable config and expose joined fields as columns. Alias carefully — the bundle builds DQL aliases from your config, and mismatched aliases are the #1 breakage.
• Custom renderers. Use per-column renderers/callbacks for formatting (dates, badges, action links). Keep them side-effect free; they run per row server-side.
• Filters. Add fixed WHERE conditions in config for scoping (e.g. tenant, soft-deleted), and let DataTables' global search handle the rest.
• Porting to Laravel. Map: Doctrine DQL → Eloquent builder, column config → ->addColumn()/->editColumn(), renderer → closure, joins → ->join()/with(). The DataTables JS side is identical, which is the real value of reading this repo.

Gotchas and Tips

• Archived and Symfony2-only. No maintenance, PHP/Doctrine2-era constraints. Don't expect PHP 8 or Doctrine 3 compatibility. In a modern Laravel app, use it only as a design reference.
• JSON contract drift. If draw isn't echoed back, or recordsTotal/recordsFiltered are wrong, DataTables paginates incorrectly. Log the raw response while debugging.
• Search on joined columns. Global search only covers columns flagged searchable. Joins need explicit searchable flags or the search box "does nothing" for related fields.
• Order-column injection. Never derive ORDER BY directly from the request; whitelist sortable columns. The bundle does some of this, but any custom renderer/config you add can reintroduce risk.
• Annotation caching. In dev, changes to entity annotations may not reflect until the cache is cleared — app/console cache:clear when columns "disappear."
• DQL alias mismatches. The bundle's generated aliases are fragile; a typo in a join config yields empty results rather than an error. Dump the final DQL when results look wrong.
• Front-end version coupling. The shipped template assumes an older jQuery/DataTables pairing. Mixing a modern DataTables CDN with the bundle's param names breaks the request format.
• Extension points. Override the Twig template via waldo_datatable config, swap the theme, or subclass the Datatable service to customize query building. For Laravel, treat these as the seams to replicate (->setRowClass(), custom rawColumns, response transformers).
• Debugging. Use the Symfony profiler's Doctrine panel to inspect the executed SQL; the bundle's Ajax requests are ordinary controller actions, so standard logging applies.