Voyager Datatable Laravel Package

Getting Started

• Install into an existing Laravel app that already has Voyager (the-control-group/voyager) and typically yajra/laravel-datatables-oracle. Add the package:

  composer require joy/voyager-datatable
  

• Look first at config/ and src/ to see what it actually registers: it is a thin bridge between Voyager's BREAD system and yajra/laravel-datatables. There is no meaningful public docs site, so treat the GitHub README and source as the spec.
• Typical first use case: replace a default Voyager BREAD listing (server-rendered <table>) with an AJAX DataTable, so large tables paginate, search, and sort server-side instead of loading all rows.
• Minimum viable flow:
  1. Publish config if the package exposes one (php artisan vendor:publish --tag=...), inspect it.
  2. Enable it per BREAD (usually via BREAD options/relations or a config mapping — check the package source for the exact key).
  3. Point the package at a DataTable class (extend Yajra\DataTables\Services\DataTable or the package's base class).
  4. Visit the Voyager BREAD list view and confirm the grid renders and the JSON endpoint responds under the admin prefix.
• Start with one small BREAD (e.g., roles, settings) before touching user-facing tables.

Implementation Patterns

• DataTable class per model. Define an EloquentDataTable subclass with query(), html(), and ajax() methods. Keep the query in query() and column definitions in html() so the same class is reusable from an admin controller and any custom endpoint.
• Eager loading is the whole game. Because the grid now paginates server-side, N+1 problems surface per page. Always with() relationships you render as columns:

  public function query(Model $model)
  {
      return $model->newQuery()->with(['author:id,name', 'category:id,title']);
  }
  

• Use addColumn/editColumn, not raw SQL aliases, for computed or relation output. Keeps your select() stable and lets rawColumns() stay explicit.
• Filter UI via filterColumn / filter() for BREAD-specific search fields. This is where you recreate whatever custom filters Voyager's default list had.
• Register routes carefully. Either let the package register admin routes for you, or add an explicit admin-prefixed AJAX route and set the DataTable's ajax() URL to it. Don't rely on the package silently hooking Voyager's controller — verify in php artisan route:list --path=admin.
• Integration with Voyager controllers: if the package doesn't auto-swap the BREAD index, override the Voyager controller's index() (via a custom controller in config/voyager.php) and return the DataTable's render() from your view.
• Blade view pattern: the package usually ships a wrapper view that calls $dataTable->table(). Extend it in resources/views/vendor/... rather than editing vendor files, and push the scripts() in a @push('javascript') stack so Voyager's layout picks it up.
• Buttons / exports: if you use yajra/laravel-datatables-buttons, add the ButtonServiceProvider action in the builder and expose export columns in a Voyager "actions" dropdown.

Gotchas and Tips

• Very low adoption (13 stars, 0 dependents). Expect edge cases: no community answers, and Voyager's own maintenance has slowed. Budget time to read the source instead of searching for docs.
• Last release Feb 2024. Verify compatibility against your Voyager version and, importantly, against the yajra datatables major version (v9 vs v10 API differs — csrf, ->parameters(), column search behavior). Pin versions.
• Search on relations silently breaks when the column isn't a real DB column. Use filterColumn() or a whereHas() clause; otherwise global search returns wrong results.
• rawColumns risk. Any HTML in a column (links, badges) must be listed in rawColumns(). Forgetting it renders escaped markup — a common "why is my action button text?" bug. Conversely, never put user-controlled data in a raw column without e()/escaping.
• CSRF and the AJAX endpoint. If the grid 419s, the DataTable isn't reading the meta CSRF token — ensure $dataTable->ajax() includes csrf and the view has <meta name="csrf-token"> in Voyager's layout.
• Voyager route/middleware quirks. The package often relies on the admin middleware group and prefix from config/voyager.php. Changing routes.prefix or using a custom admin domain will break hardcoded URLs — grep the source for admin/ before assuming flexibility.
• Debugging: hit the AJAX URL directly in the browser (logged in) to see raw JSON errors; Vue/DataTables swallows 500s. Check storage/logs/laravel.log and enable query logging around query().
• Extension points are thin but useful: published views under resources/views/vendor/, config overrides, and your own DataTable subclasses are the reliable customization surface. Avoid editing vendor files.
• Performance: add DB indexes on the columns you sort/filter by; server-side DataTables does ORDER BY and LIKE '%term%' on the fly. For high-traffic admin panels, prefer searchable => false on expensive fields and use explicit filters.
• Abandonment hedge. If constraints tighten, migrating a DataTable class to plain yajra is usually just removing the Voyager wrapper — keep your queries in query() so you're not locked in.