Callbacks

Callbacks allow you to hook into the configuration and lifecycle of filter elements and list types using PHP 8 attributes. This mechanism replaces the traditional Contao DCA callbacks with a more flexible, service-oriented approach.

1. Registration

To register a callback, use the #[AsFilterCallback] or #[AsListCallback] attribute on a service method.

#[AsFilterCallback]

Used for logic related to Filter Elements.

use HeimrichHannot\FlareBundle\DependencyInjection\Attribute\AsFilterCallback;
use HeimrichHannot\FlareBundle\Specification\FilterDefinition;
use HeimrichHannot\FlareBundle\Specification\ListSpecification;
use HeimrichHannot\FlareBundle\Query\ListExecutionContext;

#[AsFilterCallback(
    element: 'my_filter_type',
    target: 'fields.myField.options',
    priority: 10
)]
public function getMyFieldOptions(
    ListSpecification $list, 
    FilterDefinition $filter, 
    ListExecutionContext $context
): array {
    return [
        'value1' => 'Label 1',
        'value2' => 'Label 2',
    ];
}

#[AsListCallback]

Used for logic related to List Types.

use HeimrichHannot\FlareBundle\DependencyInjection\Attribute\AsListCallback;

#[AsListCallback(
    element: 'my_list_type',
    target: 'config.onload'
)]
public function handleOnLoad(): void
{
    // Custom logic when the list type is loaded
}

2. Filter Element Callbacks

Filterconfig.onloadExecuted when the DataContainer object for the filter element is initialized.

Available Arguments

Type or classNotes

FilterModel

The current filter element model

ListModel

The list model the filter belongs to

DataContainer

The Contao DataContainer instance

Return Type

void

Example Implementation

#[AsFilterCallback(element: 'my_filter', target: 'config.onload')]
public function onLoad(FilterModel $filter, DataContainer $dc): void
{
  // Custom logic
}

Filterfields.<field>.optionsUsed to dynamically provide options for a filter element field.

Available Arguments

Type or classNotes

FilterModel

The current filter element model

ListModel

The list model the filter belongs to

DataContainer

The Contao DataContainer instance

FilterDefinition

Internal filter definition

ListSpecification

The list specification

ListExecutionContext

Current execution context

array $tables

Associated tables for the list

string $targetTable

The target table for the filter

Return Type

array

Return an associative array of selectable options where the array key is the stored value and the array value is the backend label.

Example Implementation

#[AsFilterCallback(element: 'my_filter', target: 'fields.myField.options')]
public function getOptions(array $tables, string $targetTable): array
{
  return ['val' => 'Label'];
}

Filterfields.<field>.loadTriggered when a filter element field value is loaded from the database.

Available Arguments

Type or classNotes

mixed $value

Positional

The raw value from the database

FilterModel

The current filter element model

ListModel

The list model

DataContainer

The Contao DataContainer instance

Return Type

mixed

Return the transformed value that should be used in the backend form after loading.

Example Implementation

#[AsFilterCallback(element: 'my_filter', target: 'fields.myField.load')]
public function onLoad($value, FilterModel $filter): mixed
{
  return $value === 'foo' ? 'bar' : $value;
}

Filterfields.<field>.saveTriggered before a filter element field value is saved to the database.

Available Arguments

Type or classNotes

mixed $value

Positional

The value to be saved

FilterModel

The current filter element model

ListModel

The list model

DataContainer

The Contao DataContainer instance

Return Type

mixed

Return the normalized value that should actually be persisted to the database.

Example Implementation

#[AsFilterCallback(element: 'my_filter', target: 'fields.myField.save')]
public function onSave($value, FilterModel $filter): mixed
{
  return strtoupper($value);
}

3. List Type Callbacks

Listconfig.onloadTriggered when the list configuration (DCA) is initialized.

Available Arguments

Type or classNotes

ListModel

The list model

DataContainer

The Contao DataContainer instance

Return Type

void

Example Implementation

#[AsListCallback(element: 'my_list', target: 'config.onload')]
public function onLoad(ListModel $list, DataContainer $dc): void
{
  // Modify DCA or state
}

Listfields.<field>.optionsUsed to provide options for list configuration fields.

Available Arguments

Type or classNotes

ListModel

The list model

DataContainer

The Contao DataContainer instance

Return Type

array

Return an associative array of selectable options where the array key is the stored value and the array value is the backend label.

Example Implementation

#[AsListCallback(element: 'my_list', target: 'fields.myField.options')]
public function getOptions(ListModel $list): array
{
  return ['a' => 'Option A'];
}

Listfields.<field>.loadTriggered when a list configuration field value is loaded.

Available Arguments

Type or classNotes

mixed $value

Positional

The raw value

ListModel

The list model

DataContainer

The Contao DataContainer instance

Return Type

mixed

Return the transformed value that should be shown in the backend form after loading.

Example Implementation

#[AsListCallback(element: 'my_list', target: 'fields.myField.load')]
public function onLoad($value): mixed
{
  return $value;
}

Listfields.<field>.saveTriggered before a list configuration field value is saved.

Available Arguments

Type or classNotes

mixed $value

Positional

The value to be saved

ListModel

The list model

DataContainer

The Contao DataContainer instance

Return Type

mixed

Return the normalized value that should be persisted for the list configuration field.

Example Implementation

#[AsListCallback(element: 'my_list', target: 'fields.myField.save')]
public function onSave($value): mixed
{
  return $value;
}

4. Argument Resolution Details

• Positional Arguments: Some targets provide a value as the first argument (marked as Positional above).
• Type-hinted Arguments: You can type-hint any of the following classes to have them injected:
  • HeimrichHannot\FlareBundle\Model\FilterModel
  • HeimrichHannot\FlareBundle\Model\ListModel
  • Contao\DataContainer
  • HeimrichHannot\FlareBundle\Specification\FilterDefinition
  • HeimrichHannot\FlareBundle\Specification\ListSpecification
  • HeimrichHannot\FlareBundle\Query\ListExecutionContext
• Named Arguments: For targets like options, additional data is passed that can be accessed by the parameter name (e.g., array $tables, string $targetTable).