Ux Datatables Laravel Package

Getting Started

• Install via Composer: composer require ludovicdevio/ux-datatables. Laravel auto-discovery should register the service provider.
• Publish any config and frontend assets: php artisan vendor:publish --provider="LudovicDevio\UxDataTables\UxDataTablesServiceProvider" (verify the exact provider name in the README).
• Check the package's README and src/ directory for the exact namespace, available artisan commands, and required JS/CSS includes. As v1.0.0 is the first stable release, the README may be the most complete reference.
• First use case: create a DataTable class (e.g., php artisan make:datatable UsersDataTable if the command exists) that defines columns, query source, and formatting. Use it in a controller to return JSON for AJAX or to render a Blade view with the table.

Implementation Patterns

• One DataTable class per resource: Encapsulate column definitions, query logic, and formatting in a dedicated class. Inject it into controllers to keep controllers thin.
• Server-side processing: Leverage the package's integration with Eloquent/Query Builder for pagination, sorting, and searching. Use with() for eager loading and select only needed columns.
• AJAX endpoints: Expose a route that returns the DataTable's JSON response. In Blade, use the provided component or directive to initialise the table with the correct AJAX URL and options.
• Custom columns and actions: Use closures or formatter methods to render links, badges, or buttons. Mark columns as raw HTML where necessary.
• Filters and search: Implement custom filters by overriding query methods or using provided filter hooks. Validate and sanitise request parameters before applying conditions.
• Authorization: Apply Laravel gates/policies inside the DataTable class (e.g., in a builder() or query() method) to restrict rows based on the authenticated user.
• Frontend integration: If the package uses Symfony UX (Stimulus/Turbo), ensure the required JS dependencies are installed and the Stimulus controller is registered. Otherwise, follow the package's instructions for initialising DataTables.net.
• Exports and bulk actions: If supported, configure export buttons or define custom bulk action handlers in the DataTable class.

Gotchas and Tips

• v1.0.0 is the first stable release: The API should be stable, but documentation may be sparse. Review the GitHub changelog/commits for any last-minute changes before upgrading from a pre-release.
• Service provider registration: Laravel auto-discovery usually works, but if you encounter missing bindings, manually add the service provider to config/app.php.
• Asset publishing: Some JS/CSS assets may need to be published and included in your layout. Look for Blade directives like @uxDatatablesStyles / @uxDatatablesScripts or manual <script> includes.
• CSRF and AJAX: Ensure your AJAX requests include the CSRF token (e.g., via a meta tag and $.ajaxSetup). The package may handle this automatically, but verify.
• Debugging: Use Laravel Debugbar and browser dev tools to inspect the JSON response and network requests. Enable query logging to review generated SQL and catch N+1 issues.
• Performance: Always eager load relationships and limit selected columns. Use ->withTrashed() or other scopes only when needed.
• Extensibility: If a feature is missing, extend the base DataTable class or override methods. Check the source for available hooks (e.g., beforeSend, applyFilters).
• Frontend conflicts: If you use Livewire, Alpine, or other JS frameworks, ensure DataTables initialisation does not conflict. The package's Stimulus controller (if present) should be registered correctly.
• Testing: Write feature tests that call your DataTable's AJAX endpoint and assert the JSON structure. Use RefreshDatabase and factories to seed data.