README

A Symfony 8+ bundle for Bootstrap-first business datatables driven by PHP definitions.

Status

Stable 1.x; 2.0 beta available. The stable public API follows Semantic Versioning. The 2.0 prerelease introduces the documented theme extension contract; review the migration guide before upgrading.

Requirements

PHP: 8.4+
Symfony: 8.0+
Frontend: Bootstrap 5 (CSS/JS), Symfony UX Stimulus, and AssetMapper.

Features

PHP-first Definitions: Declare your datatables as PHP classes with attributes.
Twig Rendering: Render tables with a single Twig function: {{ zhortein_datatable() }}.
Ajax Fragments: Seamless server-side updates using vanilla Stimulus.
Data Providers: Native Doctrine ORM, Array and optional remote HTTP/API providers.
Filtering: Built-in global search, toolbar/header filters, and advanced Search Builder.
Multi-column Sorting: Ordered, accessible sorting shared by providers, URL state, saved views, and exports.
Shareable State: Per-instance URL state with browser history and Turbo restoration.
Named Views: Optional saved views with replaceable ownership, authorization and storage contracts.
Persistent Preferences: Optional PSR-6-backed per-user defaults with explicit identity, safe filters and save/reset controls.
Streaming Exports: Bounded-memory Doctrine, CSV and XLSX pipelines with explicit provider/writer capabilities.
Guarded Exports: Server-side CSV/XLSX row limits, preflight counting and replaceable authorization.
Asynchronous Exports: Optional owner-bound background jobs with storage-agnostic persistence and Symfony Messenger integration.
Actions: Declarative row, global and bulk actions with CSRF-aware forms and opt-in Ajax execution.
Exports: Server-side CSV and optional XLSX exports.
Customization: Flexible UI/UX customization via Twig blocks and a 2.0 registry for complete external themes.
Type Safety: Automatic Doctrine type detection and typed cell rendering.
Rich Enums: Localized enum labels with optional badges, colors and icons, shared by filters and exports.
Rich Cells: Complete server-side cell context and reusable computed values shared with exports.
Hierarchical Tables: Accessible lazy child datatables with signed context, isolated state, and independent providers.

Installation Summary

Install the PHP dependencies:

composer require zhortein/datatable-bundle
composer require symfony/asset-mapper symfony/asset symfony/stimulus-bundle

To evaluate the 2.0 prerelease explicitly:

composer require zhortein/datatable-bundle:^2.0@beta

The bundle does not currently provide a Symfony Flex recipe. The host application must:

register ZhorteinDatatableBundle in config/bundles.php;
import @ZhorteinDatatableBundle/config/routes.php;
enable @zhortein/datatable-bundle/datatable in assets/controllers.json;
install and import Bootstrap 5 and Bootstrap Icons;
render the AssetMapper app entrypoint in the base layout.

Add the frontend dependencies:

php bin/console importmap:require bootstrap
php bin/console importmap:require bootstrap-icons/font/bootstrap-icons.min.css

Follow the Installation Guide for the exact file contents, verification commands and troubleshooting. Then use the Quick Start to create a complete working page.

Minimal Example

1. Define your Datatable

namespace App\Datatable;

use App\Entity\User;
use Zhortein\DatatableBundle\Attribute\AsDatatable;
use Zhortein\DatatableBundle\Contract\DatatableInterface;
use Zhortein\DatatableBundle\Definition\DatatableDefinition;

#[AsDatatable(name: 'users')]
final class UserDatatable implements DatatableInterface
{
    public function buildDatatable(DatatableDefinition $definition): void
    {
        $definition
            ->setEntityClass(User::class)
            ->addColumn('e.id', visible: false)
            ->addColumn('e.email', label: 'Email')
            ->addColumn('e.createdAt', label: 'Created At', searchable: false, type: 'datetime')
        ;
    }
}

2. Render it in Twig

{{ zhortein_datatable('users', { search: true }) }}

Documentation

License

MIT

zhortein / datatable-bundle

Maintainers

Package info

Statistics

Security