Zhortein Datatable Bundle

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

• Documentation Index
• Installation
• Quick Start
• Providers Overview
• Doctrine Provider
• HTTP/API Provider
• Filters
• Advanced Filters
• Enum Presentation
• Multi-column Sorting
• URL State & Browser History
• Named Saved Views
• Actions & Security
• Security Model
• Bulk Actions & Selection
• Exports
• Asynchronous Export Jobs
• UI/UX & Controls
• Icon System
• Theming & Templates
• Cell Context & Computed Values
• Hierarchical Datatables
• Public API & Compatibility
• Frontend Test Strategy
• Roadmap

License

MIT