Symfony OptionsResolver

https://github.com/symfony/options-resolver
Admin
Symfony OptionsResolver is a PHP component that provides an improved replacement for array_replace,...
Tokens:10,754
Snippets:36
Trust Score:9.5
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Configure Mailer Service Options with OptionsResolver

Source: https://context7.com/symfony/options-resolver/llms.txt

This example shows a robust implementation of a configuration class using OptionsResolver. It covers defining options, setting defaults, validating types and values, normalizing inputs, and handling nested configuration structures.

```php
use Symfony\Component\OptionsResolver\Options;
use Symfony\Component\OptionsResolver\OptionsResolver;

class MailerConfiguration
{
    private array $config;

    public function __construct(array $options = [])
    {
        $resolver = new OptionsResolver();
        $this->configureOptions($resolver);
        $this->config = $resolver->resolve($options);
    }

    private function configureOptions(OptionsResolver $resolver): void
    {
        $resolver
            ->define('transport')
            ->default('smtp')
            ->allowedTypes('string')
            ->allowedValues('smtp', 'sendmail', 'ses', 'mailgun')
            ->info('Mail transport driver');

        $resolver->setOptions('smtp', function (OptionsResolver $smtp, Options $parent) {
            $smtp->define('host')->default('localhost')->allowedTypes('string');
            $smtp->define('port')->default(function (Options $options) {
                return $options['encryption'] === 'ssl' ? 465 : 587;
            })->allowedTypes('int')->allowedValues(function ($v) { return $v > 0 && $v <= 65535; });
            $smtp->define('encryption')->default('tls')->allowedTypes('string', 'null')->allowedValues('tls', 'ssl', null);
            $smtp->setDefined(['username', 'password']);
            $smtp->setAllowedTypes('username', 'string');
            $smtp->setAllowedTypes('password', 'string');
        });

        $resolver
            ->define('from')
            ->required()
            ->allowedTypes('string', 'array')
            ->normalize(function (Options $options, $value) {
                if (is_string($value)) {
                    return ['address' => $value, 'name' => ''];
                }
                return $value;
            })
            ->info('Default sender email address');

        $resolver->setOptions('retry', function (OptionsResolver $retry) {
            $retry->setDefault('enabled', true);
            $retry->setAllowedTypes('enabled', 'bool');
            $retry->setDefault('max_attempts', 3);
            $retry->setAllowedTypes('max_attempts', 'int');
            $retry->setAllowedValues('max_attempts', function ($v) { return $v >= 1 && $v <= 10; });
            $retry->setDefault('delay', 1000);
            $retry->setAllowedTypes('delay', 'int');
            $retry->setInfo('delay', 'Delay between retries in milliseconds');
        });

        $resolver->setDefault('logging', true);
        $resolver->setAllowedTypes('logging', 'bool');

        $resolver
            ->define('debug')
            ->default(false)
            ->allowedTypes('bool')
            ->deprecated('app/mailer', '2.0', 'Use "logging" option instead of "%name%".');
    }

    public function get(string $key): mixed
    {
        return $this->config[$key] ?? null;
    }

    public function getSmtpDsn(): string
    {
        $smtp = $this->config['smtp'];
        $auth = '';
        if (isset($smtp['username'])) {
            $auth = urlencode($smtp['username']);
            if (isset($smtp['password'])) {
                $auth .= ':' . urlencode($smtp['password']);
            }
            $auth .= '@';
        }
        return sprintf('smtp://%s%s:%d', $auth, $smtp['host'], $smtp['port']);
    }
}

$mailer = new MailerConfiguration([
    'transport' => 'smtp',
    'smtp' => [
        'host' => 'mail.example.com',
        'encryption' => 'ssl',
        'username' => 'user@example.com',
        'password' => 'secret',
    ],
    'from' => 'noreply@example.com',
    'retry' => [
        'max_attempts' => 5,
    ],
]);

echo $mailer->getSmtpDsn();
var_dump($mailer->get('from'));
```

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

### Set and Get Option Information with Symfony OptionsResolver

Source: https://context7.com/symfony/options-resolver/llms.txt

Demonstrates how to attach descriptive information to options using setInfo() and retrieve it using getInfo(). This information is useful for documentation and is included in validation error messages. It covers setting defaults, required options, allowed types, and values.

```php
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\OptionsResolver\Debug\OptionsResolverIntrospector;

$resolver = new OptionsResolver();

// Set info for documentation/error messages
$resolver->setDefault('api_key', null);
$resolver->setRequired('api_key');
$resolver->setAllowedTypes('api_key', 'string');
$resolver->setInfo('api_key', 'Your API authentication key from the dashboard');

$resolver->setDefault('timeout', 30);
$resolver->setAllowedTypes('timeout', 'int');
$resolver->setAllowedValues('timeout', function ($value) {
    return $value > 0 && $value <= 300;
});
$resolver->setInfo('timeout', 'Request timeout in seconds (1-300)');

// Using fluent API
$resolver
    ->define('retry_count')
    ->default(3)
    ->allowedTypes('int')
    ->allowedValues(function ($v) { return $v >= 0 && $v <= 10; })
    ->info('Number of retry attempts (0-10)');

// Retrieve info
echo $resolver->getInfo('api_key');     // 'Your API authentication key from the dashboard'
echo $resolver->getInfo('timeout');     // 'Request timeout in seconds (1-300)'
echo $resolver->getInfo('retry_count'); // 'Number of retry attempts (0-10)'

// Info is included in validation error messages
try {
    $resolver->resolve([
        'api_key' => 'valid-key',
        'retry_count' => 99, // Invalid value
    ]);
} catch (
    Symfony\Component\OptionsResolver\Exception\InvalidOptionsException $e) {
    echo $e->getMessage();
    // 'The option "retry_count" with value 99 is invalid. Info: Number of retry attempts (0-10).'
}

```

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

### Validate Option Values with setAllowedValues() in PHP

Source: https://context7.com/symfony/options-resolver/llms.txt

Demonstrates how to restrict option values to a specific set of allowed values or validation closures using setAllowedValues(). Supports whitelists and custom validation logic via closures. Includes examples of validation errors and successful resolution.

```php
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\OptionsResolver\Exception\InvalidOptionsException;

$resolver = new OptionsResolver();

// Whitelist of allowed values
$resolver->setDefault('transport', 'smtp');
$resolver->setAllowedValues('transport', ['smtp', 'sendmail', 'mail', 'null']);

// Closure validation
$resolver->setDefault('port', 25);
$resolver->setAllowedTypes('port', 'int');
$resolver->setAllowedValues('port', function ($value) {
    return $value > 0 && $value <= 65535;
});

// Multiple validation options (any can match)
$resolver->setDefault('priority', 'normal');
$resolver->setAllowedValues('priority', [
    'low',
    'normal',
    'high',
    function ($value) {
        return is_int($value) && $value >= 1 && $value <= 10;
    },
]);

// Add more allowed values
$resolver->addAllowedValues('transport', 'ses');

// Validation error with whitelist
try {
    $resolver->resolve(['transport' => 'invalid']);
} catch (InvalidOptionsException $e) {
    echo $e->getMessage();
    // 'The option "transport" with value "invalid" is invalid.
    //  Accepted values are: "smtp", "sendmail", "mail", "null", "ses".'
}

// Validation error with closure
try {
    $resolver->resolve(['port' => -1]);
} catch (InvalidOptionsException $e) {
    echo $e->getMessage();
    // 'The option "port" with value -1 is invalid.'
}

// Successful resolution
$resolved = $resolver->resolve([
    'transport' => 'ses',
    'port' => 587,
    'priority' => 5, // matches the closure validator
]);
```

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

### Validate Option Types with setAllowedTypes() in PHP

Source: https://context7.com/symfony/options-resolver/llms.txt

Demonstrates how to restrict option values to specific types using setAllowedTypes(). Supports basic types, class names, array notation, union types, and nullable types. Includes examples of type validation errors and successful resolution.

```php
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\OptionsResolver\Exception\InvalidOptionsException;

$resolver = new OptionsResolver();

// Basic types
$resolver->setDefault('name', 'default');
$resolver->setAllowedTypes('name', 'string');

$resolver->setDefault('count', 0);
$resolver->setAllowedTypes('count', 'int');

// Multiple allowed types
$resolver->setDefault('id', null);
$resolver->setAllowedTypes('id', ['int', 'string', 'null']);

// Union type syntax
$resolver->setDefault('value', 0);
$resolver->setAllowedTypes('value', 'string|int');

// Typed arrays
$resolver->setDefault('tags', []);
$resolver->setAllowedTypes('tags', 'string[]');

// Union types in arrays
$resolver->setDefault('items', []);
$resolver->setAllowedTypes('items', '(string|int)[]');

// Class/interface types
$resolver->setDefault('date', null);
$resolver->setAllowedTypes('date', ['null', \DateTimeInterface::class]);

// Add additional allowed types
$resolver->addAllowedTypes('date', \DateTimeImmutable::class);

// Type validation error
try {
    $resolver->resolve(['name' => 123]);
} catch (InvalidOptionsException $e) {
    echo $e->getMessage();
    // 'The option "name" with value 123 is expected to be of type "string", but is of type "int".'
}

// Successful resolution
$resolved = $resolver->resolve([
    'name' => 'Product',
    'count' => 5,
    'id' => 'abc-123',
    'tags' => ['php', 'symfony'],
    'items' => ['foo', 42, 'bar'],
    'date' => new \DateTime(),
]);
```

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

### Configuring Default and Lazy Options

Source: https://context7.com/symfony/options-resolver/llms.txt

Demonstrates how to set simple default values and use closures for lazy evaluation of options based on other resolved values. This allows for dynamic configuration generation during the resolution process.

```php
use Symfony\Component\OptionsResolver\Options;
use Symfony\Component\OptionsResolver\OptionsResolver;

$resolver = new OptionsResolver();

$resolver->setDefault('host', 'localhost');
$resolver->setDefault('port', 3306);

$resolver->setDefaults([
    'charset' => 'utf8mb4',
    'timeout' => 30,
]);

$resolver->setDefault('dsn', function (Options $options) {
    return sprintf('mysql:host=%s;port=%d;charset=%s',
        $options['host'],
        $options['port'],
        $options['charset']
    );
});

$resolver->setDefault('timeout', function (Options $options, $previousValue) {
    return $previousValue * 2;
});

$resolved = $resolver->resolve(['host' => 'db.example.com']);
```

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

### Configure options with fluent define API

Source: https://context7.com/symfony/options-resolver/llms.txt

Shows how to use the fluent define() method to configure options, including setting defaults, types, allowed values, and deprecation notices in a chainable interface.

```php
use Symfony\Component\OptionsResolver\Options;
use Symfony\Component\OptionsResolver\OptionsResolver;

$resolver = new OptionsResolver();

// Fluent definition of a required option with type and allowed values
$resolver
    ->define('log_level')
    ->required()
    ->allowedTypes('string')
    ->allowedValues('debug', 'info', 'warning', 'error', 'critical')
    ->info('The minimum log level to capture');

// Fluent definition with default, type, and normalizer
$resolver
    ->define('timeout')
    ->default(30)
    ->allowedTypes('int', 'float')
    ->allowedValues(function ($value) {
        return $value > 0;
    })
    ->normalize(function (Options $options, $value) {
        return (int) ceil($value);
    })
    ->info('Connection timeout in seconds');

// Chain multiple option definitions
$resolver
    ->define('host')
    ->default('localhost')
    ->allowedTypes('string')
    ->info('Database host address')

    ->define('port')
    ->default(3306)
    ->allowedTypes('int')
    ->info('Database port number')

    ->define('ssl')
    ->default(false)
    ->allowedTypes('bool')
    ->info('Whether to use SSL connection');

// Deprecated option with custom message
$resolver
    ->define('legacy_mode')
    ->default(false)
    ->allowedTypes('bool')
    ->deprecated('vendor/package', '2.0', 'The "%name%" option is deprecated, use "compatibility_mode" instead.');

$resolved = $resolver->resolve([
    'log_level' => 'warning',
    'timeout' => 45.7,
    'ssl' => true,
]);
```

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

### Setting Default Values

Source: https://context7.com/symfony/options-resolver/llms.txt

Demonstrates how to set default values for options using `setDefault()` and `setDefaults()`, including lazy options.

```APIDOC
## Setting Default Values

### Description
Use `setDefault()` to define default values for options. When a closure with `Options` type-hint is passed, it becomes a lazy option evaluated during resolution. Lazy options can access other resolved options.

### Method
`setDefault()`

### Endpoint
N/A (PHP Component)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```php
use Symfony\Component\OptionsResolver\Options;
use Symfony\Component\OptionsResolver\OptionsResolver;

$resolver = new OptionsResolver();

// Simple default value
$resolver->setDefault('host', 'localhost');
$resolver->setDefault('port', 3306);

// Set multiple defaults at once
$resolver->setDefaults([
    'charset' => 'utf8mb4',
    'timeout' => 30,
]);

// Lazy default value based on other options
$resolver->setDefault('dsn', function (Options $options) {
    return sprintf('mysql:host=%s;port=%d;charset=%s',
        $options['host'],
        $options['port'],
        $options['charset']
    );
});

// Access previous default value in subclass/extension
$resolver->setDefault('timeout', function (Options $options, $previousValue) {
    // $previousValue is 30 from previous setDefault
    return $previousValue * 2; // 60
});

$resolved = $resolver->resolve(['host' => 'db.example.com']);
// Result: ['host' => 'db.example.com', 'port' => 3306, 'charset' => 'utf8mb4',
//          'timeout' => 60, 'dsn' => 'mysql:host=db.example.com;port=3306;charset=utf8mb4']
```

### Response
#### Success Response (200)
N/A (PHP execution result)

#### Response Example
```json
{
  "host": "db.example.com",
  "port": 3306,
  "charset": "utf8mb4",
  "timeout": 60,
  "dsn": "mysql:host=db.example.com;port=3306;charset=utf8mb4"
}
```
```

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

### Defining Optional Configuration Parameters

Source: https://context7.com/symfony/options-resolver/llms.txt

Illustrates how to declare valid option names without assigning default values. These options are accepted during resolution only if explicitly provided by the user.

```php
use Symfony\Component\OptionsResolver\OptionsResolver;

$resolver = new OptionsResolver();

$resolver->setDefined('debug');
$resolver->setDefined(['cache_dir', 'log_level']);

$resolver->setDefault('environment', 'production');

$resolved = $resolver->resolve([
    'debug' => true,
    'cache_dir' => '/tmp/cache',
]);
```

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

### Inspect OptionsResolver configuration with OptionsResolverIntrospector

Source: https://context7.com/symfony/options-resolver/llms.txt

This snippet demonstrates how to instantiate an OptionsResolver, define various options (defaults, types, normalizers, deprecations), and use the OptionsResolverIntrospector to query these configurations. It covers retrieving defaults, lazy closures, allowed types, normalizers, and handling exceptions when configuration is missing.

```php
use Symfony\Component\OptionsResolver\Options;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\OptionsResolver\Debug\OptionsResolverIntrospector;
use Symfony\Component\OptionsResolver\Exception\NoConfigurationException;

$resolver = new OptionsResolver();

$resolver->setDefault('name', 'default_name');
$resolver->setAllowedTypes('name', 'string');
$resolver->setAllowedValues('name', function ($v) { return strlen($v) > 0; });
$resolver->setInfo('name', 'The display name');

$resolver->setDefault('count', function (Options $options) {
    return 10;
});
$resolver->setAllowedTypes('count', 'int');
$resolver->setNormalizer('count', function (Options $options, $value) {
    return max(0, $value);
});

$resolver->setDefault('deprecated_opt', false);
$resolver->setDeprecated('deprecated_opt', 'vendor/pkg', '1.0', 'Option %name% is deprecated.');

$resolver->setOptions('nested', function (OptionsResolver $nested) {
    $nested->setDefault('key', 'value');
});

$introspector = new OptionsResolverIntrospector($resolver);

$default = $introspector->getDefault('name');
echo $default;

$lazies = $introspector->getLazyClosures('count');
var_dump(count($lazies));

$types = $introspector->getAllowedTypes('name');
var_dump($types);

$values = $introspector->getAllowedValues('name');
var_dump(count($values));

$normalizers = $introspector->getNormalizers('count');
var_dump(count($normalizers));

$normalizer = $introspector->getNormalizer('count');
var_dump($normalizer instanceof \Closure);

$deprecation = $introspector->getDeprecation('deprecated_opt');
var_dump($deprecation);

$nested = $introspector->getNestedOptions('nested');
var_dump(count($nested));

try {
    $introspector->getAllowedTypes('deprecated_opt');
} catch (NoConfigurationException $e) {
    echo $e->getMessage();
}
```

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

### MailerConfiguration Class

Source: https://context7.com/symfony/options-resolver/llms.txt

Demonstrates a real-world configuration class using OptionsResolver for a mailer service.

```APIDOC
## MailerConfiguration Class

### Description
This class provides a complete configuration example for a mailer service using Symfony's OptionsResolver. It defines and resolves various mailer options, including transport, SMTP details, sender information, retry settings, and logging.

### Method
N/A (Class Definition)

### Endpoint
N/A (Class Definition)

### Parameters
N/A (Class Definition)

### Request Example
```php
// Usage Example
$mailer = new MailerConfiguration([
    'transport' => 'smtp',
    'smtp' => [
        'host' => 'mail.example.com',
        'encryption' => 'ssl',
        'username' => 'user@example.com',
        'password' => 'secret',
    ],
    'from' => 'noreply@example.com',
    'retry' => [
        'max_attempts' => 5,
    ],
]);

echo $mailer->getSmtpDsn();
// Expected Output: 'smtp://user%40example.com:secret@mail.example.com:465'

var_dump($mailer->get('from'));
// Expected Output: ['address' => 'noreply@example.com', 'name' => '']
```

### Response
N/A (Class Definition)

### Error Handling
N/A (Class Definition)
```

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

### Defining Options Without Defaults

Source: https://context7.com/symfony/options-resolver/llms.txt

Explains how to declare options that are accepted but not required or have no default using `setDefined()`.

```APIDOC
## Defining Options Without Defaults

### Description
Use `setDefined()` to declare valid option names without setting default values. Defined options are accepted but not included in results unless provided.

### Method
`setDefined()`

### Endpoint
N/A (PHP Component)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```php
use Symfony\Component\OptionsResolver\OptionsResolver;

$resolver = new OptionsResolver();

// Define options that can be passed but have no default
$resolver->setDefined('debug');
$resolver->setDefined(['cache_dir', 'log_level']);

// Set some defaults for other options
$resolver->setDefault('environment', 'production');

// Check if option is defined
var_dump($resolver->isDefined('debug'));        // true
var_dump($resolver->isDefined('environment'));  // true
var_dump($resolver->isDefined('undefined'));    // false

// Get all defined options
$resolver->getDefinedOptions(); // ['debug', 'cache_dir', 'log_level', 'environment']

// Resolve without optional options
$resolved = $resolver->resolve([]);
// Result: ['environment' => 'production']

// Resolve with optional options provided
$resolved = $resolver->resolve([
    'debug' => true,
    'cache_dir' => '/tmp/cache',
]);
// Result: ['environment' => 'production', 'debug' => true, 'cache_dir' => '/tmp/cache']
```

### Response
#### Success Response (200)
N/A (PHP execution result)

#### Response Example
```json
{
  "environment": "production",
  "debug": true,
  "cache_dir": "/tmp/cache"
}
```
```

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

### Required Options

Source: https://context7.com/symfony/options-resolver/llms.txt

Explains how to mark options as required using `setRequired()` and handles `MissingOptionsException`.

```APIDOC
## Required Options

### Description
Use `setRequired()` to mark options that must be provided by the user. Required options without defaults will throw `MissingOptionsException` if not supplied.

### Method
`setRequired()`

### Endpoint
N/A (PHP Component)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```php
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\OptionsResolver\Exception\MissingOptionsException;

$resolver = new OptionsResolver();

// Mark single option as required
$resolver->setRequired('api_key');

// Mark multiple options as required
$resolver->setRequired(['username', 'password']);

// Required option with a default (must be defined but has fallback)
$resolver->setRequired('environment');
$resolver->setDefault('environment', 'production');

// Check option status
var_dump($resolver->isRequired('api_key'));    // true
var_dump($resolver->isMissing('api_key'));     // true (no default set)
var_dump($resolver->isMissing('environment')); // false (has default)

// Get all required/missing options
$resolver->getRequiredOptions(); // ['api_key', 'username', 'password', 'environment']
$resolver->getMissingOptions();  // ['api_key', 'username', 'password']

// This throws MissingOptionsException
try {
    $resolver->resolve([]);
} catch (MissingOptionsException $e) {
    echo $e->getMessage(); // 'The required options "api_key", "password", "username" are missing.'
}

// Successful resolution
$resolved = $resolver->resolve([
    'api_key' => 'secret123',
    'username' => 'admin',
    'password' => 'pass123',
]);
```

### Response
#### Success Response (200)
N/A (PHP execution result)

#### Response Example
```json
{
  "api_key": "secret123",
  "username": "admin",
  "password": "pass123",
  "environment": "production"
}
```
```

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

### Managing Required Options

Source: https://context7.com/symfony/options-resolver/llms.txt

Shows how to enforce mandatory options and handle missing values. It covers marking options as required and catching exceptions when essential data is absent.

```php
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\OptionsResolver\Exception\MissingOptionsException;

$resolver = new OptionsResolver();

$resolver->setRequired('api_key');
$resolver->setRequired(['username', 'password']);

$resolver->setRequired('environment');
$resolver->setDefault('environment', 'production');

try {
    $resolver->resolve([]);
} catch (MissingOptionsException $e) {
    echo $e->getMessage();
}

$resolved = $resolver->resolve([
    'api_key' => 'secret123',
    'username' => 'admin',
    'password' => 'pass123',
]);
```

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

### Ignoring Undefined Options

Source: https://context7.com/symfony/options-resolver/llms.txt

Explains how to use `setIgnoreUndefined(true)` to prevent `UndefinedOptionsException` when unknown options are provided to the resolver. These options will be silently ignored.

```APIDOC
## Ignoring Undefined Options

Use `setIgnoreUndefined()` to silently ignore unknown options instead of throwing exceptions.

### Method
Not applicable (This is a configuration example, not an API endpoint).

### Endpoint
Not applicable.

### Parameters
Not applicable.

### Request Example
```php
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\OptionsResolver\Exception\UndefinedOptionsException;

$resolver = new OptionsResolver();

$resolver->setDefault('known_option', 'value');
$resolver->setDefault('another_option', true);

// By default, undefined options throw an exception
try {
    $resolver->resolve([
        'known_option' => 'custom',
        'undefined_option' => 'ignored',
    ]);
} catch (UndefinedOptionsException $e) {
    echo $e->getMessage();
    // 'The option "undefined_option" does not exist. Defined options are: "another_option", "known_option".'
}

// Enable ignoring undefined options
$resolver->setIgnoreUndefined(true);

// Now undefined options are silently ignored
$resolved = $resolver->resolve([
    'known_option' => 'custom',
    'undefined_option' => 'this will be ignored',
    'extra_data' => ['also', 'ignored'],
]);
// Result: ['known_option' => 'custom', 'another_option' => true]

// Useful when extending configurations
class ExtendedConfig {
    public function configure(OptionsResolver $resolver): void {
        $resolver->setIgnoreUndefined(true); // Allow subclasses to add options
        $resolver->setDefault('base_option', 'value');
    }
}

// Using fluent API
$resolver = new OptionsResolver();
$resolver
    ->define('option')
    ->default('value')
    ->ignoreUndefined(); // Enable for entire resolver

$resolved = $resolver->resolve(['option' => 'test', 'unknown' => 'ignored']);
// Result: ['option' => 'test']
```

### Response
Not applicable.

### Response Example
Not applicable.
```

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

### Normalize option values with setNormalizer

Source: https://context7.com/symfony/options-resolver/llms.txt

Demonstrates how to transform, sanitize, or compute derived option values using setNormalizer and addNormalizer. Normalizers are executed after validation and can access other options via the Options object.

```php
use Symfony\Component\OptionsResolver\Options;
use Symfony\Component\OptionsResolver\OptionsResolver;

$resolver = new OptionsResolver();

// Normalize string to lowercase
$resolver->setDefault('format', 'json');
$resolver->setAllowedTypes('format', 'string');
$resolver->setNormalizer('format', function (Options $options, $value) {
    return strtolower(trim($value));
});

// Convert to specific type
$resolver->setDefault('date', null);
$resolver->setAllowedTypes('date', ['null', 'string', \DateTimeInterface::class]);
$resolver->setNormalizer('date', function (Options $options, $value) {
    if (is_string($value)) {
        return new \DateTimeImmutable($value);
    }
    return $value;
});

// Normalizer with access to other options
$resolver->setDefault('filename', null);
$resolver->setDefault('extension', 'txt');
$resolver->setNormalizer('filename', function (Options $options, $value) {
    if ($value && !pathinfo($value, PATHINFO_EXTENSION)) {
        return $value . '.' . $options['extension'];
    }
    return $value;
});

// Add multiple normalizers (executed in order)
$resolver->addNormalizer('format', function (Options $options, $value) {
    return $value === 'yml' ? 'yaml' : $value;
});

// Prepend a normalizer (executed first)
$resolver->addNormalizer('format', function (Options $options, $value) {
    return str_replace('-', '_', $value);
}, forcePrepend: true);

$resolved = $resolver->resolve([
    'format' => '  JSON-LD  ',
    'date' => '2024-01-15',
    'filename' => 'report',
]);
```

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

### Deprecating Options with Symfony OptionsResolver

Source: https://context7.com/symfony/options-resolver/llms.txt

Demonstrates how to use the `setDeprecated()` method in Symfony's OptionsResolver to mark options as deprecated. This includes simple deprecations, custom messages, conditional deprecations based on values or other options, and using the fluent API. It also shows how to check if an option is deprecated.

```php
use Symfony\Component\OptionsResolver\Options;
use Symfony\Component\OptionsResolver\OptionsResolver;

$resolver = new OptionsResolver();

// Simple deprecation with default message
$resolver->setDefault('legacy_option', false);
$resolver->setAllowedTypes('legacy_option', 'bool');
$resolver->setDeprecated('legacy_option', 'vendor/package', '2.0');
// Triggers: "Since vendor/package 2.0: The option "legacy_option" is deprecated."

// Custom deprecation message
$resolver->setDefault('old_name', null);
$resolver->setDeprecated(
    'old_name',
    'vendor/package',
    '2.1',
    'The option "%name%" is deprecated, use "new_name" instead.'
);

// Conditional deprecation based on value
$resolver->setDefault('format', 'json');
$resolver->setAllowedTypes('format', 'string');
$resolver->setAllowedValues('format', ['json', 'xml', 'yaml', 'csv']);
$resolver->setDeprecated('format', 'vendor/package', '3.0', function (Options $options, $value) {
    if ($value === 'xml') {
        return 'The XML format is deprecated, use JSON instead.';
    }
    if ($value === 'csv') {
        return 'The CSV format is deprecated and will be removed in 4.0.';
    }
    return ''; // Empty string = no deprecation triggered
});

// Deprecation based on other options
$resolver->setDefault('use_cache', true);
$resolver->setDefault('cache_ttl', 3600);
$resolver->setDeprecated('cache_ttl', 'vendor/package', '2.5', function (Options $options, $value) {
    if (!$options['use_cache']) {
        return 'Setting "cache_ttl" has no effect when "use_cache" is false.';
    }
    return '';
});

// Using fluent API
$resolver
    ->define('deprecated_feature')
    ->default(false)
    ->allowedTypes('bool')
    ->deprecated('vendor/package', '2.0', 'The "%name%" option is deprecated.');

// Check if option is deprecated
var_dump($resolver->isDeprecated('legacy_option')); // true
var_dump($resolver->isDeprecated('format'));        // true

$resolved = $resolver->resolve([
    'legacy_option' => true,  // Triggers deprecation notice
    'format' => 'xml',        // Triggers: "The XML format is deprecated..."
]);

```

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

### Define Prototype Arrays with OptionsResolver in PHP

Source: https://context7.com/symfony/options-resolver/llms.txt

This snippet demonstrates how to use `setPrototype(true)` within nested options to define structures for arrays of identically structured items. This is useful for configurations like connection pools or server lists where multiple entries share the same format. It allows defining required fields, default values, allowed types, and custom validation rules for each item in the array.

```php
use Symfony\Component\OptionsResolver\Options;\nuse Symfony\Component\OptionsResolver\OptionsResolver;\n\n$resolver = new OptionsResolver();\n\n// Define prototype for connection pool\n$resolver->setOptions('connections', function (OptionsResolver $nested) {\n    // Mark as prototype - each array element follows this structure\n    $nested->setPrototype(true);\n\n    $nested->setRequired('name');\n    $nested->setAllowedTypes('name', 'string');\n\n    $nested->setRequired('dsn');\n    $nested->setAllowedTypes('dsn', 'string');\n\n    $nested->setDefault('timeout', 30);\n    $nested->setAllowedTypes('timeout', 'int');\n\n    $nested->setDefault('persistent', false);\n    $nested->setAllowedTypes('persistent', 'bool');\n});\n\n// Define servers as prototype array\n$resolver->setOptions('servers', function (OptionsResolver $nested) {\n    $nested->setPrototype(true);\n\n    $nested\n        ->define('host')\n        ->required()\n        ->allowedTypes('string');\n\n    $nested\n        ->define('port')\n        ->default(80)\n        ->allowedTypes('int');\n\n    $nested\n        ->define('weight')\n        ->default(1)\n        ->allowedTypes('int')\n        ->allowedValues(function ($v) { return $v >= 1 && $v <= 100; });\n});\n\n$resolved = $resolver->resolve([\n    'connections' => [\n        'primary' => [\n            'name' => 'Primary DB',\n            'dsn' => 'mysql:host=db1.example.com;dbname=app',\n            'timeout' => 60,\n        ],\n        'replica' => [\n            'name' => 'Read Replica',\n            'dsn' => 'mysql:host=db2.example.com;dbname=app',\n            'persistent' => true,\n        ],\n    ],\n    'servers' => [\n        ['host' => 'server1.example.com', 'port' => 8080, 'weight' => 10],\n        ['host' => 'server2.example.com', 'weight' => 5],\n        ['host' => 'server3.example.com', 'port' => 9000],\n    ],\n]);\n// Result: [\n//   'connections' => [\n//     'primary' => ['name' => 'Primary DB', 'dsn' => '...', 'timeout' => 60, 'persistent' => false],\n//     'replica' => ['name' => 'Read Replica', 'dsn' => '...', 'timeout' => 30, 'persistent' => true],\n//   ],\n//   'servers' => [\n//     ['host' => 'server1.example.com', 'port' => 8080, 'weight' => 10],\n//     ['host' => 'server2.example.com', 'port' => 80, 'weight' => 5],\n//     ['host' => 'server3.example.com', 'port' => 9000, 'weight' => 1],\n//   ]\n// ]
```

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

### Deprecating Options

Source: https://context7.com/symfony/options-resolver/llms.txt

Demonstrates how to mark options as deprecated using `setDeprecated()`. This triggers E_USER_DEPRECATED when the option is used, with options for custom messages and conditional deprecation.

```APIDOC
## Deprecating Options

Use `setDeprecated()` to mark options as deprecated. Triggers E_USER_DEPRECATED when the option is used.

### Method
Not applicable (This is a configuration example, not an API endpoint).

### Endpoint
Not applicable.

### Parameters
Not applicable.

### Request Example
```php
use Symfony\Component\OptionsResolver\OptionsResolver;

$resolver = new OptionsResolver();

// Simple deprecation with default message
$resolver->setDefault('legacy_option', false);
$resolver->setAllowedTypes('legacy_option', 'bool');
$resolver->setDeprecated('legacy_option', 'vendor/package', '2.0');
// Triggers: "Since vendor/package 2.0: The option \"legacy_option\" is deprecated."

// Custom deprecation message
$resolver->setDefault('old_name', null);
$resolver->setDeprecated(
    'old_name',
    'vendor/package',
    '2.1',
    'The option "%name%" is deprecated, use "new_name" instead.'
);

// Conditional deprecation based on value
$resolver->setDefault('format', 'json');
$resolver->setAllowedTypes('format', 'string');
$resolver->setAllowedValues('format', ['json', 'xml', 'yaml', 'csv']);
$resolver->setDeprecated('format', 'vendor/package', '3.0', function (Options $options, $value) {
    if ($value === 'xml') {
        return 'The XML format is deprecated, use JSON instead.';
    }
    if ($value === 'csv') {
        return 'The CSV format is deprecated and will be removed in 4.0.';
    }
    return ''; // Empty string = no deprecation triggered
});

// Deprecation based on other options
$resolver->setDefault('use_cache', true);
$resolver->setDefault('cache_ttl', 3600);
$resolver->setDeprecated('cache_ttl', 'vendor/package', '2.5', function (Options $options, $value) {
    if (!$options['use_cache']) {
        return 'Setting "cache_ttl" has no effect when "use_cache" is false.';
    }
    return '';
});

// Using fluent API
$resolver
    ->define('deprecated_feature')
    ->default(false)
    ->allowedTypes('bool')
    ->deprecated('vendor/package', '2.0', 'The "%name%" option is deprecated.');

// Check if option is deprecated
var_dump($resolver->isDeprecated('legacy_option')); // true
var_dump($resolver->isDeprecated('format'));        // true

$resolved = $resolver->resolve([
    'legacy_option' => true,  // Triggers deprecation notice
    'format' => 'xml',        // Triggers: "The XML format is deprecated..."
]);
```

### Response
Not applicable.

### Response Example
Not applicable.
```

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

### Define Nested Options with OptionsResolver in PHP

Source: https://context7.com/symfony/options-resolver/llms.txt

This snippet shows how to define complex, nested option structures using Symfony's OptionsResolver. It allows for default values, allowed types, required fields, and even dynamic default values based on other options. The `setOptions` method is used to create nested configurations for 'database' and 'cache', and the fluent API is used for 'logging'.

```php
use Symfony\Component\OptionsResolver\Options;\nuse Symfony\Component\OptionsResolver\OptionsResolver;\n\n$resolver = new OptionsResolver();\n\n// Define nested options for database configuration\n$resolver->setOptions('database', function (OptionsResolver $nested, Options $parent) {\n    $nested->setDefault('driver', 'mysql');\n    $nested->setAllowedValues('driver', ['mysql', 'pgsql', 'sqlite']);\n\n    $nested->setRequired('name');\n    $nested->setAllowedTypes('name', 'string');\n\n    $nested->setDefault('host', 'localhost');\n    $nested->setDefault('port', function (Options $options) {\n        return $options['driver'] === 'pgsql' ? 5432 : 3306;\n    });\n\n    $nested->setDefined(['username', 'password']);\n    $nested->setAllowedTypes('username', 'string');\n    $nested->setAllowedTypes('password', 'string');\n});\n\n// Define nested options for cache\n$resolver->setOptions('cache', function (OptionsResolver $nested) {\n    $nested->setDefault('enabled', true);\n    $nested->setAllowedTypes('enabled', 'bool');\n\n    $nested->setDefault('ttl', 3600);\n    $nested->setAllowedTypes('ttl', 'int');\n\n    $nested->setDefault('driver', 'file');\n    $nested->setAllowedValues('driver', ['file', 'redis', 'memcached']);\n});\n\n// Using fluent API for nested options\n$resolver\n    ->define('logging')\n    ->options(function (OptionsResolver $nested) {\n        $nested\n            ->define('enabled')\n            ->default(true)\n            ->allowedTypes('bool');\n\n        $nested\n            ->define('path')\n            ->default('/var/log/app.log')\n            ->allowedTypes('string');\n    });\n\n$resolved = $resolver->resolve([\n    'database' => [\n        'name' => 'myapp',\n        'username' => 'admin',\n        'password' => 'secret',\n    ],\n    'cache' => [\n        'driver' => 'redis',\n        'ttl' => 7200,\n    ],\n]);\n// Result: [\n//   'database' => ['driver' => 'mysql', 'name' => 'myapp', 'host' => 'localhost',\n//                  'port' => 3306, 'username' => 'admin', 'password' => 'secret'],\n//   'cache' => ['enabled' => true, 'ttl' => 7200, 'driver' => 'redis'],\n//   'logging' => ['enabled' => true, 'path' => '/var/log/app.log']\n// ]
```

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

### Remove and Clear Options with Symfony OptionsResolver

Source: https://context7.com/symfony/options-resolver/llms.txt

Illustrates how to manage options within the OptionsResolver by removing individual or multiple options using remove(), and resetting the entire resolver configuration with clear(). This is useful for dynamically adjusting the expected options.

```php
use Symfony\Component\OptionsResolver\OptionsResolver;

$resolver = new OptionsResolver();

// Setup initial options
$resolver->setDefaults([
    'option_a' => 'value_a',
    'option_b' => 'value_b',
    'option_c' => 'value_c',
]);
$resolver->setRequired('option_d');
$resolver->setAllowedTypes('option_a', 'string');
$resolver->setAllowedValues('option_b', ['value_b', 'other']);

// Remove single option (removes all configuration for that option)
$resolver->remove('option_a');

var_dump($resolver->isDefined('option_a'));  // false
var_dump($resolver->hasDefault('option_a')); // false

// Remove multiple options
$resolver->remove(['option_b', 'option_d']);

var_dump($resolver->isDefined('option_b'));  // false
var_dump($resolver->isRequired('option_d')); // false

// Only option_c remains
$resolved = $resolver->resolve([]);
// Result: ['option_c' => 'value_c']

// Clear all options
$resolver->setDefaults(['x' => 1, 'y' => 2, 'z' => 3]);
$resolver->clear();

var_dump($resolver->getDefinedOptions()); // []
var_dump($resolver->hasDefault('x'));     // false

$resolved = $resolver->resolve([]);
// Result: []

```

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

### Ignoring Undefined Options with Symfony OptionsResolver

Source: https://context7.com/symfony/options-resolver/llms.txt

Illustrates how to use `setIgnoreUndefined(true)` in Symfony's OptionsResolver to prevent exceptions when undefined options are provided. This is useful for extending configurations or when dealing with optional parameters. The fluent API method `ignoreUndefined()` is also shown.

```php
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\OptionsResolver\Exception\UndefinedOptionsException;

$resolver = new OptionsResolver();

$resolver->setDefault('known_option', 'value');
$resolver->setDefault('another_option', true);

// By default, undefined options throw an exception
try {
    $resolver->resolve([
        'known_option' => 'custom',
        'undefined_option' => 'ignored',
    ]);
} catch (UndefinedOptionsException $e) {
    echo $e->getMessage();
    // 'The option "undefined_option" does not exist. Defined options are: "another_option", "known_option".'
}

// Enable ignoring undefined options
$resolver->setIgnoreUndefined(true);

// Now undefined options are silently ignored
$resolved = $resolver->resolve([
    'known_option' => 'custom',
    'undefined_option' => 'this will be ignored',
    'extra_data' => ['also', 'ignored'],
]);
// Result: ['known_option' => 'custom', 'another_option' => true]

// Useful when extending configurations
class ExtendedConfig {
    public function configure(OptionsResolver $resolver): void {
        $resolver->setIgnoreUndefined(true); // Allow subclasses to add options
        $resolver->setDefault('base_option', 'value');
    }
}

// Using fluent API
$resolver = new OptionsResolver();
$resolver
    ->define('option')
    ->default('value')
    ->ignoreUndefined(); // Enable for entire resolver

$resolved = $resolver->resolve(['option' => 'test', 'unknown' => 'ignored']);
// Result: ['option' => 'test']

```
Tokens:
Raw