UX DataTables

https://github.com/pentiminax/ux-datatables
Admin
UX DataTables is a Symfony bundle integrating the DataTables library in Symfony applications.
Tokens:317,962
Snippets:2,324
Trust Score:9.6
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Setup: Install dependencies

Source: https://github.com/pentiminax/ux-datatables/blob/main/AGENTS.md

Installs PHP dependencies with Composer, then frontend dependencies in assets/ and documentation dependencies in docs/.

```bash
composer install

cd assets
npm install

cd ../docs
npm ci
```

--------------------------------

### Complete DataTable configuration example

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/options.mdx

A complete example of configuring a DataTable with various options including autoWidth, caption, language, ordering, paging, searching, serverSide, processing, scrollY, pageLength, lengthMenu, stateSave, urlState, layout, and ajax. This shows a typical full setup for a DataTable instance.

```php
use Pentiminax\UX\DataTables\Enum\Feature;
use Pentiminax\UX\DataTables\Enum\Language;
use Pentiminax\UX\DataTables\Model\DataTable;

$dataTable = new DataTable('products');

$dataTable
    ->autoWidth()
    ->caption('Product Catalog')
    ->language(Language::EN)
    ->ordering(handler: true, indicators: true)
    ->paging(buttons: 5, firstLast: true)
    ->searching()
    ->serverSide()
    ->processing()
    ->scrollY('400px')
    ->pageLength(25)
    ->lengthMenu([10, 25, 50, 100])
    ->stateSave()
    ->urlState()
    ->layout([
        'topStart'    => Feature::PAGE_LENGTH,
        'topEnd'      => Feature::SEARCH,
        'bottomStart' => Feature::INFO,
        'bottomEnd'   => Feature::PAGING,
    ])
    ->ajax(
        url: '/api/products',
        dataSrc: 'data',
        type: 'GET'
    );
```

--------------------------------

### urlState - Example URL produced

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/options.mdx

Example URL produced by urlState() showing the query string format with search, order, start, and pageLength parameters.

```text
?search=foo&order[name]=email&order[dir]=asc&start=20&pageLength=25
```

--------------------------------

### Quick Start with #[AsDataTable]

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/reference/abstract-datatable.mdx

Use this example to create a Doctrine-backed data table by extending AbstractDataTable and applying the #[AsDataTable] attribute. The attribute automatically creates a DoctrineDataProvider configured with the entity class, the internal row processing pipeline built from mapRow(), and the customizeQueryBuilder() method. Configure columns in configureColumns() and map entity rows to frontend-compatible arrays in mapRow().

```php
use App\Entity\User;
use Pentiminax\UX\DataTables\Attribute\AsDataTable;
use Pentiminax\UX\DataTables\Model\AbstractDataTable;
use Pentiminax\UX\DataTables\Column\TextColumn;
use Pentiminax\UX\DataTables\Column\NumberColumn;

#[AsDataTable(User::class)]
final class UsersDataTable extends AbstractDataTable
{
    public function configureColumns(): iterable
    {
        yield NumberColumn::new('id', 'ID');
        yield TextColumn::new('lastName', 'Last name');
        yield TextColumn::new('firstName', 'First name');
        yield TextColumn::new('email', 'Email');
    }

    protected function mapRow(mixed $row): array
    {
        /** @var User $row */
        return [
            'id' => $row->getId(),
            'lastName' => $row->getLastName(),
            'firstName' => $row->getFirstName(),
            'email' => $row->getEmail(),
        ];
    }
}
```

--------------------------------

### Advanced Fixed Columns Example with start and end

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/extensions/fixed-columns.mdx

Enables fixed columns with custom start and end column counts. Pinning too many columns reduces useful viewport width.

```php
$dataTable->fixedColumns(start: 2, end: 1);
```

--------------------------------

### Install with Composer

Source: https://github.com/pentiminax/ux-datatables/blob/main/README.md

Install the bundle via Composer. Requires PHP 8.3 or higher and Symfony StimulusBundle.

```console
composer require pentiminax/ux-datatables
```

--------------------------------

### Set starting display row with displayStart

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/options.mdx

Sets the row at which the table will start displaying. The comment notes that 20 starts at row 21 (zero-based indexing).

```php
$dataTable->displayStart(20);  // Start at row 21
```

--------------------------------

### Install openspout/openspout

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/extensions/buttons.mdx

Installs the required openspout/openspout package for both CSV and XLSX server-side exports.

```bash
composer require openspout/openspout
```

--------------------------------

### urlState - Resulting URL with prefix

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/options.mdx

Example URL produced when using prefixes, showing bracket notation for search, order, start, and pageLength parameters.

```text
?users[search]=alice&users[order][name]=id&users[order][dir]=asc&orders[start]=10&orders[pageLength]=25
```

--------------------------------

### Install symfony/expression-language for Action::setPermission()

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/action-column.mdx

Install the optional Symfony ExpressionLanguage component before using Expression objects with setPermission().

```bash
composer require symfony/expression-language
```

--------------------------------

### Install Bootstrap 3 package

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/styling.mdx

Run this command to install the Bootstrap 3 integration package for DataTables.

```bash
php bin/console importmap:require datatables.net-bs
```

--------------------------------

### Complete DataTable Example with ChoiceColumn

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/choice-column.mdx

Complete example of a DataTable class using ChoiceColumn with a BackedEnum and badge rendering, including column configuration and row mapping.

```php
use Pentiminax\UX\DataTables\Attribute\AsDataTable;
use Pentiminax\UX\DataTables\Column\ChoiceColumn;
use Pentiminax\UX\DataTables\Column\NumberColumn;
use Pentiminax\UX\DataTables\Column\TextColumn;
use Pentiminax\UX\DataTables\Model\AbstractDataTable;

enum OrderStatus: string
{
    case Draft     = 'draft';
    case Confirmed = 'confirmed';
    case Shipped   = 'shipped';
    case Cancelled = 'cancelled';
}

#[AsDataTable(Order::class)]
final class OrdersDataTable extends AbstractDataTable
{
    public function configureColumns(): iterable
    {
        yield NumberColumn::new('id', 'ID');
        yield TextColumn::new('reference', 'Reference');
        yield ChoiceColumn::new('status', 'Status')
            ->setChoices(OrderStatus::class)
            ->renderAsBadges([
                'draft'     => 'secondary',
                'confirmed' => 'primary',
                'shipped'   => 'success',
                'cancelled' => 'danger',
            ]);
    }

    protected function mapRow(mixed $row): array
    {
        return [
            'id'        => $row->getId(),
            'reference' => $row->getReference(),
            'status'    => $row->getStatus()->value,
        ];
    }
}
```

--------------------------------

### Configure data_tables.yaml

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/getting-started/installation.mdx

Example configuration file for the bundle. Place it at config/packages/data_tables.yaml. Options include language, layout, lengthMenu, pageLength, table_attributes, and extensions.

```yaml
data_tables:
  options:
    language: en-GB
    layout:
      topStart: pageLength
      topEnd: search
      bottomStart: info
      bottomEnd: paging
    lengthMenu: [10, 25, 50]
    pageLength: 10
  table_attributes:
    class: 'table'
  extensions:
    buttons: [csv, excel, pdf, print]
    select:
      style: single
```

--------------------------------

### Minimal Scroller Example

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/extensions/scroller.mdx

Use Scroller for large datasets to improve rendering performance. This minimal setup enables Scroller and sets a vertical scroll area of 480px.

```php
$dataTable
    ->scroller()
    ->scrollY('480px');
```

--------------------------------

### Advanced setup with method call

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/integrations/mercure.mdx

Use the mercure() method for programmatic configuration. withCredentials enables cookie/auth forwarding, debounceMs is applied client-side before reload (default 500ms), and topics accepts one or many topics.

```php
$dataTable->mercure(
    topics: ['admin/books', 'admin/authors'],
    withCredentials: true,
    debounceMs: 300,
);
```

--------------------------------

### Install Bootstrap 4 package

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/styling.mdx

Run this command to install the Bootstrap 4 integration package for DataTables.

```bash
php bin/console importmap:require datatables.net-bs4
```

--------------------------------

### ArrayDataProvider constructor before/after with new arguments

Source: https://github.com/pentiminax/ux-datatables/blob/main/UPGRADE.md

Shows the old two-argument ArrayDataProvider construction and the new three-argument version that passes resolved columns and configured filters to enable ordering and search. The 'Before' example is the previous behavior; the 'After' example is the required upgrade.

```php
// Before
return new ArrayDataProvider($this->rows, $this->createRowMapper());
```

```php
// After
return new ArrayDataProvider(
    $this->rows,
    $this->createRowMapper(),
    $this->getResolvedColumns(),
    $this->getConfiguredDataTable()->getFilters(),
);
```

--------------------------------

### Install Bootstrap 4 extension packages

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/styling.mdx

Install the core Bootstrap 4 package and matching extension packages (Select, Responsive, Buttons) for DataTables.

```bash
php bin/console importmap:require datatables.net-bs4
php bin/console importmap:require datatables.net-select-bs4
php bin/console importmap:require datatables.net-responsive-bs4
php bin/console importmap:require datatables.net-buttons-bs4
# Add other extensions you use…
```

--------------------------------

### Configure page length options with lengthMenu

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/options.mdx

Sets the page length options. The second example shows how to provide custom labels for each value, including -1 for 'All'.

```php
$dataTable->lengthMenu([10, 25, 50, 100]);

// With custom labels
$dataTable->lengthMenu([
    [10, 25, 50, -1],
    ['10 rows', '25 rows', '50 rows', 'All']
]);
```

--------------------------------

### Complete Example: IconColumn with dynamic icon, color, size, and tooltips

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/icon-column.mdx

Use this example to create a DataTable with an IconColumn that renders icons based on the raw cell value. The icon, color, and tooltip are determined by closures that map state values to Icon enum cases, color strings, and tooltip text. Searching and sorting operate on the raw cell value, not the rendered icon, and the icon library is lazy-loaded only when at least one IconColumn is present.

```php
use Pentiminax\UX\DataTables\Attribute\AsDataTable;
use Pentiminax\UX\DataTables\Column\IconColumn;
use Pentiminax\UX\DataTables\Column\TextColumn;
use Pentiminax\UX\DataTables\Enum\Icon;
use Pentiminax\UX\DataTables\Enum\IconSize;
use Pentiminax\UX\DataTables\Model\AbstractDataTable;

#[AsDataTable(User::class)]
final class UsersDataTable extends AbstractDataTable
{
    public function configureColumns(): iterable
    {
        yield TextColumn::new('name', 'Name');
        yield IconColumn::new('status', 'Status')
            ->icon(fn (string $state): Icon => match ($state) {
                'active'   => Icon::CircleCheck,
                'pending'  => Icon::Clock,
                'archived' => Icon::Archive,
                default    => Icon::Circle,
            })
            ->color(fn (string $state): string => match ($state) {
                'active'   => 'success',
                'pending'  => 'warning',
                default    => 'secondary',
            })
            ->size(IconSize::Large)
            ->tooltips([
                'active'   => 'Account is active',
                'pending'  => 'Awaiting confirmation',
                'archived' => 'No longer active',
            ]);
    }

    protected function mapRow(mixed $row): array
    {
        return [
            'name'   => $row->getName(),
            'status' => $row->getStatus(),
        ];
    }
}
```

--------------------------------

### PHP: lengthMenu with Show All and Capped

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/configuration.mdx

PHP examples showing how lengthMenu() declares -1 to honor show all, or omits it to cap at max_page_length.

```php
// Show all is honored: this table offers it.
$table->lengthMenu([10, 25, -1]);

// Show all is capped to max_page_length: this table never offers it.
$table->lengthMenu([10, 25]);
```

--------------------------------

### Complete example: ProductsDataTable

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/template-column.mdx

A full data table class using TemplateColumn for a stock badge, along with NumberColumn and TextColumn. Includes mapRow() implementation.

```php
use Pentiminax\UX\DataTables\Attribute\AsDataTable;
use Pentiminax\UX\DataTables\Column\NumberColumn;
use Pentiminax\UX\DataTables\Column\TemplateColumn;
use Pentiminax\UX\DataTables\Column\TextColumn;
use Pentiminax\UX\DataTables\Model\AbstractDataTable;

#[AsDataTable(Product::class)]
final class ProductsDataTable extends AbstractDataTable
{
    public function configureColumns(): iterable
    {
        yield NumberColumn::new('id', 'ID');
        yield TextColumn::new('name', 'Name');
        yield TemplateColumn::new('stock_badge', 'Stock')
            ->setField('stock')
            ->setTemplate('datatable/columns/stock_badge.html.twig');
    }

    protected function mapRow(mixed $row): array
    {
        return [
            'id'         => $row->getId(),
            'name'       => $row->getName(),
            'stock_badge' => $row->getStock(),
        ];
    }
}
```

--------------------------------

### Shared AbstractColumn methods example

Source: https://github.com/pentiminax/ux-datatables/blob/main/skills/ux-datatables/references/columns.md

Shows the fluent configuration methods available on every column, such as setWidth, setClassName, setCellType, setVisible, setOrderable, setSearchable, disableGlobalSearch, setOrderExpression, setData, setField, setDefaultContent, setExportable, hideWhenUpdating, setPermission, and setCustomOption. Use this as a reference for configuring any column type.

```php
TextColumn::new('email', 'Email')
    ->setWidth('200px')            // any CSS unit
    ->setClassName('text-truncate')
    ->setCellType('th')            // 'td' (default) or 'th'
    ->setVisible(true)
    ->setOrderable(false)          // disable sorting on this column
    ->setSearchable(false)         // disable per-column search
    ->disableGlobalSearch()        // keep searchable but exclude from the global box
    ->setOrderExpression('invoiceCount')  // raw ORDER BY (DQL/SELECT alias) for a computed column — see server-side.md
    ->setData('user.email')        // data source path (client-side rows)
    ->setField('user.email')       // entity property path (server-side query/sort)
    ->setDefaultContent('—')       // fallback when value is null/missing
    ->setExportable(false)         // exclude from export (adds 'not-exportable' class)
    ->hideWhenUpdating()           // hide field in the edit modal
    ->setPermission('ROLE_ADMIN')     // hide column unless granted (evaluated server-side, never sent to client)
    ->setCustomOption('key', 'value');
```

--------------------------------

### urlState - Multi-column ordering URL format

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/options.mdx

Example URL format when multiple columns are sorted, using indexed order parameters.

```text
?order[0][name]=id&order[0][dir]=asc&order[1][name]=email&order[1][dir]=desc
```

--------------------------------

### Install Symfony test pack

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/testing.mdx

Install the Symfony functional testing tools as development dependencies. This provides PHPUnit, browser-kit, dom-crawler, and css-selector, which are required for the test harness.

```bash
composer require --dev symfony/test-pack
```

--------------------------------

### Install profiler pack

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/reference/profiler.mdx

Install the Symfony profiler pack as a dev dependency to enable the profiler panel in the dev environment. The bundle automatically imports its profiler configuration when kernel.debug is true.

```bash
composer require --dev symfony/profiler-pack
```

--------------------------------

### Minimal Fixed Columns Example

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/extensions/fixed-columns.mdx

Enables fixed columns with default settings. Use for wide tables where IDs or actions must stay visible while scrolling.

```php
$dataTable->fixedColumns();
```

--------------------------------

### Install Assets with Webpack Encore

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/getting-started/installation.mdx

Installs JavaScript dependencies and rebuilds assets when using Webpack Encore. Required only for Webpack Encore users; AssetMapper users need no extra work.

```bash
npm install --force
npm run watch
```

--------------------------------

### Register custom search strategy with createSearchStrategyRegistry()

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/reference/search-strategies.mdx

Override createSearchStrategyRegistry() to register a custom strategy on top of the default registry. Registering a strategy whose getLogic() matches a shipped one replaces it. The custom WordPrefixStartsSearchStrategy implements SearchStrategyInterface and uses RelationFieldResolver and LikeValueEscaper to match the start of any word, unlike the shipped 'starts' logic which anchors on the beginning of the value.

```php
use Doctrine\ORM\QueryBuilder;
use Pentiminax\UX\DataTables\Contracts\ColumnInterface;
use Pentiminax\UX\DataTables\Contracts\SearchStrategyInterface;
use Pentiminax\UX\DataTables\DataTableRequest\ColumnControlSearch;
use Pentiminax\UX\DataTables\Query\LikeValueEscaper;
use Pentiminax\UX\DataTables\Query\RelationFieldResolver;

/**
 * Word-prefix "starts with": the shipped `starts` logic anchors on the beginning of the value,
 * so searching "doe" never matches "John Doe". This one also matches the start of any word.
 */
final class WordPrefixStartsSearchStrategy implements SearchStrategyInterface
{
    public function apply(
        QueryBuilder $qb,
        ColumnInterface $column,
        ColumnControlSearch $search,
        int $paramIndex,
        string $alias,
    ): void {
        $value = trim($search->value);
        // Honors the column's setSearchField() override when it has one, and falls back to
        // the displayed field otherwise -- including for a column that implements only
        // ColumnInterface.
        $fieldPath = RelationFieldResolver::resolveSearchField($column);

        if ('' === $value || null === $fieldPath) {
            return;
        }

        // Apply the joins the column declared with addSearchJoin(). Idempotent, and a no-op
        // for a column without the search contract.
        RelationFieldResolver::applySearchJoins($qb, $column);

        // LOWER() and LIKE on a uuid or a datetime column are rejected by strict engines.
        if (!RelationFieldResolver::supportsTextSearch($qb, $fieldPath)) {
            return;
        }

        $field = RelationFieldResolver::resolve($qb, $alias, $fieldPath);
        $prefix = sprintf('word_prefix_%d', $paramIndex);
        $anywhere = sprintf('word_anywhere_%d', $paramIndex);
        $escaped = LikeValueEscaper::escape(mb_strtolower($value));
        $escape = LikeValueEscaper::ESCAPE_CHARACTER;

        $qb
            ->andWhere(sprintf(
                "(LOWER(%1\$s) LIKE :%2\$s ESCAPE '%4\$s' OR LOWER(%1\$s) LIKE :%3\$s ESCAPE '%4\$s')",
                $field,
                $prefix,
                $anywhere,
                $escape,
            ))
            ->setParameter($prefix, $escaped.'%')
            ->setParameter($anywhere, '% '.$escaped.'%');
    }

    public function getLogic(): string
    {
        return 'starts';
    }
}
```

```php
use Pentiminax\UX\DataTables\Query\Strategy\DefaultSearchStrategyRegistry;
use Pentiminax\UX\DataTables\Query\Strategy\SearchStrategyRegistry;

protected function createSearchStrategyRegistry(): SearchStrategyRegistry
{
    $registry = new DefaultSearchStrategyRegistry();
    $registry->register(new WordPrefixStartsSearchStrategy());

    return $registry;
}
```

--------------------------------

### Complete Example: UsersDataTable

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/image-column.mdx

A full data table class using ImageColumn with width, height, rounded, placeholder, and clickable options, along with NumberColumn and TextColumn.

```php
use Pentiminax\UX\DataTables\Attribute\AsDataTable;
use Pentiminax\UX\DataTables\Column\ImageColumn;
use Pentiminax\UX\DataTables\Column\NumberColumn;
use Pentiminax\UX\DataTables\Column\TextColumn;
use Pentiminax\UX\DataTables\Model\AbstractDataTable;

#[AsDataTable(User::class)]
final class UsersDataTable extends AbstractDataTable
{
    public function configureColumns(): iterable
    {
        yield NumberColumn::new('id', 'ID');
        yield ImageColumn::new('avatar', 'Avatar')
            ->setImageWidth(50)
            ->setImageHeight(50)
            ->rounded()
            ->setPlaceholder('/images/default-avatar.png')
            ->clickable();
        yield TextColumn::new('name', 'Name');
    }

    protected function mapRow(mixed $row): array
    {
        return [
            'id'     => $row->getId(),
            'avatar' => $row->getAvatarUrl(),
            'name'   => $row->getName(),
        ];
    }
}
```

--------------------------------

### Complete DataTable example with BooleanColumn

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/boolean-column.mdx

Complete example of a DataTable class using BooleanColumn with switch rendering. The entity class is injected automatically via #[AsDataTable(User::class)].

```php
use Pentiminax\UX\DataTables\Attribute\AsDataTable;
use Pentiminax\UX\DataTables\Column\BooleanColumn;
use Pentiminax\UX\DataTables\Column\NumberColumn;
use Pentiminax\UX\DataTables\Column\TextColumn;
use Pentiminax\UX\DataTables\Model\AbstractDataTable;

#[AsDataTable(User::class)]
final class UsersDataTable extends AbstractDataTable
{
    public function configureColumns(): iterable
    {
        yield NumberColumn::new('id', 'ID');
        yield TextColumn::new('email', 'Email');
        yield BooleanColumn::new('active', 'Active')
            ->renderAsSwitch();
        // Entity class is injected automatically from #[AsDataTable(User::class)]
    }

    protected function mapRow(mixed $row): array
    {
        return [
            'id'     => $row->getId(),
            'email'  => $row->getEmail(),
            'active' => $row->isActive(),
        ];
    }
}
```

--------------------------------

### Define lengthMenu options with data_tables.options.lengthMenu

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/configuration.mdx

Defines the available page length options shown in the dropdown. The YAML example lists plain numbers; the PHP example shows custom labels using a nested array with -1 for 'All'.

```yaml
data_tables:
  options:
    lengthMenu: [10, 25, 50, 100]
```

```php
// In PHP
$table->lengthMenu([
    [10, 25, 50, -1],
    [10, 25, 50, 'All']
]);
```

--------------------------------

### Minimal Mercure setup with AsDataTable

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/integrations/mercure.mdx

Enables Mercure for a data table by setting mercure: true in the AsDataTable attribute. The bundle then resolves the Mercure topic automatically from the entity's API Platform item IRI.

```php
#[AsDataTable(Book::class, mercure: true)]
final class BookDataTable extends AbstractDataTable
{
}
```

--------------------------------

### Fluent button list with ButtonsExtension

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/extensions/buttons.mdx

Use the fluent with*Button() API to build a list of buttons across several statements. The example creates a ButtonsExtension with a CSV button, adds an Excel and a Print button, then attaches the extension to a DataTable and places the buttons in the topStart layout position.

```php
$buttons = (new ButtonsExtension([ButtonType::CSV]))
    ->withExcelButton()
    ->withPrintButton();

$dataTable
    ->addExtension($buttons)
    ->layout([
        'topStart' => Feature::BUTTONS,
    ]);
```

--------------------------------

### Complete MoneyColumn data table example

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/money-column.mdx

Full data table class using MoneyColumn with a custom mapRow method. Shows how to integrate MoneyColumn with other columns and map raw data to the expected format.

```php
use Pentiminax\UX\DataTables\Attribute\AsDataTable;
use Pentiminax\UX\DataTables\Column\MoneyColumn;
use Pentiminax\UX\DataTables\Column\TextColumn;
use Pentiminax\UX\DataTables\Model\AbstractDataTable;

#[AsDataTable(Product::class)]
final class ProductsDataTable extends AbstractDataTable
{
    public function configureColumns(): iterable
    {
        yield TextColumn::new('name', 'Product');
        yield MoneyColumn::new('price', 'Price')->currency('EUR');
    }

    protected function mapRow(mixed $row): array
    {
        return [
            'name'  => $row->getName(),
            'price' => $row->getPriceInCents(),
        ];
    }
}
```

--------------------------------

### Enable KeyTable with keyTable()

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/extensions/keytable.mdx

Call keyTable() on the DataTable instance to enable keyboard navigation for cells and rows. Use this minimal setup for keyboard-first workflows and data entry.

```php
$dataTable->keyTable();
```

--------------------------------

### Configure DataTable Extensions with Buttons and Select

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/reference/abstract-datatable.mdx

Use configureDataTable() to add buttons (CSV, EXCEL) and enable multi-select with a specific style. This example shows how to add extensions to the DataTable.

```php
use Pentiminax\UX\DataTables\Enum\ButtonType;
use Pentiminax\UX\DataTables\Enum\SelectStyle;
use Pentiminax\UX\DataTables\Model\DataTable;

public function configureDataTable(DataTable $table): DataTable
{
    return $table
        ->buttons([ButtonType::CSV, ButtonType::EXCEL])
        ->select(style: SelectStyle::MULTI)
        ->columnControl();
}
```

--------------------------------

### Configure actions with position before columns

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/action-column.mdx

Shows how to use Actions::position() to place the entire actions column before the data columns. The example adds an edit and delete action, with the detail action positioned before columns via per-action override.

```php
use Pentiminax\UX\DataTables\Enum\ActionsPosition;
use Pentiminax\UX\DataTables\Model\Actions;

public function configureActions(Actions $actions): Actions
{
    return $actions
        ->position(ActionsPosition::BeforeColumns)
        ->add(Action::edit('Edit'))
        ->add(Action::delete('Delete'));
}
```

--------------------------------

### Set Default Protocol with setDefaultProtocol()

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/url-column.mdx

Prepends 'https' to href values that do not already include a protocol. For example, 'example.com' becomes 'https://example.com' while the displayed text remains 'example.com'.

```php
UrlColumn::new('website', 'Website')
    ->setDefaultProtocol('https');
```

--------------------------------

### Complete NumberColumn data table example

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/number-column.mdx

A full data table class using NumberColumn and TextColumn. Shows how to define columns and map row data, keeping raw numeric values for sorting.

```php
use Pentiminax\UX\DataTables\Attribute\AsDataTable;
use Pentiminax\UX\DataTables\Column\NumberColumn;
use Pentiminax\UX\DataTables\Column\TextColumn;
use Pentiminax\UX\DataTables\Model\AbstractDataTable;

#[AsDataTable(Product::class)]
final class ProductsDataTable extends AbstractDataTable
{
    public function configureColumns(): iterable
    {
        yield NumberColumn::new('id', 'ID')->setWidth('60px');
        yield TextColumn::new('name', 'Product');
        yield NumberColumn::new('stock', 'Stock');
        yield NumberColumn::new('price', 'Price');
    }

    protected function mapRow(mixed $row): array
    {
        return [
            'id'    => $row->getId(),
            'name'  => $row->getName(),
            'stock' => $row->getStock(),
            'price' => $row->getPrice(),
        ];
    }
}
```

--------------------------------

### Documentation: Lint and build

Source: https://github.com/pentiminax/ux-datatables/blob/main/AGENTS.md

Runs documentation linting and build from the docs/ directory.

```bash
npm run lint
npm run build
```

--------------------------------

### MoneyColumn currency and storage configuration

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/money-column.mdx

Configures MoneyColumn with currency, cents storage, and decimal options. The first example uses USD with cents storage and 2 decimals; the second uses EUR without cents storage and hides the currency sign.

```php
MoneyColumn::new('total', 'Total')
    ->currency('USD')
    ->storedAsCents(true)
    ->decimals(2);
```

```php
MoneyColumn::new('rate', 'Rate')
    ->currency('EUR')
    ->storedAsCents(false)
    ->showCurrencySign(false);
```

--------------------------------

### ChoiceFilter with options array and BackedEnum

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/reference/filters.mdx

Shows two ChoiceFilter examples: one with an explicit options array using the [label => value] convention, and one with multiple selection enabled and a BackedEnum class-string for options.

```php
ChoiceFilter::new('status')->options(['Draft' => 'draft', 'Published' => 'published']);
ChoiceFilter::new('roles')->multiple()->options(Role::class);
```

--------------------------------

### TernaryFilter with labels and values

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/reference/filters.mdx

Shows two TernaryFilter examples. The first uses custom labels for true/false states and a field path. The second uses explicit boolean values for the true/false states.

```php
TernaryFilter::new('verified')->field('emailVerifiedAt')
    ->trueLabel('Verified')->falseLabel('Not verified');

TernaryFilter::new('active')->values(true, false);
```

--------------------------------

### Frontend: Lint, typecheck, test, build

Source: https://github.com/pentiminax/ux-datatables/blob/main/AGENTS.md

Runs frontend linting, type checking, tests, and build from the assets/ directory.

```bash
npm run lint
npm run typecheck
npm test
npm run build
```

--------------------------------

### Size configuration with IconSize enum

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/icon-column.mdx

Set the icon size using the size() method, which accepts a string or IconSize enum case. The example uses IconSize::Large, which maps to 24 pixels.

```php
use Pentiminax\UX\DataTables\Enum\IconSize;

IconColumn::new('status', 'Status')
    ->icon(Icon::CircleCheck)
    ->size(IconSize::Large);
```

--------------------------------

### Combine Buttons, Select, Responsive, and Layout

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/extensions/combining-extensions.mdx

Recommended combination of DataTables extensions: enables CSV and Excel export buttons, multi-select, responsive behavior, and a layout with buttons at topStart and search at topEnd. Use this as a starting point for a feature-rich table.

```php
use Pentiminax\UX\DataTables\Enum\ButtonType;
use Pentiminax\UX\DataTables\Enum\Feature;
use Pentiminax\UX\DataTables\Enum\SelectStyle;

$dataTable
    ->buttons([ButtonType::CSV, ButtonType::EXCEL])
    ->select(SelectStyle::MULTI)
    ->responsive()
    ->layout([
        'topStart' => Feature::BUTTONS,
        'topEnd' => Feature::SEARCH,
    ]);
```

--------------------------------

### Full data table class with edit action

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/reference/edit-modal.mdx

Complete example of a data table class that configures columns and adds an edit action. The class uses the AsDataTable attribute and extends AbstractDataTable, with columns for id, name, price, and active status.

```php
use App\Entity\Product;
use Pentiminax\UX\DataTables\Attribute\AsDataTable;
use Pentiminax\UX\DataTables\Column\BooleanColumn;
use Pentiminax\UX\DataTables\Column\NumberColumn;
use Pentiminax\UX\DataTables\Column\TextColumn;
use Pentiminax\UX\DataTables\Model\AbstractDataTable;
use Pentiminax\UX\DataTables\Model\Action;
use Pentiminax\UX\DataTables\Model\Actions;

#[AsDataTable(Product::class)]
final class ProductsDataTable extends AbstractDataTable
{
    public function configureColumns(): iterable
    {
        yield NumberColumn::new('id', 'ID');
        yield TextColumn::new('name', 'Name');
        yield NumberColumn::new('price', 'Price');
        yield BooleanColumn::new('active', 'Active');
    }

    public function configureActions(Actions $actions): Actions
    {
        return $actions->add(
            Action::edit('Edit')
                ->setIcon('bi bi-pencil')
        );
    }
}
```

--------------------------------

### Complete Example with URL Column

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/url-column.mdx

Defines a data table for the User entity with ID, name, and website columns. The name column links to a route using linkToRoute(), and the website column opens in a new tab with an external icon. The Symfony UrlGeneratorInterface is injected automatically when using linkToRoute().

```php
use App\Entity\User;
use Pentiminax\UX\DataTables\Attribute\AsDataTable;
use Pentiminax\UX\DataTables\Column\NumberColumn;
use Pentiminax\UX\DataTables\Column\TextColumn;
use Pentiminax\UX\DataTables\Column\UrlColumn;
use Pentiminax\UX\DataTables\Model\AbstractDataTable;

#[AsDataTable(User::class)]
final class UsersDataTable extends AbstractDataTable
{
    public function configureColumns(): iterable
    {
        yield NumberColumn::new('id', 'ID');
        yield TextColumn::new('name', 'Name');
        yield UrlColumn::new('name', 'Profile')
            ->linkToRoute('admin_user_show', static fn (User $user): array => [
                'id' => $user->getId(),
            ]);
        yield UrlColumn::new('website', 'Website')
            ->openInNewTab()
            ->showExternalIcon();
    }

    protected function mapRow(mixed $row): array
    {
        return [
            'id'      => $row->getId(),
            'name'    => $row->getName(),
            'website' => $row->getWebsite(),
        ];
    }
}
```

--------------------------------

### Enable CSS with AssetMapper - Bootstrap 4 / 3

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/styling.mdx

Edit assets/controllers.json to enable the Bootstrap 4/3 CSS and disable the default DataTables CSS. Then install the packages (see Framework Setup below). Only one CSS entry should be true at a time.

```json
{
  "controllers": {
    "@pentiminax/ux-datatables": {
      "datatable": {
        "enabled": true,
        "autoimport": {
          "datatables.net-dt/css/dataTables.dataTables.min.css": false,
          "datatables.net-bs4/css/dataTables.bootstrap4.min.css": true
        }
      }
    }
  }
}
```

--------------------------------

### Command options for make:datatable

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/reference/maker.mdx

Shows basic usage, namespace support, and entity listing for the make:datatable command.

```bash
# Basic usage
php bin/console make:datatable EntityName

# With namespace
php bin/console make:datatable App\\Entity\\User

# List available entities
php bin/console make:datatable
# (Will prompt for entity selection)
```

--------------------------------

### ChoiceFilter entity options from Doctrine entity

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/reference/filters.mdx

Shows two examples of loading options from a Doctrine entity. The first uses a simple entity with a label and ordering. The second uses a closure for the label and a query builder to filter active authors, with multiple selection enabled.

```php
use App\Entity\Author;
use App\Entity\Category;
use Doctrine\ORM\EntityRepository;
use Doctrine\ORM\QueryBuilder;
use Pentiminax\UX\DataTables\Filter\ChoiceFilter;

ChoiceFilter::new('category')
    ->label('Category')
    ->entity(Category::class, label: 'name', orderBy: ['name' => 'ASC']);

ChoiceFilter::new('author')
    ->multiple()
    ->entity(
        class: Author::class,
        label: static fn (Author $author): string => $author->getFullName(),
        queryBuilder: static function (EntityRepository $repository, QueryBuilder $qb): void {
            $qb->andWhere('e.active = true');
        },
    );
```

--------------------------------

### Layout with Feature enums and custom HTML

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/options.mdx

Use the layout() method to position UI components. Each position accepts a Feature enum, an array of features, null to hide, or a DataTables feature object. The example shows simple layout, multiple features per position, and a full-width row with custom HTML.

```php
use Pentiminax\UX\DataTables\Enum\Feature;

// Simple layout
$dataTable->layout([
    'topStart'    => Feature::PAGE_LENGTH,
    'topEnd'      => Feature::SEARCH,
    'bottomStart' => Feature::INFO,
    'bottomEnd'   => Feature::PAGING,
]);

// Multiple features per position
$dataTable->layout([
    'topEnd' => [Feature::SEARCH, Feature::BUTTONS],
]);

// Full-width row with custom HTML, null to hide a position
$dataTable->layout([
    'top'         => ['div' => ['html' => '<h2>My Table</h2>']],
    'topStart'    => Feature::PAGE_LENGTH,
    'bottomStart' => null,
    'bottomEnd'   => Feature::PAGING,
]);
```

--------------------------------

### Full search configuration with withSearchOption

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/options.mdx

Configures search behavior in detail. Requires importing SearchOption. The searchDelay option is in milliseconds (debounce).

```php
use Pentiminax\UX\DataTables\Model\Options\SearchOption;

$dataTable->withSearchOption(SearchOption::new(
    caseInsensitive: true,
    regex: false,
    return: false,
    search: 'priority',
    smart: true,
    searchDelay: 300,  // Debounce in ms
));
```

--------------------------------

### Import PentiminaxDataTables routes

Source: https://github.com/pentiminax/ux-datatables/blob/main/skills/ux-datatables/references/gotchas.md

Import the bundle's built-in routes once to enable server-side tables, edit/delete actions, and boolean toggles. Without this import, Ajax calls silently fail.

```php
// config/routes/ux_datatables.php
return static function (RoutingConfigurator $routes): void {
    $routes->import('@PentiminaxDataTablesBundle/config/routes.php');
};
```

--------------------------------

### OfficeOptionsProvider implements SearchListOptionsProviderInterface

Source: https://github.com/pentiminax/ux-datatables/blob/main/skills/ux-datatables/references/column-control.md

Provides office options for the 'office' column, returning null for other columns. The constructor injects OfficeRepository and the provide method returns label-value options or null.

```php
<?php

use App\Entity\Employee;
use App\Repository\OfficeRepository;
use Pentiminax\UX\DataTables\Attribute\AsDataTable;
use Pentiminax\UX\DataTables\Contracts\ColumnInterface;
use Pentiminax\UX\DataTables\Contracts\SearchListOptionsProviderInterface;
use Pentiminax\UX\DataTables\DataTableRequest\DataTableRequest;
use Pentiminax\UX\DataTables\Model\AbstractDataTable;
use Pentiminax\UX\DataTables\Model\DataTable;
use Pentiminax\UX\DataTables\Model\Extensions\ColumnControl\SearchList;

final class OfficeOptionsProvider implements SearchListOptionsProviderInterface
{
    public function __construct(private readonly OfficeRepository $offices)
    {
    }

    public function provide(DataTableRequest $request, ColumnInterface $column): ?iterable
    {
        return 'office' === $column->getName()
            ? $this->offices->labelValueOptions()
            : null;
    }
}

#[AsDataTable(Employee::class)]
final class EmployeeDataTable extends AbstractDataTable
{
    public function __construct(private readonly OfficeOptionsProvider $officeOptions)
    {
    }

    public function configureDataTable(DataTable $table): DataTable
    {
        return $table
            ->serverSide()
            ->processing()
            ->columnControl(
                target: 1,
                content: [SearchList::new()->ajaxOptionsProvider($this->officeOptions)],
            );
    }
}
```

--------------------------------

### Column to DataTableColumn migration before and after

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/reference/attributes.mdx

Shows the mechanical migration from the deprecated Column attribute to DataTableColumn. The before example uses named parameters for type, title, orderable, and width. The after example moves those into options, keeping type, name, and position as named arguments.

```php
use Pentiminax\UX\DataTables\Column\EmailColumn;

// Before
#[Column(type: EmailColumn::class, title: 'Email', orderable: false, width: '120px')]
private string $email;

// After
#[DataTableColumn(EmailColumn::class, ['title' => 'Email', 'orderable' => false, 'width' => '120px'])]
private string $email;
```

--------------------------------

### Server-side DataTable test example

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/testing.mdx

Example test class for a server-side table. It uses dataTable() to send a real request, then chains assertions on the response. The test searches for 'Symfony', orders by title descending, and asserts record counts and column values.

```php
// tests/DataTable/BookDataTableTest.php
namespace App\Tests\DataTable;

use App\DataTable\BookDataTable;
use Pentiminax\UX\DataTables\Test\DataTableTestCase;

final class BookDataTableTest extends DataTableTestCase
{
    public function testSearchNarrowsTheResultSet(): void
    {
        static::createClient();

        $this->dataTable(BookDataTable::class)
            ->search('Symfony')
            ->orderBy('title', 'desc')
            ->page(1)
            ->length(10)
            ->fetch()
            ->assertRecordsTotal(120)
            ->assertRecordsFiltered(3)
            ->assertColumnValues('title', ['UX in Action', 'Symfony 7', 'Doctrine Deep Dive']);
    }
}
```

--------------------------------

### Run make:datatable with entity name or FQCN

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/reference/maker.mdx

Run the maker command with either a short entity name or a fully-qualified class name. The command generates a DataTable class in src/DataTables/.

```bash
php bin/console make:datatable User
```

```bash
php bin/console make:datatable App\\Entity\\User
```

--------------------------------

### ajax(string $url, ?string $dataSrc = null, string $type = 'GET')

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/reference/datatable.mdx

Configures the Ajax endpoint and request mode.

```APIDOC
## ajax(string $url, ?string $dataSrc = null, string $type = 'GET')

### Description
Configures the Ajax endpoint and request mode for server-side data loading.

### Parameters
- **$url** (string) - Required - The Ajax endpoint URL.
- **$dataSrc** (?string) - Optional - The data source property name.
- **$type** (string) - Optional - HTTP method, default 'GET'.
```

--------------------------------

### Combine Default Protocol and Allowed Protocols

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/url-column.mdx

Combines setDefaultProtocol() and allowedProtocols() to prepend 'https' and then render only URLs with that protocol as links.

```php
UrlColumn::new('website', 'Website')
    ->setDefaultProtocol('https')
    ->allowedProtocols(['https']);
```

--------------------------------

### PHP: pageLength and lengthMenu Escaping Bound

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/configuration.mdx

PHP example showing that pageLength() and lengthMenu() entries are served in full, even above max_page_length.

```php
// Served in full: the table asked for these page sizes.
$table->pageLength(2000)->lengthMenu([500, 2000]);
```

--------------------------------

### displayStart(int $displayStart)

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/reference/datatable.mdx

Sets the initial row offset.

```APIDOC
## displayStart(int $displayStart)

### Description
Sets the initial row offset.

### Parameters
- **$displayStart** (int) - Required - The initial row offset.
```

--------------------------------

### Template example: stock_badge.html.twig

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/template-column.mdx

Twig template for the stock badge, using a ternary to set the badge variant based on the data value.

```twig
{# templates/datatable/columns/stock_badge.html.twig #}
{% set variant = data > 10 ? 'success' : (data > 0 ? 'warning' : 'danger') %}
<span class="badge text-bg-{{ variant }}">{{ data }}</span>
```

--------------------------------

### PHP-First Configuration with AbstractDataTable

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/getting-started/introduction.mdx

Configure a DataTable entirely in PHP using a fluent API. Extend AbstractDataTable and implement configureColumns() and configureDataTable() to define columns and options like page length and searching.

```php
use Pentiminax\UX\DataTables\Column\NumberColumn;
use Pentiminax\UX\DataTables\Column\TextColumn;
use Pentiminax\UX\DataTables\Model\AbstractDataTable;
use Pentiminax\UX\DataTables\Model\DataTable;

final class UsersDataTable extends AbstractDataTable
{
    public function configureColumns(): iterable
    {
        yield TextColumn::new('name', 'Name');
        yield NumberColumn::new('age', 'Age');
    }

    public function configureDataTable(DataTable $table): DataTable
    {
        return $table
            ->pageLength(25)
            ->searching(true);
    }
}
```

--------------------------------

### Enable API Platform integration imperatively

Source: https://github.com/pentiminax/ux-datatables/blob/main/skills/ux-datatables/references/api-platform.md

Use this imperative configuration to enable the client-side adapter only, without auto URL resolution or column auto-detection.

```php
public function configureDataTable(DataTable $table): DataTable
{
    return $table
        ->ajax('/api/books')
        ->serverSide()
        ->apiPlatform(true);
}
```

--------------------------------

### Template example: user_status.html.twig

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/columns/template-column.mdx

Twig template that renders a badge with a variant based on the data value. Uses the 'data' variable for the cell value.

```twig
{# templates/datatable/columns/user_status.html.twig #}
<span class="badge bg-{{ data == 'active' ? 'success' : 'danger' }}">
    {{ data|capitalize }}
</span>
```

--------------------------------

### Set UI language with language

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/options.mdx

Sets the UI language using the Language enum. Examples show French, German, Spanish, and British English.

```php
use Pentiminax\UX\DataTables\Enum\Language;

$dataTable->language(Language::FR); // French
$dataTable->language(Language::DE); // German
$dataTable->language(Language::ES); // Spanish
$dataTable->language(Language::EN); // British English
```

--------------------------------

### ajaxRequestData(string $url, array $data, string $type = 'GET')

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/reference/datatable.mdx

Configures the Ajax endpoint with extra request data sent on every call.

```APIDOC
## ajaxRequestData(string $url, array $data, string $type = 'GET')

### Description
Configures the Ajax endpoint with extra request data sent on every call.

### Parameters
- **$url** (string) - Required - The Ajax endpoint URL.
- **$data** (array) - Required - Additional data to send with each request.
- **$type** (string) - Optional - HTTP method, default 'GET'.
```

--------------------------------

### info - Toggle information summary

Source: https://github.com/pentiminax/ux-datatables/blob/main/docs/src/content/docs/guide/options.mdx

Use info(true) to show the information summary (default) or info(false) to hide it.

```php
$dataTable->info(true);   // Show (default)
$dataTable->info(false);  // Hide
```
Tokens:
Raw