Symfony UX Autocomplete

https://github.com/symfony/ux-autocomplete
Admin
Symfony UX Autocomplete provides Javascript-powered auto-completion functionality for Symfony forms.
Tokens:31,786
Snippets:455
Trust Score:9.5
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Pagination Example

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/endpoints.md

Example flow of next_page URL generation across multiple request pages.

```text
Page 1: GET /autocomplete/product?query=laptop
Response: next_page = "/autocomplete/product?query=laptop&page=2"

Page 2: GET /autocomplete/product?query=laptop&page=2
Response: next_page = "/autocomplete/product?query=laptop&page=3"

Page 3: GET /autocomplete/product?query=laptop&page=3
Response: next_page = null  (no more pages)
```

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

### isGranted() Configuration Examples

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/wrapped-entity-type-autocompleter.md

Examples of configuring the security option using roles or callables.

```php
// Check role:
'security' => 'ROLE_ADMIN'

// Callable:
'security' => function(Security $security) {
    return $security->isGranted('EDIT', $this);
}
```

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

### Full Implementation Example

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/base-entity-autocomplete-type.md

A complete example showing the class definition and usage within a form factory.

```php
use Symfony\UX\Autocomplete\Form\BaseEntityAutocompleteType;
use Symfony\UX\Autocomplete\Form\AsEntityAutocompleteField;

#[AsEntityAutocompleteField(alias: 'product')]
class ProductAutocompleteType extends BaseEntityAutocompleteType
{
    // Inherits all functionality from BaseEntityAutocompleteType
    // Auto-generates URL from the alias
}

// Usage in form:
$form = $formFactory->create(MyFormType::class, $data, [
    'product_field' => [
        'class' => Product::class,
        'autocomplete' => true,
        'max_results' => 15,
        'searchable_fields' => ['name', 'sku'],
    ]
]);
```

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

### getGroupBy() Configuration Examples

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/wrapped-entity-type-autocompleter.md

Examples of configuring the group_by option using property paths or callables.

```php
'group_by' => 'category.name'
// Results grouped by category name

'group_by' => function($entity) {
    return strtoupper($entity->getStatus());
}
```

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

### setOptions() Usage Example

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/wrapped-entity-type-autocompleter.md

Example of passing extra options to the autocompleter.

```php
$autocompleter->setOptions([
    'extra_options' => [
        'category_id' => 5,
        'department' => 'sales',
    ]
]);
```

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

### Autocomplete Request Example

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-autocomplete-controller.md

Example of a GET request to the autocomplete endpoint.

```http
GET /autocomplete/nonexistent
```

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

### getAttributes() Configuration Examples

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/wrapped-entity-type-autocompleter.md

Examples of configuring additional_attributes using static arrays or dynamic callables.

```php
// Static attributes:
'additional_attributes' => ['data-category' => 'featured']

// Dynamic attributes:
'additional_attributes' => function($entity) {
    return [
        'data-stock' => $entity->getStockCount(),
        'data-available' => $entity->isAvailable() ? 'true' : 'false',
    ];
}
```

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

### Full Form Type Options Example

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/configuration.md

A comprehensive example demonstrating various configuration options for the Autocomplete form type.

```php
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

class ProductFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder->add('product', ProductAutocompleteType::class, [
            // Autocomplete
            'autocomplete' => true,
            'autocomplete_url' => null,  // Auto-generated from attribute
            
            // Search
            'searchable_fields' => ['name', 'sku', 'category.name'],
            'filter_query' => null,
            
            // Display
            'choice_label' => 'name',
            'choice_value' => 'id',
            'additional_attributes' => function($entity) {
                return ['data-price' => $entity->getPrice()];
            },
            
            // Pagination
            'max_results' => 15,
            'min_characters' => 2,
            
            // Grouping
            'group_by' => 'category.name',
            
            // Security
            'security' => 'ROLE_USER',
            
            // UI
            'preload' => 'focus',
            'reset_on_focus' => false,
            'options_as_html' => false,
            'allow_options_create' => false,
            
            // Messages
            'loading_more_text' => 'Loading more products...',
            'no_results_found_text' => 'No products found',
            'no_more_results_text' => 'All products shown',
            'create_option_text' => 'Create product "%placeholder%"',
            
            // Tom Select
            'tom_select_options' => [
                'maxItems' => 1,
            ],
            
            // Runtime
            'extra_options' => [
                'category_id' => 5,
            ],
        ]);
    }

    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults([
            'data_class' => Order::class,
        ]);
    }
}
```

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

### shortName() Usage Examples

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/as-entity-autocomplete-field.md

Examples demonstrating how class names are converted to snake_case aliases.

```php
shortName(ProductAutocompleteType::class);
// Returns: 'product_autocomplete'

shortName('App\\Form\\UserType');
// Returns: 'user_type'

shortName('MyCustomType');
// Returns: 'my_custom_type'
```

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

### Grouped Results Example

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-results.md

Demonstrates how to structure results when using optgroups.

```php
$results = new AutocompleteResults(
    results: [
        ['value' => '1', 'text' => 'Laptop', 'group_by' => ['Electronics']],
        ['value' => '2', 'text' => 'Novel', 'group_by' => ['Books']],
    ],
    hasNextPage: false,
    optgroups: [
        ['value' => 'Electronics', 'label' => 'Electronics'],
        ['value' => 'Books', 'label' => 'Books'],
    ],
);

// JSON response structure
[
    'results' => [
        'options' => [...],  // results array
        'optgroups' => [...]  // optgroups array
    ],
    'next_page' => null
]
```

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

### Install Assets for WebpackEncore

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/doc/index.rst

Install necessary JavaScript assets and restart the watch process when using WebpackEncore.

```terminal
$ npm install --force
$ npm run watch
```

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

### Auto-Alias Generation Examples

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/as-entity-autocomplete-field.md

Additional examples of how shortName() processes various class names.

```php
shortName(ProductAutocompleteType::class)        // → 'product_autocomplete'
shortName(UserType::class)                        // → 'user_type'
shortName(MyCustomFieldType::class)               // → 'my_custom_field_type'
shortName('App\\Form\\Order\\OrderFieldType')    // → 'order_field_type'
shortName('SimpleType')                           // → 'simple_type'
```

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

### Install Symfony UX Autocomplete dependencies

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/assets/README.md

Commands to install the required PHP package and the corresponding npm package version.

```shell
composer require symfony/ux-autocomplete:2.23.0
npm add @symfony/ux-autocomplete@2.23.0
```

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

### Autocomplete GET Request

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-autocomplete-controller.md

Example of a standard GET request to the autocomplete endpoint with query and page parameters.

```http
GET /autocomplete/product?query=laptop&page=1
```

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

### Nested Association Path Example

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-search-util.md

Demonstrates multi-level nesting for association paths.

```php
'publisher.country.name'  // product.publisher.country.name
```

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

### Configure Tom Select Plugins

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/doc/index.rst

Example of enabling Tom Select plugins via the tom_select_options configuration.

```php
$resolver->setDefaults([
    'class' => Ingredient::class,
    'tom_select_options' => [
        'plugins' => [
            // Enable Input Autogrow plugin
            'input_autogrow',
```

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

### Usage Example for fetchResults

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-results-executor.md

Demonstrates retrieving an autocompleter from the registry and fetching results for a specific query.

```php
$executor = $container->get('ux.autocomplete.results_executor');
$autocompleter = $registry->getAutocompleter('product');

$results = $executor->fetchResults($autocompleter, 'laptop', 1);

echo count($results->results);  // number of results on page 1
echo $results->hasNextPage;     // true if page 2 exists
```

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

### Install Symfony UX Autocomplete

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/doc/index.rst

Use Composer to add the bundle to your Symfony project.

```terminal
$ composer require symfony/ux-autocomplete
```

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

### Autocomplete Query Example

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/endpoints.md

Demonstrates the internal QueryBuilder logic applied when a search query is received.

```php
// Autocompleter:
$qb->where('p.name LIKE :query OR p.description LIKE :query')
   ->setParameter('query', '%laptop%')
```

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

### Grouped Result Output

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-results-executor.md

Example of the array structure when grouping is applied.

```php
[
    'value' => '1',
    'text' => 'Product',
    'group_by' => ['Electronics'],
]
```

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

### Example Usage of getPropertyDataType

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-metadata.md

Demonstrates how to retrieve data types for various entity properties.

```php
$meta->getPropertyDataType('name');        // 'string'
$meta->getPropertyDataType('price');       // 'decimal'
$meta->getPropertyDataType('isActive');    // 'boolean'
$meta->getPropertyDataType('category');    // 'many' or 'one'
$meta->getPropertyDataType('id');          // 'integer' or 'uuid'
```

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

### Calculate Checksum Example

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/checksum-calculator.md

Retrieves the service from the container and generates a checksum for a data array.

```php
$calculator = $container->get('ux.autocomplete.checksum_calculator');
$data = ['category' => '5', 'type' => 'featured'];
$checksum = $calculator->calculateForArray($data);
// Returns: 'abc123def456...' (base64)
```

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

### Implement setOptions method

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/options-aware-entity-autocompleter-interface.md

Example implementation of the setOptions method within an autocompleter class.

```php
public function setOptions(array $options): void
{
    $this->extraOptions = $options[self::EXTRA_OPTIONS] ?? [];
}
```

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

### Handle Permission Denied

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/endpoints.md

Example response when the current user lacks access to the requested autocompleter.

```http
Request: GET /autocomplete/admin_products?query=test

Response:
HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "message": "Access denied from autocompleter class."
}
```

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

### Optgroup support structure

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-controller.md

Example JSON structure for defining optgroups in search results.

```json
// Response:
{
    "results": {
        "options": [...],
        "optgroups": [
            { "value": "Category", "label": "Category" }
        ]
    }
}

// Rendered as HTML optgroups
```

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

### AutocompleteResults Usage Example

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-results.md

Demonstrates creating an AutocompleteResults instance and the resulting JSON structure.

```php
// Created automatically by AutocompleteResultsExecutor
$results = new AutocompleteResults(
    results: [
        ['value' => '1', 'text' => 'Product One', 'data-stock' => 10],
        ['value' => '2', 'text' => 'Product Two', 'data-stock' => 5],
    ],
    hasNextPage: true,
    optgroups: [],
);

// Converted to JSON response
[
    'results' => [
        ['value' => '1', 'text' => 'Product One', 'data-stock' => 10],
        ['value' => '2', 'text' => 'Product Two', 'data-stock' => 5],
    ],
    'next_page' => '/autocomplete/product?query=search&page=2'
]
```

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

### Optgroup Structure

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-results.md

Example structure for defining optgroups in autocomplete results.

```php
[
    ['value' => 'Electronics', 'label' => 'Electronics'],
    ['value' => 'Books', 'label' => 'Books'],
]
```

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

### getInstance() Usage Example

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/as-entity-autocomplete-field.md

Retrieving an attribute instance from a form type class.

```php
$attribute = AsEntityAutocompleteField::getInstance(ProductAutocompleteType::class);
if ($attribute) {
    echo $attribute->getAlias();  // 'product'
    echo $attribute->getRoute();  // 'ux_entity_autocomplete'
}
```

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

### Supported Entity Structure

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-metadata-factory.md

Example of a valid entity structure with a single primary key.

```php
class Product
{
    #[Id]
    #[GeneratedValue]
    private int $id;
    
    // Single key: ✓ Supported
}
```

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

### Handle Tampered Extra Options

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/endpoints.md

Example response when the extra_options parameter has been modified or tampered with.

```http
Request: GET /autocomplete/product?query=test&extra_options=tampered

Response:
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "message": "The extra options have been tampered with."
}
```

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

### Alias Naming Convention

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/base-entity-autocomplete-type.md

Examples of how class names are converted to aliases when no alias is explicitly provided.

```text
// ProductAutocompleteType -> product_autocomplete
// UserType -> user_type
```

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

### Implement full OptionsAwareEntityAutocompleterInterface

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/options-aware-entity-autocompleter-interface.md

A complete example of an autocompleter class implementing the interface to filter queries based on stored options.

```php
use Symfony\UX\Autocomplete\OptionsAwareEntityAutocompleterInterface;
use Doctrine\ORM\EntityRepository;
use Doctrine\ORM\QueryBuilder;
use Symfony\Bundle\SecurityBundle\Security;

class ProductAutocompleter implements OptionsAwareEntityAutocompleterInterface
{
    private array $options = [];

    public function getEntityClass(): string
    {
        return Product::class;
    }

    public function createFilteredQueryBuilder(EntityRepository $repository, string $query): QueryBuilder
    {
        $qb = $repository->createQueryBuilder('p')
            ->where('p.name LIKE :query')
            ->setParameter('query', '%' . $query . '%');

        // Use options if set
        if (isset($this->options['extra_options']['category'])) {
            $qb->andWhere('p.category = :category')
                ->setParameter('category', $this->options['extra_options']['category']);
        }

        return $qb;
    }

    public function getLabel(object $entity): string
    {
        return $entity->getName();
    }

    public function getValue(object $entity): mixed
    {
        return $entity->getId();
    }

    public function getAttributes(object $entity): array
    {
        return [];
    }

    public function isGranted(Security $security): bool
    {
        return true;
    }

    public function getGroupBy(): mixed
    {
        return null;
    }

    public function setOptions(array $options): void
    {
        $this->options = $options;
    }
}
```

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

### Get Label

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/wrapped-entity-type-autocompleter.md

Determines the display label for an entity based on the choice_label option.

```php
public function getLabel(object $entity): string
```

```php
// Property path:
'choice_label' => 'name'
// Returns: $entity->name

// Callable:
'choice_label' => function($entity) {
    return $entity->getName() . ' (' . $entity->getSku() . ')';
}
```

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

### GET /{alias}

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-autocomplete-controller.md

Fetches autocomplete results based on the provided autocompleter alias.

```APIDOC
## GET /{alias}

### Description
Fetches autocomplete results for a specific autocompleter alias. The controller validates the alias and processes any provided extra options.

### Method
GET

### Endpoint
/{alias}

### Parameters
#### Path Parameters
- **alias** (string) - Required - The identifier of the autocompleter to use.

#### Query Parameters
- **_extra** (string) - Optional - Base64-encoded JSON containing extra options with a SHA256 HMAC checksum.

### Response
#### Success Response (200)
- Returns the autocomplete results formatted by the AutocompleteResultsExecutor.

#### Error Response (404)
- Returned when the autocompleter alias does not exist.

#### Error Response (400)
- Returned when extra options are invalid, missing a checksum, or have been tampered with.
```

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

### Example Usage of getIdValue

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-metadata.md

Demonstrates extracting the primary key value from a specific entity instance.

```php
$product = $repository->find(123);
$meta = $factory->create(Product::class);
$id = $meta->getIdValue($product);  // Returns: '123'
```

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

### Handle Invalid Autocompleter Alias

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/endpoints.md

Example response when requesting an autocompleter alias that does not exist.

```http
Request: GET /autocomplete/unknown?query=test

Response:
HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "message": "No autocompleter found for \"unknown\". Available autocompleters are: (product, category)"
}
```

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

### Configure TextType Field

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/doc/index.rst

Example of enabling autocomplete on a standard TextType field with custom Tom Select options.

```php
$builder
    // ...
    ->add('tags', TextType::class, [
        'autocomplete' => true,
        'tom_select_options' => [
            'create' => true,
            'createOnBlur' => true,
            'delimiter' => ',',
        ],
        // 'autocomplete_url' => '... optional: custom endpoint, see below',
    ])
;
```

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

### Search Field Validation Examples

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-search-util.md

Shows valid and invalid formats for defining searchable association fields.

```php
// Error: bare association without field
'category'  // ✗ InvalidArgumentException

// Correct: association with field
'category.name'  // ✓ Valid
```

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

### GET /autocomplete/{alias}

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-autocomplete-controller.md

Retrieves a list of autocomplete suggestions based on a search query and optional pagination.

```APIDOC
## GET /autocomplete/{alias}

### Description
Fetches autocomplete results for a specific entity autocompleter identified by the alias.

### Method
GET

### Endpoint
/autocomplete/{alias}

### Parameters
#### Path Parameters
- **alias** (string) - Required - The identifier for the autocompleter registry entry.

#### Query Parameters
- **query** (string) - Optional - Search query from the user (default: '').
- **page** (int) - Optional - Page number for pagination (default: 1).
- **extra_options** (string) - Optional - Base64-encoded JSON options.

### Response
#### Success Response (200)
- **results** (array|object) - The list of suggestions or grouped options.
- **next_page** (string|null) - The URL for the next page of results, or null if no more pages exist.

### Response Example
{
    "results": [
        {
            "value": "1",
            "text": "Product One",
            "data-stock": 10
        }
    ],
    "next_page": "/autocomplete/product?query=laptop&page=2"
}
```

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

### GET /autocomplete/{alias}

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/endpoints.md

Retrieves a list of autocomplete suggestions based on the provided alias and search query.

```APIDOC
## GET /autocomplete/{alias}

### Description
Fetches autocomplete suggestions for a specific entity type defined by the alias.

### Method
GET

### Endpoint
/autocomplete/{alias}

### Parameters
#### Path Parameters
- **alias** (string) - Required - The autocompleter alias (e.g., product, user_search)

#### Query Parameters
- **query** (string) - Optional - Search query from user input
- **page** (int) - Optional - Page number for pagination (1-indexed)
- **extra_options** (string) - Optional - Base64-encoded, HMAC-signed form options

### Request Example
GET /autocomplete/product?query=laptop&page=1
```

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

### Define Form with Extra Options

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/doc/index.rst

Example of using extra_options to pass data that persists across Ajax requests.

```php
// src/Form/FoodForm.php
// ...

class FoodForm extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $currentFoodId = $builder->getData()->getId();

        $builder
            ->add('food', FoodAutocompleteField::class, [
                'extra_options' => [
                    'excluded_foods' => [$currentFoodId],
                ],
            )
        ;
    }
}
```

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

### EntityAutocompleteController Security Validation

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/checksum-calculator.md

Example of the full cycle for signing extra options on the frontend and validating them on the server.

```php
// Frontend encodes and signs:
$extraOptions = ['category' => '5'];
$checksum = $calculator->calculateForArray($extraOptions);
$extraOptions['@checksum'] = $checksum;
$encoded = base64_encode(json_encode($extraOptions));

// Frontend sends: extra_options=<encoded>

// Server validates:
$decoded = json_decode(base64_decode($encodedOptions), true);
if (!hash_equals(
    $calculator->calculateForArray($decoded),
    $decoded['@checksum']
)) {
    throw new BadRequestHttpException('Tampered with');
}
```

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

### Define Form with Query Builder

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/doc/index.rst

Example of a form type using a query_builder that fails to persist state during Ajax calls.

```php
// src/Form/FoodForm.php
// ...

class FoodForm extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $currentFoodId = $builder->getData()->getId();

        $builder
            ->add('food', FoodAutocompleteField::class, [
                'query_builder' => function (EntityRepository $er) {
                    $qb = $er->createQueryBuilder('o');

                    return $qb->andWhere($qb->expr()->notIn('o.id', [$currentFoodId]));
                };
            ])
        ;
    }
}
```

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

### Configure UI Behavior

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/configuration.md

Settings for preloading, focus behavior, HTML rendering, and option creation.

```php
'preload' => false,   // Don't preload
'preload' => true,    // Load immediately
'preload' => 'focus', // Load on focus
```

```php
'reset_on_focus' => true,  // Reset on focus
```

```php
'options_as_html' => true,  // Allow HTML in option labels
```

```php
'allow_options_create' => true,
```

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

### Validation Error Messages

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-metadata-factory.md

Examples of RuntimeExceptions thrown when entity validation fails.

```text
RuntimeException: There is no Doctrine Entity Manager defined for the "[class]" class
```

```text
RuntimeException: Autocomplete does not support Doctrine entities with composite 
primary keys (such as the ones used in the "[class]" entity).
```

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

### EntitySearchUtil Constructor

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-search-util.md

Initializes the utility with an EntityMetadataFactory.

```php
public function __construct(
    private EntityMetadataFactory $metadataFactory,
)
```

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

### Project File Structure

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/README.md

Displays the directory layout of the documentation and source files for the project.

```text
/workspace/home/output/
├── README.md                          (this file)
├── types.md                           (all type definitions)
├── endpoints.md                       (HTTP API specification)
├── configuration.md                   (form field options)
├── errors.md                          (error catalog)
└── api-reference/
    ├── autocompleter-registry.md
    ├── entity-autocompleter-interface.md
    ├── options-aware-entity-autocompleter-interface.md
    ├── autocomplete-results.md
    ├── autocomplete-results-executor.md
    ├── entity-autocomplete-controller.md
    ├── base-entity-autocomplete-type.md
    ├── as-entity-autocomplete-field.md
    ├── autocomplete-choice-type-extension.md
    ├── entity-search-util.md
    ├── entity-metadata.md
    ├── entity-metadata-factory.md
    ├── wrapped-entity-type-autocompleter.md
    ├── autocomplete-controller.md
    └── checksum-calculator.md
```

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

### Configure preload behavior

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-choice-type-extension.md

Determine when initial results should be loaded.

```php
'preload' => 'focus',   // Load when field is focused (default)
'preload' => true,      // Load immediately
'preload' => false,     // Don't preload
```

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

### Translation Domain Usage

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-choice-type-extension.md

Example of how message strings are translated using the AutocompleteBundle domain.

```php
$translator->trans('Loading more results...', [], 'AutocompleteBundle')
```

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

### Stimulus Controller Attributes

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-choice-type-extension.md

Example of the HTML attributes added to the select element by the extension.

```html
<select
    data-controller="symfony--ux-autocomplete--autocomplete"
    data-symfony--ux-autocomplete--autocomplete-url-value="/api/autocomplete/products"
    data-symfony--ux-autocomplete--autocomplete-max-results-value="10"
    data-symfony--ux-autocomplete--autocomplete-loading-more-text-value="Loading more results..."
>
```

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

### Enable option creation

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-choice-type-extension.md

Allow users to create new options by typing.

```php
'allow_options_create' => true,
```

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

### Constructor Definition

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-metadata.md

Initializes the metadata wrapper with Doctrine's ClassMetadata.

```php
public function __construct(
    private ClassMetadata $metadata,
)
```

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

### Pass Tom Select options

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-choice-type-extension.md

Directly configure the underlying Tom Select library.

```php
'tom_select_options' => [
    'maxItems' => 3,
    'copyClassesToDropdown' => true,
    'plugins' => ['drag_drop', 'clear_button'],
]
```

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

### Initialize FormView

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-choice-type-extension.md

Method signature for initializing the Stimulus controller on a rendered form field.

```php
public function finishView(FormView $view, FormInterface $form, array $options): void
```

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

### Initialize AutocompleteChoiceTypeExtension

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-choice-type-extension.md

Constructor for the extension, requiring a ChecksumCalculator and an optional TranslatorInterface.

```php
public function __construct(
    private readonly ChecksumCalculator $checksumCalculator,
    private readonly ?TranslatorInterface $translator = null,
)
```

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

### Create Method Usage

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-metadata-factory.md

Retrieves the factory from the container and generates metadata for a specific entity class.

```php
$factory = $container->get('ux.autocomplete.entity_metadata_factory');
$metadata = $factory->create(Product::class);

echo $metadata->getAllPropertyNames();
```

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

### Get Value

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/wrapped-entity-type-autocompleter.md

Extracts the form field value for an entity based on the choice_value option.

```php
public function getValue(object $entity): string
```

```php
// Default: uses entity ID
// Returns: $entity->getId()

// Property path:
'choice_value' => 'uuid'
// Returns: $entity->uuid

// Callable:
'choice_value' => function($entity) {
    return $entity->getSlug();
}
```

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

### EntityAutocompleteController Constructor

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-autocomplete-controller.md

Initializes the controller with the necessary registry, executor, URL generator, and checksum calculator services.

```php
public function __construct(
    private AutocompleterRegistry $autocompleteFieldRegistry,
    private AutocompleteResultsExecutor $autocompleteResultsExecutor,
    private UrlGeneratorInterface $urlGenerator,
    private ChecksumCalculator $checksumCalculator,
)
```

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

### Set create option text

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-choice-type-extension.md

Customize the message for creating new options, using %placeholder% for the input value.

```php
'create_option_text' => 'Create "%placeholder%"',
// Result: "Create "laptop""
```

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

### TomSelect Configuration Objects

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-controller.md

Configuration structures for different autocomplete modes.

```typescript
{
    render: {
        no_results: () => noResultsFoundText,
        option_create: (data) => createOptionText,
    },
    plugins: {
        // clear_button if single select (not disabled)
        // remove_button if multiple select
        // virtual_scroll if remote data
    },
    onItemAdd: () => clearTextbox(),
    closeAfterSelect: true,
    // ... other common settings
}
```

```typescript
{
    firstUrl: (query) => `${url}?query=${query}`,
    load: (query, callback) => fetch(url).then(...),
    shouldLoad: (query) => checkMinCharacters(),
    optgroupField: 'group_by',
    score: () => 1,  // No client-side filtering
    render: {
        option: (item) => htmlOrEscaped(item),
        loading_more: () => loadingMoreText,
        no_more_results: () => noMoreResultsText,
        no_results: () => noResultsFoundText,
    },
    preload: preloadValue,
}
```

```typescript
{
    maxOptions: optionCount,
    // No remote loading
    // shouldLoad returns false for non-selects without URL
}
```

```typescript
{
    score: (search) => scoringFunction(stripTags(item)),
    render: {
        item: (item) => `<div>${item.text}</div>`,
        option: (item) => `<div>${item.text}</div>`,
    },
}
```

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

### Method Definitions

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/as-entity-autocomplete-field.md

Methods for retrieving attribute configuration and generating aliases.

```php
public function getAlias(): ?string
```

```php
public function getRoute(): string
```

```php
public static function shortName(string $class): string
```

```php
public static function getInstance(string $class): ?self
```

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

### Implement Custom Autocompleter

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/README.md

Create a custom autocompleter by implementing EntityAutocompleterInterface and registering it in the DI container.

```php
use Symfony\UX\Autocomplete\EntityAutocompleterInterface;
use Symfony\Bundle\SecurityBundle\Security;

class CustomAutocompleter implements EntityAutocompleterInterface
{
    public function getEntityClass(): string { return Product::class; }
    
    public function createFilteredQueryBuilder($repo, $query): QueryBuilder {
        // Custom query logic
    }
    
    public function getLabel($entity): string { return $entity->getName(); }
    public function getValue($entity) { return $entity->getId(); }
    public function getAttributes($entity): array { return []; }
    public function isGranted(Security $security): bool { return true; }
    public function getGroupBy() { return null; }
}
```

```php
// In DI container
$container->set('app.product_autocompleter', CustomAutocompleter::class)
    ->addTag('ux.autocomplete.entity_autocompleter', [
        'alias' => 'product',
        'route' => 'ux_entity_autocomplete',
    ]);
```

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

### Entity Search Utility Usage

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-metadata-factory.md

Shows how EntitySearchUtil internally leverages the factory to process search clauses.

```php
$util = $container->get('ux.autocomplete.entity_search_util');
// Internally uses EntityMetadataFactory to understand property types
$util->addSearchClause($qb, 'search', Product::class, ['name', 'category.name']);
```

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

### Get Entity Class

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/wrapped-entity-type-autocompleter.md

Retrieves the entity class name defined in the form's class option.

```php
public function getEntityClass(): string
```

```php
// Reads from form option:
public function configureOptions(OptionsResolver $resolver): void
{
    $resolver->setDefault('class', Product::class);
}

// Autocompleter returns:
$autocompleter->getEntityClass();  // 'App\Entity\Product'
```

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

### Encoding Extra Options for Autocomplete

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/endpoints.md

Demonstrates how to serialize, sign, and encode extra options for the autocomplete request.

```php
// Form field passes:
['category' => '5', 'type' => 'featured']

// Encoded as:
$options = ['category' => '5', 'type' => 'featured'];
$checksum = hash_hmac('sha256', json_encode($options), $secret, true);
$options['@checksum'] = base64_encode($checksum);
$encoded = base64_encode(json_encode($options));

// URL: ?extra_options=<encoded>
```

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

### Implement getLabel

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-autocompleter-interface.md

Returns the display label for an entity instance.

```php
public function getLabel(object $entity): string
{
    return $entity->getName();
}
```

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

### Configure Runtime Extra Options

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/configuration.md

Pass extra context to the autocomplete endpoint and access it on the server side.

```php
'extra_options' => [
    'category_id' => 5,
    'department' => 'sales',
]
```

```php
// In OptionsAwareEntityAutocompleterInterface::setOptions()
public function setOptions(array $options): void
{
    $extraOptions = $options['extra_options'] ?? [];
    // $extraOptions = ['category_id' => 5, 'department' => 'sales']
}
```

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

### Build Form Method

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/base-entity-autocomplete-type.md

Configures the form builder and sets the autocomplete URL attribute.

```php
public function buildForm(FormBuilderInterface $builder, array $options): void
```

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

### Throw LogicException for Missing Doctrine

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/errors.md

Triggered when the bundle attempts to use entity features without the Doctrine ORM installed.

```php
if (null === $this->registry) {
    throw new \LogicException(
        'Doctrine must be installed to use the entity features of AutocompleteBundle.'
    );
}
```

```bash
composer require symfony/doctrine-bundle doctrine/orm
```

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

### Register Autocomplete Bundle

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/configuration.md

Explicitly register the bundle in the configuration file.

```php
Symfony\UX\Autocomplete\AutocompleteBundle::class => ['all' => true],
```

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

### ChecksumCalculator Constructor

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/checksum-calculator.md

Initializes the calculator with the application's kernel secret.

```php
public function __construct(
    private readonly string $secret,
)
```

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

### GET /autocomplete/{alias}

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/errors.md

Endpoint for retrieving autocomplete results. This endpoint may return various HTTP errors based on the validity of the request and the autocompleter configuration.

```APIDOC
## GET /autocomplete/{alias}

### Description
Retrieves autocomplete results for a specific autocompleter alias. Errors may occur if the alias is invalid, extra options are malformed, or access is denied.

### Method
GET

### Endpoint
/autocomplete/{alias}

### Parameters
#### Path Parameters
- **alias** (string) - Required - The identifier of the autocompleter.

#### Query Parameters
- **query** (string) - Optional - The search term.
- **extra_options** (string) - Optional - Base64 encoded JSON string containing additional options.

### Response
#### Success Response (200)
- **results** (array) - List of autocomplete results.

#### Error Responses
- **400 Bad Request** - Returned when extra options are invalid, missing a checksum, or the checksum is invalid.
- **403 Forbidden** - Returned when the user does not have permission to access the autocompleter.
- **404 Not Found** - Returned when the specified autocompleter alias does not exist.
```

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

### Configure HTML rendering for options

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-choice-type-extension.md

Control whether option labels are rendered as HTML or escaped text.

```php
'options_as_html' => true,  // HTML is rendered
'options_as_html' => false, // HTML is escaped (default)
```

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

### Configure Options Method

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/base-entity-autocomplete-type.md

Defines the default options and validation rules for the autocomplete form.

```php
public function configureOptions(OptionsResolver $resolver): void
```

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

### Deterministic Checksum Verification

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/checksum-calculator.md

Demonstrates that the calculator produces identical hashes regardless of key order due to recursive sorting.

```php
$checksum1 = $calculator->calculateForArray(['a' => 1, 'b' => 2]);
$checksum2 = $calculator->calculateForArray(['b' => 2, 'a' => 1]);
// $checksum1 === $checksum2 (keys are sorted)
```

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

### Extend Tom Select with Stimulus

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/doc/index.rst

Create a custom Stimulus controller to intercept pre-connect and connect events for advanced Tom Select configuration.

```javascript
// assets/controllers/custom-autocomplete_controller.js
import { Controller } from '@hotwired/stimulus';

export default class extends Controller {
    initialize() {
        this._onPreConnect = this._onPreConnect.bind(this);
        this._onConnect = this._onConnect.bind(this);
    }

    connect() {
        this.element.addEventListener('autocomplete:pre-connect', this._onPreConnect);
        this.element.addEventListener('autocomplete:connect', this._onConnect);
    }

    disconnect() {
        // You should always remove listeners when the controller is disconnected to avoid side-effects
        this.element.removeEventListener('autocomplete:connect', this._onConnect);
        this.element.removeEventListener('autocomplete:pre-connect', this._onPreConnect);
    }

    _onPreConnect(event) {
        // TomSelect has not been initialized - options can be changed
        console.log(event.detail.options); // Options that will be used to initialize TomSelect
        event.detail.options.onChange = (value) => {
            // ...
        };
    }

    _onConnect(event) {
        // TomSelect has just been initialized and you can access details from the event
        console.log(event.detail.tomSelect); // TomSelect instance
        console.log(event.detail.options); // Options used to initialize TomSelect
    }
}
```

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

### Define setOptions method signature

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/options-aware-entity-autocompleter-interface.md

The interface method definition for setting form options.

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

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

### Constructing AutocompleterRegistry

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocompleter-registry.md

The constructor requires a ServiceLocator containing tagged autocompleter services.

```php
public function __construct(
    private ServiceLocator $autocompletersLocator,
)
```

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

### Import Stimulus Controller

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-choice-type-extension.md

Import statement for the Stimulus controller provided by the bundle.

```javascript
import AutocompleteController from '@symfony/ux-autocomplete/controller';
```

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

### Create EntityMetadata instance

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-metadata.md

Retrieve the factory from the container to generate metadata for a specific entity class.

```php
$factory = $container->get('ux.autocomplete.entity_metadata_factory');
$meta = $factory->create(Product::class);
```

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

### Handle LogicException for Form Options

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/errors.md

Occurs when setOptions is called after the form has already been instantiated.

```php
if (null !== $this->form) {
    throw new \LogicException(
        'The options can only be set before the form is created.'
    );
}
```

```text
LogicException: The options can only be set before the form is created.
```

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

### Pass extra options

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-choice-type-extension.md

Send additional context to the autocomplete endpoint.

```php
'extra_options' => [
    'category_id' => 5,
    'department' => 'sales',
]
```

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

### Using addSearchClause

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-search-util.md

Demonstrates how to apply a search clause to a QueryBuilder for specific entity properties.

```php
$util = $container->get('ux.autocomplete.entity_search_util');
$qb = $repository->createQueryBuilder('p');

$util->addSearchClause(
    $qb,
    'laptop',
    Product::class,
    ['name', 'description', 'category.name']
);

// Executes query with WHERE clause added
```

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

### Implement createFilteredQueryBuilder

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-autocompleter-interface.md

Creates a query builder filtered by the provided search query.

```php
public function createFilteredQueryBuilder(EntityRepository $repository, string $query): QueryBuilder
{
    return $repository->createQueryBuilder('p')
        ->where('p.name LIKE :query')
        ->setParameter('query', '%' . $query . '%');
}
```

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

### Constructor for BaseEntityAutocompleteType

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/base-entity-autocomplete-type.md

Initializes the form type with the required URL generator for endpoint routing.

```php
public function __construct(
    private UrlGeneratorInterface $urlGenerator,
)
```

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

### Retrieve All Property Names

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-metadata.md

Fetches all field names defined on the entity.

```php
public function getAllPropertyNames(): array
```

```php
$meta = $factory->create(Product::class);
$properties = $meta->getAllPropertyNames();
// Returns: ['id', 'name', 'description', 'price', 'categoryId', ...]
```

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

### Validation Exceptions

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/base-entity-autocomplete-type.md

Common exceptions thrown during configuration validation.

```text
RuntimeException: Both the searchable_fields and filter_query options cannot be set.
```

```text
LogicException: You must either provide your own autocomplete_url, or add 
#[AsEntityAutocompleteField] attribute to "ProductType".
```

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

### Dispatch pre-connect event

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-controller.md

Dispatched before TomSelect is created to allow configuration customization.

```typescript
dispatch('pre-connect', { options: tomSelectConfig })
```

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

### Format Choice Labels

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/configuration.md

Specify how entities are displayed in the dropdown using property names or callables.

```php
// Property
'choice_label' => 'name',

// Callable
'choice_label' => function($entity) {
    return $entity->getName() . ' (' . $entity->getSku() . ')';
}
```

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

### TomSelect Initialization Method

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-controller.md

Internal method responsible for configuring TomSelect based on the data source type.

```typescript
initializeTomSelect(): void
```

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

### Invoke setOptions in controller

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/options-aware-entity-autocompleter-interface.md

Usage pattern for checking if an autocompleter supports options and passing them from the request.

```php
if ($autocompleter instanceof OptionsAwareEntityAutocompleterInterface) {
    $extraOptions = $this->getExtraOptions($request);
    $autocompleter->setOptions([self::EXTRA_OPTIONS => $extraOptions]);
}
```

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

### Create Method Signature

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-metadata-factory.md

Defines the signature for creating an EntityMetadata instance from a fully-qualified entity class name.

```php
public function create(?string $entityFqcn): EntityMetadata
```

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

### Constructor Definition

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/as-entity-autocomplete-field.md

The constructor for the AsEntityAutocompleteField attribute.

```php
public function __construct(
    private ?string $alias = null,
    private string $route = 'ux_entity_autocomplete',
)
```

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

### Configure Tom Select Styles

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/doc/index.rst

Update assets/controllers.json to toggle between default and Bootstrap 5 styles for Tom Select.

```text
"autoimport": {
    "tom-select/dist/css/tom-select.default.css": false,
    "tom-select/dist/css/tom-select.bootstrap5.css": true
}
```

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

### Implement Frontend Data Loading

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/endpoints.md

Uses the TomSelect load callback to fetch results from the autocompleter URL and handle pagination.

```typescript
load: function (query: string, callback: TomLoadCallback) {
    const url = this.getUrl(query);  // includes query parameter
    fetch(url)
        .then((response) => response.json())
        .then((json) => {
            this.setNextUrl(query, json.next_page);
            callback(json.results.options || json.results);
        });
}
```

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

### Constructor Definition

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-metadata-factory.md

The constructor requires a DoctrineRegistryWrapper to access entity managers.

```php
public function __construct(
    private DoctrineRegistryWrapper $doctrine,
)
```

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

### Fetch Autocomplete Results

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-results-executor.md

Executes a query against an autocompleter and returns paginated results.

```php
public function fetchResults(
    EntityAutocompleterInterface $autocompleter,
    string $query,
    int $page
): AutocompleteResults
```

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

### Configure searchable fields

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/types.md

Specifies entity properties to search across. Defaults to searching all fields if null.

```php
'searchable_fields' => ['name', 'email', 'company.name']
```

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

### WrappedEntityTypeAutocompleter Constructor

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/wrapped-entity-type-autocompleter.md

Initializes the autocompleter with necessary form and entity services.

```php
public function __construct(
    private string $formType,
    private FormFactoryInterface $formFactory,
    private EntityMetadataFactory $metadataFactory,
    private PropertyAccessorInterface $propertyAccessor,
    private EntitySearchUtil $entitySearchUtil,
)
```

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

### Validate Extra Options Checksum

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-autocomplete-controller.md

Demonstrates how the controller decodes base64-encoded options and verifies the SHA256 HMAC checksum to prevent tampering.

```php
// Frontend encodes and signs:
$extraOptions = ['category' => '5', 'type' => 'featured'];
$encoded = base64_encode(json_encode($extraOptions));

// Controller verifies:
$decoded = json_decode(base64_decode($encoded), true);
if (!hash_equals($checksum, $calculator->calculateForArray($decoded))) {
    throw new BadRequestHttpException('Tampered with');
}
```

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

### Basic Usage (Auto-Generated Alias)

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/as-entity-autocomplete-field.md

Applying the attribute without arguments to use default settings.

```php
use Symfony\UX\Autocomplete\Form\AsEntityAutocompleteField;
use Symfony\UX\Autocomplete\Form\BaseEntityAutocompleteType;

#[AsEntityAutocompleteField]
class ProductAutocompleteType extends BaseEntityAutocompleteType
{
    // Alias auto-generated: 'product_autocomplete'
    // Route: 'ux_entity_autocomplete' (default)
    // URL will be: /autocomplete/product_autocomplete
}
```

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

### Configure minimum characters

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-choice-type-extension.md

Set the character threshold required to trigger a search.

```php
'min_characters' => 3,    // Require 3+ characters
'min_characters' => null, // Auto-select (default 3, but always loads after first search)
```

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

### Configure Custom AJAX Route

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/doc/index.rst

Define a custom route for autocomplete AJAX calls in YAML and apply it to the entity autocomplete field attribute.

```yaml
# config/routes/attributes.yaml
ux_entity_autocomplete_admin:
    controller: ux.autocomplete.entity_autocomplete_controller
    path: '/admin/autocomplete/{alias}'
```

```php
// src/Form/FoodAutocompleteField.php
#[AsEntityAutocompleteField(route: 'ux_entity_autocomplete_admin')]
class FoodAutocompleteField
{
    // ...
}
```

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

### Implement getGroupBy

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/entity-autocompleter-interface.md

Returns the property path or callable to group results by optgroups.

```php
public function getGroupBy(): mixed
{
    return 'category.name'; // Group by category name
}
```

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

### fetchResults()

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-results-executor.md

Executes an autocomplete query using the provided autocompleter and returns formatted results with pagination.

```APIDOC
## Method: fetchResults()

### Description
Executes an autocomplete query and returns formatted results with pagination information.

### Signature
`public function fetchResults(EntityAutocompleterInterface $autocompleter, string $query, int $page): AutocompleteResults`

### Parameters
- **$autocompleter** (EntityAutocompleterInterface) - Required - The autocompleter implementation.
- **$query** (string) - Required - The search query (can be empty).
- **$page** (int) - Required - The page number (1-indexed).

### Returns
- **AutocompleteResults** - Results with pagination information.

### Throws
- **AccessDeniedException** - If the autocompleter's isGranted() returns false.

### Example
```php
$executor = $container->get('ux.autocomplete.results_executor');
$autocompleter = $registry->getAutocompleter('product');

$results = $executor->fetchResults($autocompleter, 'laptop', 1);
```
```

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

### Implement OptionsAwareEntityAutocompleterInterface

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/doc/index.rst

Extend autocompleter functionality by implementing OptionsAwareEntityAutocompleterInterface to handle custom options.

```php
use Doctrine\ORM\EntityRepository;
use Doctrine\ORM\QueryBuilder;
use Sylius\Component\Product\Model\ProductAttributeInterface;
use Symfony\Bundle\SecurityBundle\Security;
use Symfony\UX\Autocomplete\OptionsAwareEntityAutocompleterInterface;

#[AutoconfigureTag('ux.entity_autocompleter', ['alias' => 'food'])]
class FoodAutocompleter implements OptionsAwareEntityAutocompleterInterface
{
+   /**
+    * @var array<string, mixed>
+    */
+   private array $options = [];

    // ...

+   public function createFilteredQueryBuilder(EntityRepository $repository, string $query): QueryBuilder
+   {
+       $excludedFoods = $this->options['extra_options']['excluded_foods'] ?? [];
+
+       $qb = $repository->createQueryBuilder('o');
+
+       if ($excludedFoods !== []) {
+           $qb
+               ->andWhere($qb->expr()->notIn('o.id', $excludedFoods));
+               ->setParameter('excludedFoods', $excludedFoods)
+           ;
+       }
+
+       return $qb;
+   }

+   /**
+   * @param array<string, mixed> $options
+   */
+   public function setOptions(array $options): void
+   {
+       $this->options = $options;
+   }
```

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

### Set autocomplete URL

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-choice-type-extension.md

Define the endpoint for autocomplete requests.

```php
'autocomplete_url' => '/api/autocomplete/products',
```

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

### Set loading message

Source: https://github.com/symfony/ux-autocomplete/blob/3.x/_autodocs/api-reference/autocomplete-choice-type-extension.md

Customize the text displayed while fetching results.

```php
'loading_more_text' => 'Loading more products...',
```
Tokens:
Raw