From 921c73f7476126ec40eb39d6f957c5f3df3f55cb Mon Sep 17 00:00:00 2001 From: Lorenzo Millucci Date: Sat, 5 Oct 2019 11:05:21 +0200 Subject: [PATCH] [OptionResolver] Document the OptionConfigurator --- components/options_resolver.rst | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/components/options_resolver.rst b/components/options_resolver.rst index 4c2ef3c1254..0870a4148dd 100644 --- a/components/options_resolver.rst +++ b/components/options_resolver.rst @@ -782,6 +782,38 @@ the option:: This closure receives as argument the value of the option after validating it and before normalizing it when the option is being resolved. +Chaining option configurations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In many cases you may need to define multiple configurations for each option. +For example, suppose the ``Mailer`` class has an ``host`` option that is required +and a ``transport`` option which can be one of ``sendmail``, ``mail`` and ``smtp``. +You can improve the readability of the code avoiding to duplicate option name for +each configuration using the method +:method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::define``:: + + // ... + class Mailer + { + // ... + public function configureOptions(OptionsResolver $resolver) + { + // ... + $resolver->define('host') + ->required() + ->default('smtp.example.org') + ->allowedTypes('string'); + $resolver->define('transport') + ->required() + ->default('transport') + ->allowedValues(['sendmail', 'mail', 'smtp']); + } + } + +.. versionadded:: 5.1 + + The ``define()`` method was introduced in Symfony 5.1. + Performance Tweaks ~~~~~~~~~~~~~~~~~~