OptionsResolver — le contrat d'entrée de ta classe

Valider, normaliser et documenter les options d'une classe en un seul endroit — c'est le rôle d'OptionsResolver.

Imagine une classe Mailer qui accepte un tableau d'options : host, port, timeout, encryption… Sans outillage, tu te retrouves à écrire à la main une dizaine de lignes if (!isset($options['host'])) throw …, puis des vérifications de type, puis des valeurs par défaut — du code répétitif, fragile et sans documentation.

Le pattern consiste à déclarer les options dans une méthode configureOptions() (ou similaire), puis à appeler resolve() dans le constructeur ou dans une factory. Le composant est utilisé en interne par tous les composants Symfony qui acceptent des options : Form, HttpClient, Messenger, etc.

Les avantages clés par rapport à une validation manuelle :

Définir et résoudre — les fondations

setDefault, setRequired, setDefined — définir les options. resolve() — les valider toutes d'un coup.

Tout commence par un objet OptionsResolver dans lequel tu déclares tes options avant d'appeler resolve(). Pense-y comme à un contrat signé avant que des données n'entrent dans ta classe.

use Symfony\Component\OptionsResolver\OptionsResolver;

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

    private function configureOptions(OptionsResolver $resolver): void
    {
        // Obligatoire — MissingOptionsException si absent
        $resolver->setRequired('host');

        // Facultatif avec valeur par défaut
        $resolver->setDefault('port', 80);
        $resolver->setDefault('timeout', 30);

        // Défini mais sans valeur — acceptable si fourni, pas obligatoire
        $resolver->setDefined(['proxy', 'auth_bearer']);
    }
}

// Utilisation
new HttpClient(['host' => 'api.example.com', 'port' => 443]);

// MissingOptionsException — 'host' est required
new HttpClient(['port' => 443]);

// UndefinedOptionsException — 'verify_ssl' n'est pas déclaré
new HttpClient(['host' => 'api.example.com', 'verify_ssl' => true]);

setDefaults() est un raccourci pour définir plusieurs options par défaut en une seule fois — exactement comme appeler setDefault() en boucle.

$resolver->setDefaults([
    'port'    => 80,
    'timeout' => 30,
    'retries' => 3,
]);

La méthode setIgnoreUndefined(true) permet d'assouplir le contrat : les options inconnues sont silencieusement ignorées plutôt que de lever une exception. À utiliser avec parcimonie — en général pour des sous-composants qui acceptent un tableau d'options plus large que ce qu'ils consomment.

Validation — types et valeurs autorisées

setAllowedTypes filtre par type PHP ou FQCN. setAllowedValues accepte des valeurs statiques ou une closure.

Une option définie mais sans contrainte accepte n'importe quelle valeur — ce qui n'est souvent pas ce que tu veux. setAllowedTypes() et setAllowedValues() verrouillent le contrat.

$resolver
    // Types : string ou null (option nullable)
    ->setAllowedTypes('host', ['string', 'null'])

    // Type entier uniquement
    ->setAllowedTypes('port', 'int')

    // Valeur dans une liste finie
    ->setAllowedValues('encryption', ['tls', 'ssl', null])

    // Validation custom : port dans la plage TCP valide
    ->setAllowedValues('port', function(int $port): bool {
        return $port >= 1 && $port <= 65535;
    })

    // Tableau de strings : FQCN[]
    ->setAllowedTypes('middlewares', 'string[]')

    // Instance d'une interface
    ->setAllowedTypes('logger', ['null', \Psr\Log\LoggerInterface::class]);

L'ordre de validation est fixe : les types sont vérifiés avant les valeurs. Si port reçoit "abc" (string), la validation de type échoue avant même d'atteindre la closure de plage. Cela signifie que dans ta closure setAllowedValues, tu peux supposer que le type est correct.

// FQCN — accepte une instance ou null
$resolver->setDefault('transport', null);
$resolver->setAllowedTypes('transport', ['null', TransportInterface::class]);

// Enum PHP natif : passe directement l'instance
$resolver->setAllowedValues('level', LogLevel::cases());

Normalizers — transformer les valeurs après validation

Les normalizers s'exécutent après la validation — ils transforment sans valider. setNormalizer remplace, addNormalizer enchaîne.

La validation décide si une valeur est acceptable. La normalisation décide de sa forme définitive. Les deux étapes sont séparées : les normalizers s'exécutent après la validation des types et des valeurs.

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

// Premier normalizer : trim des espaces
$resolver->setNormalizer('host', function(\Symfony\Options $options, string $value): string {
    return trim($value);
});

// Deuxième normalizer (enchaîné) : lowercase
$resolver->addNormalizer('host', function(\Symfony\Options $options, string $value): string {
    return strtolower($value);
});

// ' MyHost ' → 'myhost'
$resolved = $resolver->resolve(['host' => '  MyHost  ']);

Le paramètre Options $options donne accès à d'autres options déjà résolues — pratique pour construire une valeur composite.

// Normalizer qui lit une autre option
$resolver->addNormalizer('base_url', function(\Symfony\Options $options, string $value): string {
    if ($options['port'] !== 80) {
        return $value . ':' . $options['port'];
    }
    return $value;
});

Lazy options — valeurs calculées à la demande

Une closure dans setDefault n'est évaluée qu'à la résolution — elle peut lire d'autres options déjà résolues.

Imagine que ta valeur par défaut n'est pas une constante, mais dépend d'une autre option — ou d'un calcul coûteux que tu ne veux exécuter que si l'option n'est pas fournie. C'est exactement le rôle des lazy options.

use Symfony\Component\OptionsResolver\Options;

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

// dsn est calculé à partir de host et port déjà résolus
$resolver->setDefault('dsn', function(Options $options): string {
    return 'mysql://' . $options['host'] . ':' . $options['port'];
});

// Si port n'est pas fourni, dsn utilise 3306
// Si port est fourni (ex. 5432), dsn le reflète automatiquement

La signature longue — avec un second paramètre $previousValue — permet de chaîner avec la valeur fournie par l'appelant : la closure reçoit la valeur passée dans resolve() et peut la modifier ou la remplacer.

// Signature longue : accès à la valeur fournie par l'appelant
$resolver->setDefault('tags', function(Options $options, ?array $previous): array {
    $base = ['app'];
    return array_merge($base, $previous ?? []);
});

// Sans fournir 'tags' → ['app']
// Avec ['tags' => ['feature']] → ['app', 'feature']

Les lazy options peuvent accéder à d'autres lazy options — le resolver gère automatiquement l'ordre d'évaluation en construisant le graphe de dépendances. En revanche, modifier le resolver depuis l'intérieur d'une lazy closure est interdit et lève AccessException.

Options imbriquées et prototypes

setOptions() crée un sous-resolver pour une option tableau. setPrototype(true) applique le même schéma à chaque élément d'un array.

Pour des options qui sont elles-mêmes des tableaux structurés — configuration d'une connexion, d'un transport, d'un serveur — setOptions() crée un sous-resolver dédié plutôt que d'imbriquer des if/isset en cascade.

$resolver->setOptions('database', function(OptionsResolver $sub, Options $parent): void {
    $sub->setDefault('host', 'localhost');
    $sub->setRequired('name');
    $sub->setDefault('port', function(Options $subOpts): int {
        // Accède au parent pour choisir le port par défaut
        return $parent['env'] === 'test' ? 5432 : 3306;
    });
    $sub->setAllowedTypes('port', 'int');
});

// Utilisation
$resolver->resolve([
    'env'      => 'prod',
    'database' => ['name' => 'my_db', 'host' => 'db.example.com'],
]);

$resolver->setOptions('servers', function(OptionsResolver $sub): void {
    $sub->setPrototype(true);   // active le mode prototype
    $sub->setRequired('hostname');
    $sub->setDefault('port', 80);
    $sub->setAllowedTypes('port', 'int');
});

// Chaque élément est résolu séparément
$resolver->resolve([
    'servers' => [
        ['hostname' => 'web1.example.com'],
        ['hostname' => 'web2.example.com', 'port' => 8080],
    ],
]);

Déprecation et documentation des options

setDeprecated() émet un warning à l'utilisation. setInfo() documente l'option dans les messages d'erreur.

Au fil du temps, certaines options deviennent obsolètes ou changent de nom. setDeprecated() émet un E_USER_DEPRECATED dès que l'option est utilisée — sans casser le code existant. setInfo() ajoute une phrase d'explication dans les messages d'erreur.

// Déprecation simple — message statique
$resolver->setDeprecated(
    'timeout',
    'acme/http-client',
    '2.0',
    'L\'option "timeout" est dépréciée depuis 2.0, utilise "connect_timeout" et "read_timeout".'
);

// Déprecation conditionnelle — closure
// Retourner '' désactive la déprecation pour cette valeur
$resolver->setDeprecated(
    'encryption',
    'acme/mailer',
    '3.0',
    function(Options $options, mixed $value): string {
        if ($value === 'ssl') {
            return 'La valeur "ssl" est obsolète, utilise "tls".';
        }
        return ''; // pas de warning pour les autres valeurs
    }
);

$resolver->setInfo('log_level', 'Niveau PSR-3. Valeurs : debug, info, notice, warning, error, critical, alert, emergency.');

// Si log_level reçoit 'verbose', l'exception inclura :
// Hint: Niveau PSR-3. Valeurs : debug, info, notice, …

isDeprecated(string $option) permet de vérifier depuis l'extérieur si une option est marquée comme dépréciée — utile dans les outils de debug ou les tests qui veulent s'assurer qu'aucune option dépréciée n'est utilisée.

// Ancienne option 'timeout' renommée en 'connect_timeout'
$resolver->setDefined('timeout');
$resolver->setDefault('connect_timeout', 30);
$resolver->setDeprecated('timeout', 'acme/http', '2.0', 'Utilise "connect_timeout".');

// Recopie automatique dans la nouvelle option
$resolver->setNormalizer('connect_timeout', function(Options $options, int $value): int {
    if (isset($options['timeout'])) {
        return $options['timeout'];
    }
    return $value;
});

define() — l'interface fluente

define() retourne un OptionConfigurator qui chaîne toutes les méthodes de configuration en une seule expression.

Toutes les méthodes vues jusqu'ici (setDefault(), setAllowedTypes(), setAllowedValues(), setNormalizer(), setDeprecated(), setInfo()) peuvent être remplacées par une interface fluente via define().

// Style classique
$resolver->setRequired('host');
$resolver->setAllowedTypes('host', 'string');
$resolver->setInfo('host', 'Nom d\'hôte ou IP du serveur cible.');

// Style fluent — équivalent exact
$resolver->define('host')
    ->required()
    ->allowedTypes('string')
    ->info('Nom d\'hôte ou IP du serveur cible.');

L'interface fluente est particulièrement lisible pour les options avec plusieurs contraintes. Voici un exemple complet de configureOptions() utilisant uniquement define() :

private function configureOptions(OptionsResolver $resolver): void
{
    $resolver->define('host')
        ->required()
        ->allowedTypes('string')
        ->normalize(fn(Options $o, string $v) => strtolower(trim($v)))
        ->info('Adresse DNS ou IP du serveur.');

    $resolver->define('port')
        ->default(80)
        ->allowedTypes('int')
        ->allowedValues(fn(int $p) => $p >= 1 && $p <= 65535)
        ->info('Port TCP (1-65535).');

    $resolver->define('encryption')
        ->default(null)
        ->allowedValues([null, 'tls', 'ssl'])
        ->deprecated('ssl', 'acme/mailer', '3.0', 'Utilise "tls".')
        ->info('Protocole de chiffrement. null = pas de chiffrement.');
}

Exceptions — comprendre chaque erreur

Six exceptions, six situations — comprendre laquelle arrive quand permet de diagnostiquer instantanément.

OptionsResolver lève six types d'exceptions. Chacune correspond à une situation précise — les identifier instantanément évite de fouiller dans la stack trace.

use Symfony\Component\OptionsResolver\Exception\ExceptionInterface;
use Symfony\Component\OptionsResolver\Exception\MissingOptionsException;
use Symfony\Component\OptionsResolver\Exception\InvalidOptionsException;

try {
    $resolved = $resolver->resolve($options);
} catch (MissingOptionsException $e) {
    // Champ obligatoire absent — feedback utilisateur
    throw new \InvalidArgumentException('Configuration incomplète : ' . $e->getMessage());
} catch (InvalidOptionsException $e) {
    // Valeur incorrecte — logguer et remonter
    $this->logger->error('Options invalides', ['error' => $e->getMessage()]);
    throw $e;
} catch (ExceptionInterface $e) {
    // Toutes les autres erreurs OptionsResolver
    throw $e;
}

Synthèse — guide de construction d'un resolver

Ordre de construction, guide de choix entre setNormalizer/setAllowedValues/lazy — tout en un tableau.

Voici un récapitulatif de tout ce que tu peux faire avec OptionsResolver, présenté dans l'ordre logique de construction d'un resolver robuste.

Un pattern courant dans les composants Symfony est d'utiliser configureOptions() comme seul point de configuration, et de l'appeler dans le constructeur. Les sous-classes peuvent appeler parent::configureOptions($resolver) puis ajouter leurs propres options avec addAllowedTypes() ou addNormalizer() sans remplacer ce qu'a fait le parent.

class BaseTransport
{
    protected function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->define('timeout')->default(30)->allowedTypes('int');
    }
}

class SslTransport extends BaseTransport
{
    protected function configureOptions(OptionsResolver $resolver): void
    {
        parent::configureOptions($resolver);
        $resolver->define('verify_peer')->default(true)->allowedTypes('bool');
        $resolver->define('ca_file')->default(null)->allowedTypes(['null', 'string']);
    }
}