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;
}

Sous le capot — la mécanique de resolve()

Un verrou, un clone, et des closures évaluées dans le désordre : la vraie mécanique derrière resolve().

Les sections précédentes t'ont montré l'API : quelles méthodes appeler pour déclarer, valider, normaliser. Cette section montre la machine — ce qui se passe réellement à l'intérieur de resolve() et pourquoi l'ordre de résolution n'est jamais celui que tu déclares, mais celui que tes options s'imposent entre elles.

// Dans OptionsResolver::resolve()
if ($this->locked) {
    throw new AccessException('Options cannot be resolved from a lazy option or normalizer.');
}

$clone = clone $this;   // l'original reste réutilisable
// ... injection des valeurs fournies, contrôle des required ...
$clone->locked = true;    // à partir d'ici, plus aucune mutation

foreach ($clone->defaults as $option => $_) {
    $clone->offsetGet($option);   // résout l'option ET ses dépendances
}

Une fois locked à true, tous les mutateurs (setDefault, setRequired, setNormalizer, setOptions…) lèvent une AccessException. Le but est de garantir qu'une closure lazy ne puisse pas redéfinir le contrat pendant qu'on l'applique — ce qui donnerait des résultats dépendant de l'ordre d'évaluation, donc imprévisibles.

C'est la clé de la résolution paresseuse dirigée par les dépendances. La boucle de resolve() parcourt les options dans leur ordre de déclaration, mais offsetGet() mémoïse chaque résultat dans un tableau resolved : une option n'est calculée qu'une seule fois. Si une lazy option lit $options['host'] avant que la boucle n'atteigne host, alors host est résolu à cet instant et mis en cache. L'ordre réel d'évaluation émerge donc du graphe de dépendances, pas de l'ordre où tu as appelé setDefault().

Ce même graphe est protégé contre les boucles. Avant d'évaluer une closure (lazy, nested ou normalizer), offsetGet() pose un drapeau calling[$option] = true dans un bloc try/finally. Si la résolution ré-entre la même option alors que son drapeau est encore posé, c'est qu'il y a un cycle : OptionDefinitionException, avec la liste exacte des options impliquées.

// LAZY — 1er paramètre typé Options → évaluée à la résolution
$resolver->setDefault('dsn', function (Options $o): string {
    return 'mysql://' . $o['host'];
});

// PAS lazy — pas de type → la Closure est stockée telle quelle
$resolver->setDefault('dsn', function ($o): string {
    return 'mysql://' . $o['host'];   // jamais appelée
});
// $options['dsn'] renvoie ici l'objet Closure, pas la chaîne

Enfin, les options imbriquées suivent la même logique paresseuse. Le sous-resolver n'est pas construit à la déclaration : c'est offsetGet() qui fait new self() au moment où l'option parent est résolue, puis exécute la closure de setOptions() et résout le sous-tableau. Les options enfants n'existent donc que lorsque leur parent est lui-même atteint dans le graphe.

Traceur de résolution

Lance la résolution et observe l'ordre réel des appels à offsetGet() : la mémoïsation, les dépendances qui se résolvent avant leur tour, et la détection de cycle.

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']);
    }
}