DataTables Bundle

https://github.com/omines/datatables-bundle
Admin
A Symfony bundle that provides integration with DataTables.net for rendering and processing data...
Tokens:104,288
Snippets:752
Trust Score:8
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### fromDefaults implementation

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTableState.md

Initializes start and length from options, then applies each order entry. start falls back to 0 when absent; initial state is not marked as a callback.

```php
$state = new static($dataTable);
$state->start = (int) $dataTable->getOption('start');
$state->length = (int) $dataTable->getOption('pageLength');

foreach ($dataTable->getOption('order') as $order) {
    $state->addOrderBy($dataTable->getColumn($order[0]), $order[1]);
}
```

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

### start / length (pagination)

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTableState.md

These methods manage pagination parameters. getStart() and getLength() return the current start offset and page length, while setStart() and setLength() allow setting them. Note that getLength() returns null when the client requested all records (-1), and setLength() coerces values less than 1 to null with a deprecation warning.

```APIDOC
## start / length (pagination)

### Description
These methods manage pagination parameters. getStart() and getLength() return the current start offset and page length, while setStart() and setLength() allow setting them. Note that getLength() returns null when the client requested all records (-1), and setLength() coerces values less than 1 to null with a deprecation warning.

### Methods
- `getStart(): int` - Returns the start offset.
- `setStart(int $start): static` - Sets the start offset. Passing a negative value triggers E_USER_DEPRECATED and coerces to 0.
- `getLength(): ?int` - Returns the page length, or null if all records were requested (-1).
- `setLength(?int $length): static` - Sets the page length. Passing an integer < 1 triggers E_USER_DEPRECATED and coerces to null.

### Parameters
#### setStart
- `$start` (int) - Required - The start offset.

#### setLength
- `$length` (?int) - Required - The page length, or null for all records.

### Return Values
- `getStart()`: int - The start offset.
- `setStart()`: static - The current instance for chaining.
- `getLength()`: ?int - The page length, or null if all records.
- `setLength()`: static - The current instance for chaining.

### Example
```php
// Export path — browse the entire table; see DataTableExporterManager
$state->setStart(0)->setLength(null);
```
```

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

### Install via Composer

Source: https://github.com/omines/datatables-bundle/blob/master/docs/source/index.html.md

Install the bundle using Composer. Requires Symfony 4.1 or later.

```bash
composer require omines/datatables-bundle
```

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

### Usage example with MongoDBAdapter

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/MongoDBAdapter.md

Creates a DataTable with MongoDB adapter and handles the request.

```php
use Omines\DataTablesBundle\Adapter\MongoDB\MongoDBAdapter;
use Omines\DataTablesBundle\Column\TextColumn;

$table = $factory->create()
    ->add('name', TextColumn::class)
    ->add('company.name', TextColumn::class, ['field' => 'company.name'])
    ->createAdapter(MongoDBAdapter::class, [
        'collection' => $collection,
    ])
    ->handleRequest($request);
```

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

### Usage example with ElasticaAdapter

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/ElasticaAdapter.md

Shows how to create a DataTable with an ElasticaAdapter, configuring columns and client/index options. Requires ruflin/elastica.

```php
use Omines\DataTablesBundle\Adapter\Elasticsearch\ElasticaAdapter;
use Omines\DataTablesBundle\Column\DateTimeColumn;
use Omines\DataTablesBundle\Column\MapColumn;
use Omines\DataTablesBundle\Column\TextColumn;

$table = $factory->create()
    ->setName('log')
    ->add('timestamp', DateTimeColumn::class, ['field' => '@timestamp', 'format' => 'Y-m-d H:i:s', 'orderable' => true])
    ->add('level', MapColumn::class, [
        'default' => '<span class="label label-default">Unknown</span>',
        'map' => ['Emergency', 'Alert', 'Critical', 'Error', 'Warning', 'Notice', 'Info', 'Debug'],
    ])
    ->add('message', TextColumn::class, ['globalSearchable' => true])
    ->createAdapter(ElasticaAdapter::class, [
        'client' => ['host' => 'elasticsearch'],
        'index' => 'logstash-*',
    ])
    ->handleRequest($request);
```

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

### Usage example with TextFilter and ChoiceFilter

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/Filters.md

Shows how to add filters to columns using TextFilter and ChoiceFilter. Requires the columnFilter template parameter and global searching to be enabled.

```php
use Omines\DataTablesBundle\Column\TextColumn;
use Omines\DataTablesBundle\Filter\ChoiceFilter;
use Omines\DataTablesBundle\Filter\TextFilter;

$table = $factory->create()
    ->add('firstName', TextColumn::class, [
        'filter' => (new TextFilter())->set(['placeholder' => 'Search first name']),
    ])
    ->add('gender', TextColumn::class, [
        'filter' => (new ChoiceFilter())->set([
            'placeholder' => 'All',
            'choices' => ['f' => 'Female', 'm' => 'Male'],
        ]),
    ])
    ->createAdapter(ORMAdapter::class, ['entity' => Person::class])
;
```

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

### Static factory: fromDefaults(DataTable $dataTable)

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTableState.md

Builds a pre-request state from the table options. It initializes start and length from the 'start' and 'pageLength' options, and applies the 'order' option entries as order-by columns.

```APIDOC
## Static factory: fromDefaults(DataTable $dataTable)

### Description
Builds a pre-request state from the table options. It initializes start and length from the 'start' and 'pageLength' options, and applies the 'order' option entries as order-by columns.

### Method
Static factory

### Signature
```php
public static function fromDefaults(DataTable $dataTable): static
```

### Parameters
- **$dataTable** (DataTable) - Required - The owning DataTable instance.

### Behavior
- `start` falls back to 0 when the 'start' option is absent.
- Each 'order' entry is a `[columnIndex, direction]` pair.
- The initial state is not marked as a callback (`isCallback()` is false, `isInitial()` is false).

```

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

### AdapterInterface methods

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/Adapters.md

Defines the contract for adapters: configure() for initial setup and getData() to process state into a ResultSetInterface. getData() with $raw=true requests unnormalized values for exporters supporting raw data.

```php
public function configure(array $options): void;
public function getData(DataTableState $state, bool $raw = false): ResultSetInterface;
```

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

### Common column options example

Source: https://github.com/omines/datatables-bundle/blob/master/docs/source/index.html.md

Shows how to configure columns with common options like label, className, render (format string or callable), and raw output. The render callable receives the value and context.

```php
# Some example columns
$table
    ->add('firstName', TextColumn::class, ['label' => 'customer.name', 'className' => 'bold'])
    ->add('lastName', TextColumn::class, ['render' => '<strong>%s</strong>', 'raw' => true])
    ->add('email', TextColumn::class, ['render' => function($value, $context) {
        return sprintf('<a href="%s">%s</a>', $value, $value);
    }])
;
```

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

### createAdapter() usage example

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTable.md

Creates an ORMAdapter with an entity option.

```php
$table->createAdapter(ORMAdapter::class, ['entity' => Employee::class]);
```

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

### Instantiator constructor with locators array

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DependencyInjection.md

Constructor accepts an array mapping base class names to ServiceLocator instances. The example shows the expected structure for adapter, column, type, and exporter services.

```php
public function __construct(array $locators = [])   // @param ServiceLocator<SupportedTypes>[] $locators
```

```php
[
    AdapterInterface::class       => ServiceLocator(adapter services),
    AbstractColumn::class         => ServiceLocator(column services),
    DataTableTypeInterface::class => ServiceLocator(type services),
    DataTableExporterInterface::class => ServiceLocator(exporter services),
]
```

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

### Deploy Assets via Console

Source: https://github.com/omines/datatables-bundle/blob/master/docs/source/index.html.md

Run the assets:install command to deploy the included Javascript files to your application's public folder. Optional if using Assetic or WebPack.

```bash
bin/console assets:install
```

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

### Export path pagination example

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTableState.md

Sets pagination to browse the entire table for export, as used by DataTableExporterManager.

```php
// Export path — browse the entire table; see DataTableExporterManager
$state->setStart(0)->setLength(null);
```

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

### Catching exceptions in consumer code

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/errors.md

Use try-catch blocks to handle configuration and dependency exceptions when creating a table, and export-time failures when getting the response. MissingDependencyException indicates missing Doctrine bundle, InvalidConfigurationException indicates bad entity FQCN or invalid options, and UnknownDataTableExporterException indicates an unknown exporter name in the request.

```php
use Omines\DataTablesBundle\Exception\InvalidConfigurationException;
use Omines\DataTablesBundle\Exception\MissingDependencyException;
use Omines\DataTablesBundle\Exception\UnknownDataTableExporterException;

try {
    $table = $factory->create()
        ->add('name', TextColumn::class)
        ->createAdapter(ORMAdapter::class, ['entity' => Employee::class])
        ->handleRequest($request);
} catch (MissingDependencyException $e) {
    // doctrine bundle not installed — fall back to ArrayAdapter
} catch (InvalidConfigurationException $e) {
    // bad entity FQCN / invalid options
}

// Export-time failures
try {
    $response = $table->getResponse(); // throws UnknownDataTableExporterException for bad '_exporter'
} catch (UnknownDataTableExporterException $e) {
    // unknown exporter name in request
}
```

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

### Controller usage of DataTableFactory::createFromType

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTableFactory.md

Example showing how to create a table from a reusable type, passing type options and handling the request.

```php
// Reusable type, see DataTableTypeInterface below
$table = $factory->createFromType(PersonTableType::class, ['showEmail' => true])
    ->handleRequest($request);
```

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

### handleRequest() usage example

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTable.md

Creates a table, handles the request, and returns the response if it's a callback; otherwise renders a template.

```php
$table = $dataTableFactory->create()->add(...)->createAdapter(...)->handleRequest($request);
if ($table->isCallback()) {
    return $table->getResponse();
}
return $this->render('table.html.twig', ['datatable' => $table]);
```

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

### Chained setter usage example

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTable.md

Example of chaining setters on a DataTable instance. Configures name, method, persist state, language source, translation domain, and a transformer that combines firstName and lastName into fullName.

```php
$table
    ->setName('employees')
    ->setMethod(Request::METHOD_GET)
    ->setPersistState('query')
    ->setLanguageFromCDN(false)
    ->setTranslationDomain('my_domain')
    ->setTransformer(function (array $row, $entity): array {
        $row['fullName'] = $row['firstName'] . ' ' . $row['lastName'];
        return $row;
    });
```

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

### PersonTableType implementation example

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTableFactory.md

Example implementation of DataTableTypeInterface. Adds columns and configures an ORM adapter with criteria based on options.

```php
class PersonTableType implements DataTableTypeInterface
{
    public function configure(DataTable $dataTable, array $options): void
    {
        $dataTable
            ->add('firstName', TextColumn::class)
            ->add('lastName', TextColumn::class)
            ->createAdapter(ORMAdapter::class, [
                'entity' => Person::class,
                'criteria' => $options['showEmail'] ? [new SearchCriteriaProvider()] : [/* custom */],
            ]);
    }
}
```

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

### Controller setup with DataTableFactory and ArrayAdapter

Source: https://github.com/omines/datatables-bundle/blob/master/docs/source/index.html.md

Creates a DataTable instance in a Symfony controller, adds two TextColumn columns, binds an ArrayAdapter with static data, and handles callbacks. The handleRequest method processes callbacks like Symfony's Form component; if it is a callback, the table provides the response, otherwise a template is rendered with the table as a parameter.

```php
use Omines\DataTablesBundle\Adapter\ArrayAdapter;
use Omines\DataTablesBundle\Column\TextColumn;
use Omines\DataTablesBundle\DataTableFactory;

class MyController extends Controller
{
    public function showAction(Request $request, DataTableFactory $dataTableFactory)
    {
        $table = $dataTableFactory->create()
            ->add('firstName', TextColumn::class)
            ->add('lastName', TextColumn::class)
            ->createAdapter(ArrayAdapter::class, [
                ['firstName' => 'Donald', 'lastName' => 'Trump'],
                ['firstName' => 'Barack', 'lastName' => 'Obama'],
            ])
            ->handleRequest($request);
        
        if ($table->isCallback()) {
            return $table->getResponse();
        }
        
        return $this->render('list.html.twig', ['datatable' => $table]);
    }
}
```

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

### Minimal custom adapter shape

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/Adapters.md

Example custom adapter extending AbstractAdapter. prepareQuery() sets total and filtered rows and stores payload; mapPropertyPath() maps field to array index; getResults() yields from payload.

```php
// Minimal custom adapter shape
class MyAdapter extends AbstractAdapter
{
    protected function prepareQuery(AdapterQuery $query): void
    {
        $query->setTotalRows($this->count());
        $query->setFilteredRows($this->countFiltered($query->getState()));
        $query->set('payload', $this->fetch($query->getState()));
    }

    protected function mapPropertyPath(AdapterQuery $query, AbstractColumn $column): ?string
    {
        return "[{$column->getField()}]";
    }

    protected function getResults(AdapterQuery $query): \Traversable
    {
        yield from $query->get('payload');
    }
}
```

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

### start and length pagination method signatures

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTableState.md

Getters and setters for pagination. getLength() returns null when the client requests all records (-1). setStart() with a negative value triggers E_USER_DEPRECATED and coerces to 0. setLength() with a value less than 1 triggers E_USER_DEPRECATED and coerces to null; applyParameters() performs the same coercion without deprecation.

```php
public function getStart(): int
public function setStart(int $start): static
public function getLength(): ?int
public function setLength(?int $length): static
```

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

### add() usage example

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTable.md

Adds a TextColumn named 'firstName' with a label option.

```php
$table->add('firstName', TextColumn::class, ['label' => 'customer.first_name']);
```

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

### ArrayAdapter usage with DataTable factory

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/Adapters.md

Example of creating a DataTable with ArrayAdapter, adding text columns, and handling the request. The adapter serves the provided array as the data source.

```php
use Omines\DataTablesBundle\Adapter\ArrayAdapter;

$table = $factory->create()
    ->add('firstName', TextColumn::class)
    ->add('lastName', TextColumn::class)
    ->createAdapter(ArrayAdapter::class, $employees)
    ->handleRequest($request);
```

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

### MongoDBAdapter usage with MongoDB

Source: https://github.com/omines/datatables-bundle/blob/master/docs/source/index.html.md

Use the MongoDBAdapter to use MongoDB collections as a data source. Requires the `mongodb/mongodb` package. The example configures a collection name and adds columns.

```php
use Omines\DataTablesBundle\Adapter\MongoDB\MongoDBAdapter;

$table = $this->createDataTable()
    ->add('name', TextColumn::class)
    ->add('company', TextColumn::class)
    ->createAdapter(MongoDBAdapter::class, [
        'collection' => 'myCollection',
    ]);
```

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

### Basic ORMAdapter setup with Doctrine ORM

Source: https://github.com/omines/datatables-bundle/blob/master/docs/source/index.html.md

Configures a DataTable using the ORMAdapter with an Employee entity. The first two columns automatically default their field option to the root entity, and the AutomaticQueryBuilder and SearchCriteriaProvider are injected by default.

```php
use Omines\DataTablesBundle\Adapter\Doctrine\ORMAdapter;

$table = $this->createDataTable()
    ->add('firstName', TextColumn::class)
    ->add('lastName', TextColumn::class)
    ->add('company', TextColumn::class, ['field' => 'company.name'])
    ->createAdapter(ORMAdapter::class, [
        'entity' => Employee::class,
    ]);
```

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

### Custom query and criteria chain with error handling

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/ORMAdapter.md

Configures ORMAdapter with a custom query builder and criteria processors. The 'hydrate' option uses HYDRATE_ARRAY. Wraps creation in a try-catch for MissingDependencyException when doctrine is not installed. Includes SearchCriteriaProvider to keep default search behavior.

```php
// Custom query + criteria chain with error handling for missing doctrine
use Doctrine\ORM\QueryBuilder;
use Omines\DataTablesBundle\Exception\MissingDependencyException;

try {
    $table->createAdapter(ORMAdapter::class, [
        'entity' => Employee::class,
        'hydrate' => \Doctrine\ORM\Query::HYDRATE_ARRAY,
        'query' => function (QueryBuilder $builder) {
            $builder
                ->select('e')
                ->addSelect('c')
                ->from(Employee::class, 'e')
                ->leftJoin('e.company', 'c');
        },
        'criteria' => [
            function (QueryBuilder $builder) {
                $builder->andWhere($builder->expr()->like('c.name', ':test'))
                    ->setParameter('test', '%ny 2%');
            },
            new SearchCriteriaProvider(), // keep default search behavior
        ],
    ]);
} catch (MissingDependencyException $e) {
    // doctrine/doctrine-bundle not installed
}
```

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

### Controller usage of DataTableFactory::create

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTableFactory.md

Example controller action that creates a DataTable with per-call options, adds a column, creates an adapter, handles the request, and returns either the callback response or renders a template.

```php
// In a controller:
public function index(Request $request, DataTableFactory $factory): Response
{
    $table = $factory->create(['pageLength' => 25])
        ->add('firstName', TextColumn::class)
        ->createAdapter(ArrayAdapter::class, [/* ... */])
        ->handleRequest($request);

    return $table->isCallback() ? $table->getResponse() : $this->render('index.html.twig', ['datatable' => $table]);
}
```

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

### Using ORMAdapter PRE_QUERY event for cache configuration

Source: https://github.com/omines/datatables-bundle/blob/master/docs/source/index.html.md

Shows how to listen to the ORMAdapterEvents::PRE_QUERY event to configure query caching. The event is dispatched after the QueryBuilder builds the Query and before iteration starts, useful for enabling result and query cache.

```php
$table->createAdapter(ORMAdapter::class, [
    'entity' => Employee::class,
    'query' => function (QueryBuilder $builder) {
        $builder
            ->select('e')
            ->addSelect('c')
            ->from(Employee::class, 'e')
            ->leftJoin('e.company', 'c')
        ;
    },
]);

$table->addEventListener(ORMAdapterEvents::PRE_QUERY, function(ORMAdapterQueryEvent $event) {
    $event->getQuery()->useResultCache(true)->useQueryCache(true);
});
```

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

### ElasticaAdapter usage with Elasticsearch

Source: https://github.com/omines/datatables-bundle/blob/master/docs/source/index.html.md

Use the ElasticaAdapter to query Elasticsearch indexes as a data source. Requires the `ruflin/elastica` package. The example configures a client host and index, and defines columns with field mappings and options.

```php
use Omines\DataTablesBundle\Adapter\Elasticsearch\ElasticaAdapter;

$table = $this->createDataTable()
    ->setName('log')
    ->add('timestamp', DateTimeColumn::class, ['field' => '@timestamp', 'format' => 'Y-m-d H:i:s', 'orderable' => true])
    ->add('level', MapColumn::class, [
        'default' => '<span class="label label-default">Unknown</span>',
        'map' => ['Emergency', 'Alert', 'Critical', 'Error', 'Warning', 'Notice', 'Info', 'Debug'],
    ])
    ->add('message', TextColumn::class, ['globalSearchable' => true])
    ->createAdapter(ElasticaAdapter::class, [
        'client' => ['host' => 'elasticsearch'],
        'index' => 'logstash-*',
    ]);
```

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

### Deploy documentation with deploy.sh

Source: https://github.com/omines/datatables-bundle/blob/master/docs/README.md

Run this script to update the documentation on the gh-pages branch. Requires push privileges on that branch.

```bash
./deploy.sh
```

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

### DataTablePreResponseEvent usage example

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/Events.md

Example of adding a listener for the PRE_RESPONSE event to modify columns before the response is generated.

```php
use Omines\DataTablesBundle\DataTableEvents;
use Omines\DataTablesBundle\Event\DataTablePreResponseEvent;

$dataTable->addEventListener(DataTableEvents::PRE_RESPONSE, function (DataTablePreResponseEvent $event) {
    $table = $event->getTable();
    $table
        ->add('extraColumn', TextColumn::class)
        ->remove('obsoleteColumn');
});
```

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

### prepareQuery

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/ElasticaAdapter.md

Prepares the query context by creating an Elastica client and setting default column fields. Throws an exception if the Elastica library is missing.

```APIDOC
## prepareQuery

### Description
Prepares the query context by creating an Elastica client and setting default column fields. Throws an exception if the Elastica library is missing.

### Method
prepareQuery

### Signature
`public function prepareQuery(AdapterQuery $query): void`

### Parameters
- **query** (AdapterQuery) - Required - The query context.

### Behavior
- Throws `MissingDependencyException` if `\Elastica\Client` does not exist.
- Stores a new `\Elastica\Client` instance on the query context.
- Defaults each column's `field` option to the column name if not set.
```

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

### DataTablePreResponseEvent (Event Listener Example)

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/Events.md

Example of using the DataTablePreResponseEvent to modify the table before the response is generated. This event is dispatched before the response is created and is the recommended hook for last-minute column manipulation.

```APIDOC
## `DataTablePreResponseEvent` Event Listener

### Description
Example of using the DataTablePreResponseEvent to modify the table before the response is generated. This event is dispatched before the response is created and is the recommended hook for last-minute column manipulation.

### Event Name
`DataTableEvents::PRE_RESPONSE`

### Listener Signature
```php
function (DataTablePreResponseEvent $event) { ... }
```

### Usage Example
```php
use Omines\DataTablesBundle\DataTableEvents;
use Omines\DataTablesBundle\Event\DataTablePreResponseEvent;

$dataTable->addEventListener(DataTableEvents::PRE_RESPONSE, function (DataTablePreResponseEvent $event) {
    $table = $event->getTable();
    $table
        ->add('extraColumn', TextColumn::class)
        ->remove('obsoleteColumn');
});
```

### Description
This example demonstrates how to add and remove columns on the table just before the response is generated. The `getTable()` method returns the DataTable instance, and the `add()` and `remove()` methods are used to modify columns.
```

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

### DataTableFactory::create implementation with defaults

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTableFactory.md

Shows how create() instantiates a DataTable, merges options, and applies global defaults via setters, including method, persist state, translation domain, language from CDN, and template.

```php
(new DataTable($this->eventDispatcher, $this->exporterManager, array_merge($config['options'] ?? [], $options), $this->instantiator))
    ->setRenderer($this->renderer)
    ->setMethod($config['method'] ?? Request::METHOD_POST)
    ->setPersistState($config['persist_state'] ?? 'fragment')
    ->setTranslationDomain($config['translation_domain'] ?? 'messages')
    ->setLanguageFromCDN($config['language_from_cdn'] ?? true)
    ->setTemplate($config['template'] ?? DataTable::DEFAULT_TEMPLATE, $config['template_parameters'] ?? [])
;
```

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

### AbstractAdapter::prepareQuery

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/Adapters.md

Abstract hook for subclasses to build the query and set total/filtered row counts.

```APIDOC
## AbstractAdapter::prepareQuery

### Description
Abstract hook for subclasses to build the query and set total/filtered row counts.

### Method
```php
abstract protected function prepareQuery(AdapterQuery $query): void;
```

### Parameters
- `$query` (AdapterQuery) - Required - The query object to prepare.

### Details
- Subclasses must implement this method to build the query, set totals (`setTotalRows`/`setFilteredRows`), and set the identifier path.
```

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

### addEventListener() usage example

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTable.md

Adds a listener for the PRE_RESPONSE event that adds an email column to the table.

```php
$table->addEventListener(DataTableEvents::PRE_RESPONSE, function (DataTablePreResponseEvent $event) {
    $event->getTable()->add('email', TextColumn::class);
});
```

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

### addOrderBy usage example

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTableState.md

Adds a descending sort on the lastName column using the column name lookup.

```php
$state->addOrderBy($dataTable->getColumnByName('lastName'), DataTable::SORT_DESCENDING);
```

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

### AbstractAdapter abstract hooks

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/Adapters.md

Subclasses must implement prepareQuery() to build query and set totals, mapPropertyPath() to map columns to property paths, and getResults() returning a Traversable of value arrays/objects readable via PropertyAccess.

```php
abstract protected function prepareQuery(AdapterQuery $query): void;
abstract protected function mapPropertyPath(AdapterQuery $query, AbstractColumn $column): ?string;
abstract protected function getResults(AdapterQuery $query): \Traversable;   // \Traversable<mixed[]>
```

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

### buildOptions method signature

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/MongoDBAdapter.md

Builds the options array for the query.

```php
private function buildOptions(DataTableState $state): array
```

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

### TwigColumn usage example

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/Columns.md

Adds a TwigColumn to a table with a custom template for rendering buttons.

```php
$table->add('buttons', TwigColumn::class, [
    'className' => 'buttons',
    'template' => 'tables/buttonbar.html.twig',
]);
```

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

### ORMAdapter::configure

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/ORMAdapter.md

Configures the adapter with an options array. Resolves options against the option definitions and runs post-configuration logic.

```APIDOC
## Method: configure

### Description
Resolves the provided options array against the adapter's option definitions and triggers post-configuration processing.

### Method
`configure`

### Signature
```php
public function configure(array $options): void
```

### Parameters
- **$options** (`array`) - Required - Options array to configure the adapter.

### Options
| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `entity` | `string` (FQCN) | **yes** | — | Root entity class; resolved to an `EntityManager` via `ManagerRegistry::getManagerForClass()` |
| `hydrate` | `int` | no | `Query::HYDRATE_OBJECT` | `Doctrine\ORM\AbstractQuery::HYDRATE_*` constant |
| `query` | `QueryBuilderProcessorInterface\|callable\|array` | no | `[]` | Query builders; empty → `AutomaticQueryBuilder` is inserted in `afterConfiguration()` |
| `criteria` | `QueryBuilderProcessorInterface\|callable\|array\|null` | no | `[new SearchCriteriaProvider()]` | Criteria processors (search/filters) applied after counts |
```

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

### createAdapter() / setAdapter() / getAdapter() signatures

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTable.md

createAdapter() resolves adapter and calls setAdapter(). setAdapter() calls configure() only when options are not null. getAdapter() throws InvalidConfigurationException when no adapter is set.

```php
public function createAdapter(string $adapter, array $options = []): static
public function setAdapter(AdapterInterface $adapter, ?array $options = null): static
public function getAdapter(): AdapterInterface
```

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

### mapPropertyPath(AdapterQuery $query, AbstractColumn $column): ?string

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/MongoDBAdapter.md

Maps a column's field to a PropertyAccess path. For example, `address.city` becomes `[address][city]`.

```APIDOC
## mapPropertyPath(AdapterQuery $query, AbstractColumn $column): ?string

### Description
Maps a column's field to a PropertyAccess path.

### Method
mapPropertyPath

### Parameters
- **query** (AdapterQuery) - Required - The query object.
- **column** (AbstractColumn) - Required - The column whose field is mapped.

### Returns
- **?string** - The PropertyAccess path, e.g., `[address][city]` for field `address.city`.
```

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

### initialize method signature

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/AbstractColumn.md

Called by DataTable::add() to resolve options and store name, index, and dataTable. Not called directly by application code.

```php
public function initialize(string $name, int $index, array $options, DataTable $dataTable): void
```

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

### MapColumn usage example

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/Columns.md

Adds a MapColumn to a table, mapping 'f' to 'Female' and 'm' to 'Male', with a default of 'not provided' for unmapped values.

```php
$table->add('gender', MapColumn::class, [
    'map' => ['f' => 'Female', 'm' => 'Male'],
    'default' => 'not provided',
]);
```

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

### Static factory fromDefaults signature

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTableState.md

Builds a pre-request state from table options. Returns a static instance.

```php
public static function fromDefaults(DataTable $dataTable): static
```

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

### buildFilter(DataTableState $state): array

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/MongoDBAdapter.md

Builds the MongoDB filter array. Starts with configured filters and adds an $or clause for global searchable columns using case-insensitive regex.

```APIDOC
## buildFilter(DataTableState $state): array

### Description
Builds the MongoDB filter array.

### Method
buildFilter

### Parameters
- **state** (DataTableState) - Required - The current DataTable state.

### Returns
- **array** - The filter array, e.g., `['$or' => [...]]` when global search is present.

### Behavior
- Starts with the configured `filters`.
- When a global search is present, wraps an `$or` over every global-searchable column using case-insensitive regex.

### Code Example
```php
foreach ($state->getDataTable()->getColumns() as $column) {
    if ($column->isGlobalSearchable()) {
        $filter[] = [$column->getField() => new \MongoDB\BSON\Regex($globalSearch, 'i')];
    }
}
$filter = ['$or' => $filter];
```
```

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

### Build options with limit, skip, and sort

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/MongoDBAdapter.md

Sets limit, skip, and sort options based on state.

```php
$options = [
    'limit' => $state->getLength() ?? 0,
    'skip' => $state->getLength() ? $state->getStart() : 0,
    'sort' => [],
];

foreach ($state->getOrderBy() as list($column, $direction)) {
    if ($column->isOrderable() && $orderField = $column->getOrderField()) {
        $options['sort'][$orderField] = self::SORT_MAP[$direction];
    }
}
```

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

### JavaScript: Add export button using initDataTables.exportBtnAction

Source: https://github.com/omines/datatables-bundle/blob/master/docs/source/index.html.md

Initializes the DataTable with a custom button that triggers the 'excel' exporter. Requires the Buttons extension and the server-side setup.

```javascript
$(function() {
    $('#table').initDataTables({{ datatable_settings(datatable) }}, {
        dom:'<"html5buttons"B>lTfgitp',
        buttons: [
            {
                text: 'Export to Excel',
                action: $.fn.initDataTables.exportBtnAction('excel', {{ datatable_settings(datatable) }})
            }
        ]
    });
});
```

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

### getOptions

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTable.md

Returns all options as an associative array.

```APIDOC
## getOptions

### Description
Returns all options as an associative array.

### Method
GET

### Endpoint
Not applicable (PHP method)

### Parameters
None

### Response
- **array** - Array of options (string keys, mixed values)
```

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

### Adapter creation with collection and filters

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/MongoDBAdapter.md

Creates a MongoDB adapter with a collection and base filters.

```php
$table->createAdapter(MongoDBAdapter::class, [
    'collection' => $this->mongoClient->selectCollection('db', 'people'),
    'filters' => [['deleted' => false]],
]);
```

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

### configure

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/ElasticaAdapter.md

Resolves adapter options and stores client settings and indices. This method is called during adapter initialization.

```APIDOC
## configure

### Description
Resolves adapter options and stores client settings and indices. This method is called during adapter initialization.

### Method
configure

### Signature
`public function configure(array $options): void`

### Parameters
- **options** (array) - Required - Options array containing 'client' and 'index' keys.

### Options
- **client** (array<string, mixed>) - Required - Client connection settings passed to the `\Elastica\Client` constructor (e.g. `['host' => 'elasticsearch']`).
- **index** (string|string[]) - Required - Index name, or list of index names (supports wildcards like `logstash-*`).
```

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

### Twig template with initDataTables

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/Twig.md

Example Twig template that initializes DataTables on a div with id 'presidents'. Loads the DataTables bundle JavaScript and calls initDataTables with the datatable_settings output.

```twig
<div id="presidents">Loading...</div>
<script src="{{ asset('bundles/datatables/js/datatables.js') }}"></script>
<script>
$(function() {
    $('#presidents').initDataTables({{ datatable_settings(datatable) }});
});
</script>
```

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

### Catching exceptions in consumer code

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/errors.md

Demonstrates how to catch exceptions thrown by the DataTables bundle during table creation and response generation. The first try block handles configuration and dependency errors, while the second handles unknown exporter names.

```APIDOC
## Catching exceptions in consumer code

### Description
Shows how to catch exceptions thrown by the DataTables bundle during table creation and response generation.

### Code Example
```php
use Omines\DataTablesBundle\Exception\InvalidConfigurationException;
use Omines\DataTablesBundle\Exception\MissingDependencyException;
use Omines\DataTablesBundle\Exception\UnknownDataTableExporterException;

try {
    $table = $factory->create()
        ->add('name', TextColumn::class)
        ->createAdapter(ORMAdapter::class, ['entity' => Employee::class])
        ->handleRequest($request);
} catch (MissingDependencyException $e) {
    // doctrine bundle not installed — fall back to ArrayAdapter
} catch (InvalidConfigurationException $e) {
    // bad entity FQCN / invalid options
}

// Export-time failures
try {
    $response = $table->getResponse(); // throws UnknownDataTableExporterException for bad '_exporter'
} catch (UnknownDataTableExporterException $e) {
    // unknown exporter name in request
}
```
```

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

### AbstractAdapter getData (final)

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/Adapters.md

Template-method driver: creates AdapterQuery, calls prepareQuery(), builds property map, iterates results, sets DT_RowId, transforms values, applies table transformer, and returns ResultSet. Throws LogicException if row counts not set.

```php
final public function getData(DataTableState $state, bool $raw = false): ResultSetInterface
```

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

### configureOptions resolver defaults and requirements

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/ElasticaAdapter.md

Sets default values for 'client' and 'index' options, marks them as required, and enforces allowed types. 'client' must be an array, 'index' can be a string or array of strings.

```php
$resolver
    ->setDefaults([
        'client' => [],
        'index' => [],
    ])
    ->setRequired(['client', 'index'])
    ->setAllowedTypes('client', 'array')
    ->setAllowedTypes('index', ['string', 'array'])
;
```

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

### applyParameters method signature

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTableState.md

Public method that loads DataTables callback parameters on top of existing state values. Accepts a ParameterBag containing request parameters such as draw, _init, _exporter, start, length, search.value, order[], and columns[][search][value].

```php
public function applyParameters(ParameterBag $parameters): void
```

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

### createAdapter

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTable.md

Creates and sets an adapter by resolving the given FQCN or service id through the Instantiator.

```APIDOC
## createAdapter

### Description
Creates and sets an adapter by resolving the given FQCN or service id through the Instantiator.

### Method
`createAdapter`

### Signature
```php
public function createAdapter(string $adapter, array $options = []): static
```

### Parameters
- **$adapter** (string) - Required - FQCN or registered service id of the adapter
- **$options** (array) - Optional - Options passed to the adapter's `configure()` method

### Example
```php
$table->createAdapter(ORMAdapter::class, ['entity' => Employee::class]);
```
```

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

### getAdapter

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTable.md

Returns the current adapter. Throws an exception if no adapter is set.

```APIDOC
## getAdapter

### Description
Returns the current adapter. Throws an exception if no adapter is set.

### Method
`getAdapter`

### Signature
```php
public function getAdapter(): AdapterInterface
```

### Exceptions
- `Exception\InvalidConfigurationException` if no adapter is set
```

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

### render method implementation

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/AbstractColumn.md

If the render option is a string, uses it as a sprintf format with the value. If it is callable, calls it with ($value, $context, $this). Otherwise returns the value unchanged.

```php
if (is_string($render = $this->options['render'])) {
    return sprintf($render, $value);
} elseif (is_callable($render)) {
    return call_user_func($render, $value, $context, $this);
}
return $value;
```

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

### DataTablesBundle build and getContainerExtension methods

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DependencyInjection.md

Defines the bundle's build method to add a compiler pass and the getContainerExtension method to return the DataTablesExtension. The bundle alias is 'datatables'.

```php
public function build(ContainerBuilder $container): void
{
    parent::build($container);
    $container->addCompilerPass(new LocatorRegistrationPass());
}

public function getContainerExtension(): ?ExtensionInterface
{
    return new DataTablesExtension();
}
```

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

### ORMAdapter configure method signature

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/ORMAdapter.md

Public method to configure the adapter. Resolves options against configureOptions() and then runs afterConfiguration().

```php
public function configure(array $options): void
```

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

### buildQuery

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/ElasticaAdapter.md

Builds an Elastica query object, adding a MultiMatch query for global search if present. This is an internal helper method.

```APIDOC
## buildQuery

### Description
Builds an Elastica query object, adding a MultiMatch query for global search if present. This is an internal helper method.

### Method
buildQuery

### Signature
`protected function buildQuery(DataTableState $state): \Elastica\Query`

### Parameters
- **state** (DataTableState) - Required - The current DataTable state.

### Returns
- (\Elastica\Query) - The constructed query object.
```

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

### Autowire DataTableFactory in a controller and fetch from container

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DependencyInjection.md

Shows two ways to obtain the DataTableFactory: constructor autowiring in a controller and direct container access in a service. The first uses the readonly promoted property syntax; the second retrieves the service by its class name.

```php
// Autowiring in a controller
use Omines\DataTablesBundle\DataTableFactory;

public function __construct(private readonly DataTableFactory $factory) {}

// Or via the container in a service
$factory = $container->get(DataTableFactory::class);
```

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

### isInitial, isCallback, getDataTable method signatures

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTableState.md

Signatures for checking the bootstrap request state, whether applyParameters() has run, and retrieving the DataTable instance.

```php
public function isInitial(): bool   // true for the '_init' bootstrap request
public function isCallback(): bool  // true once applyParameters() ran
public function getDataTable(): DataTable
```

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

### configure(array $options): void

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/MongoDBAdapter.md

Configures the MongoDB adapter with required collection and optional filters. The collection must be a MongoDB\Collection instance, and filters are base predicates merged into the query filter.

```APIDOC
## configure(array $options): void

### Description
Configures the MongoDB adapter with required collection and optional filters.

### Method
configure

### Parameters
- **collection** (MongoDB\Collection) - Required - The MongoDB collection instance.
- **filters** (array) - Optional - Base $filter predicates always applied (merged into the query filter). Default: []

### Request Example
```php
$table->createAdapter(MongoDBAdapter::class, [
    'collection' => $this->mongoClient->selectCollection('db', 'people'),
    'filters' => [['deleted' => false]],
]);
```
```

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

### ArrayAdapter configure with data array

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/Adapters.md

Configures an ArrayAdapter with an array of associative arrays as the data source. The options array is the data itself.

```php
$table->createAdapter(ArrayAdapter::class, [
    ['firstName' => 'Donald', 'lastName' => 'Trump'],
    ['firstName' => 'Barack', 'lastName' => 'Obama'],
]);
```

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

### setTemplate

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTable.md

Sets the template and parameters for rendering. Returns static for chaining.

```APIDOC
## setTemplate

### Description
Sets the template and parameters for rendering. Returns static for chaining.

### Method
POST

### Endpoint
Not applicable (PHP method)

### Parameters
- `template` (string) - Required - The template name
- `parameters` (array) - Optional - Template parameters (default: [])

### Response
- **static** - The DataTable instance for chaining
```

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

### AutomaticQueryBuilder constructor signature

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/ORMAdapter.md

Default query processor when 'query' is empty. The constructor requires an EntityManagerInterface and ClassMetadata. process() maps table columns to select columns and joins, then sets from() with the lowercased short class name (e.g., 'employee'), addSelect()s each mapped column, and adds join()s for associations. Partial DQL queries are no longer supported (removed in 0.9.0). Throws \LogicException ("Class %s has no identifiers") when an entity has no identifier fields.

```php
public function __construct(EntityManagerInterface $em, ClassMetadata $metadata)
```

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

### Set Instantiator arguments with service locators

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DependencyInjection.md

Rewrites the Instantiator service arguments to four service locators built from tags: adapter, column, type, and exporter. Each locator is a private service_locator referencing services tagged with datatables.{baseTag}.

```php
$container->getDefinition(Instantiator::class)->setArguments([[
    AdapterInterface::class        => $this->registerLocator($container, 'adapter'),
    AbstractColumn::class          => $this->registerLocator($container, 'column'),
    DataTableTypeInterface::class  => $this->registerLocator($container, 'type'),
    DataTableExporterInterface::class => $this->registerLocator($container, 'exporter'),
]]);
```

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

### prepareQuery(AdapterQuery $query): void

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/MongoDBAdapter.md

Prepares the query by setting default field options, building filter and options, counting total and filtered rows, and executing the find operation. The cursor is stored in the query with a type map for array results.

```APIDOC
## prepareQuery(AdapterQuery $query): void

### Description
Prepares the query by setting default field options, building filter and options, counting total and filtered rows, and executing the find operation.

### Method
prepareQuery

### Parameters
- **query** (AdapterQuery) - Required - The query object to prepare.

### Behavior
- Defaults every column's `field` to the column name when unset.
- Builds filter and options from the state.
- Sets total rows to the entire collection count.
- Sets filtered rows to the count with the filter.
- Runs `$cursor = $this->collection->find($filter, $options)` and sets the type map so documents come back as arrays.

### Code Example
```php
$cursor->setTypeMap(['root' => 'array', 'document' => 'array']);
$query->set('cursor', $cursor);
```
```

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

### AbstractFilter::configureOptions

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/Filters.md

Base class requires template_html and template_js keys.

```php
protected function configureOptions(OptionsResolver $resolver): static
{
    $resolver->setRequired([
        'template_html',
        'template_js',
    ]);
    return $this;
}
```

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

### getOption

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DataTable.md

Returns a specific option value by name, or null if not set.

```APIDOC
## getOption

### Description
Returns a specific option value by name, or null if not set.

### Method
GET

### Endpoint
Not applicable (PHP method)

### Parameters
- `name` (string) - Required - The option name

### Response
- **mixed** - The option value or null
```

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

### ORMAdapterQueryEvent constructor and getQuery method signatures

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/Events.md

Shows the public API of ORMAdapterQueryEvent: the constructor accepts a Query object and getQuery() returns it.

```php
public function __construct(Query $query)   // @param Query<mixed> $query
public function getQuery(): Query          // @return Query<mixed>
```

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

### LocatorRegistrationPass process method signature

Source: https://github.com/omines/datatables-bundle/blob/master/_autodocs/api-reference/DependencyInjection.md

Public method of the compiler pass that rewrites the Instantiator service arguments. Called during container compilation.

```php
public function process(ContainerBuilder $container): void
```
Tokens:
Raw