@@ -50,17 +50,17 @@ The advantages of doing this will become more obvious as you continue::
5050 $this->options = $resolver->resolve($options);
5151 }
5252
53- The options property now is a well defined array with all resolved options readily available::
53+ The options property now is a well defined array with all resolved options
54+ readily available::
5455
5556 // ...
56- public functiongetHost( )
57+ public functionsendMail($from, $to )
5758 {
58- return $this->options['host'];
59- }
60-
61- public function getPassword()
62- {
63- return $this->options['password'];
59+ $mail = ...;
60+ $mail->setHost($this->options['host']);
61+ $mail->setUsername($this->options['username']);
62+ $mail->setPassword($this->options['password']);
63+ // ...
6464 }
6565
6666Configuring the OptionsResolver
@@ -70,6 +70,7 @@ Now, try to actually use the class::
7070
7171 $mailer = new Mailer(array(
7272 'host' => 'smtp.example.org',
73+ 'username' => 'user',
7374 'password' => 'pa$$word',
7475 ));
7576
@@ -86,7 +87,7 @@ knows which options should be resolved.
8687 function.
8788
8889A best practice is to put the configuration in a method (e.g.
89- ``setDefaultOptions ``). You call this method in the constructor to configure
90+ ``configureOptions ``). You call this method in the constructor to configure
9091the ``OptionsResolver `` class::
9192
9293 use Symfony\Component\OptionsResolver\OptionsResolver;
@@ -99,17 +100,38 @@ the ``OptionsResolver`` class::
99100 public function __construct(array $options = array())
100101 {
101102 $resolver = new OptionsResolver();
102- $this->setDefaultOptions ($resolver);
103+ $this->configureOptions ($resolver);
103104
104105 $this->options = $resolver->resolve($options);
105106 }
106107
107- protected functionsetDefaultOptions (OptionsResolverInterface $resolver)
108+ protected functionconfigureOptions (OptionsResolverInterface $resolver)
108109 {
109110 // ... configure the resolver, you will learn this in the sections below
110111 }
111112 }
112113
114+ Set Default Values
115+ ~~~~~~~~~~~~~~~~~~
116+
117+ Most of the options have a default value. You can configure these options by
118+ calling:method: `Symfony\\ Component\\ OptionsResolver\\ OptionsResolver::setDefaults `::
119+
120+ // ...
121+ protected function setDefaultOptions(OptionsResolverInterface $resolver)
122+ {
123+ // ...
124+
125+ $resolver->setDefaults(array(
126+ 'username' => 'root',
127+ ));
128+ }
129+
130+ This would add an option - ``username `` - and give it a default value of
131+ ``root ``. If the user passes in a ``username `` option, that value will
132+ override this default. You don't need to configure ``username `` as an optional
133+ option.
134+
113135Required Options
114136~~~~~~~~~~~~~~~~
115137
@@ -135,15 +157,18 @@ If you don't pass a required option, a
135157:class: `Symfony\\ Component\\ OptionsResolver\\ Exception\\ MissingOptionsException `
136158will be thrown.
137159
138- To determine if an option is required, you can use the
139- :method: `Symfony\\ Component\\ OptionsResolver\\ OptionsResolver::isRequired `
140- method.
160+ ..tip ::
161+
162+ To determine if an option is required, you can use the
163+ :method: `Symfony\\ Component\\ OptionsResolver\\ OptionsResolver::isRequired `
164+ method.
141165
142166Optional Options
143167~~~~~~~~~~~~~~~~
144168
145169Sometimes, an option can be optional (e.g. the ``password `` option in the
146- ``Mailer `` class). You can configure these options by calling
170+ ``Mailer `` class), but it doesn't have a default value. You can configure
171+ these options by calling
147172:method: `Symfony\\ Component\\ OptionsResolver\\ OptionsResolver::setOptional `::
148173
149174 // ...
@@ -154,34 +179,23 @@ Sometimes, an option can be optional (e.g. the ``password`` option in the
154179 $resolver->setOptional(array('password'));
155180 }
156181
157- Set Default Values
158- ~~~~~~~~~~~~~~~~~~
159-
160- Most of the optional options have a default value. You can configure these
161- options by calling
162- :method: `Symfony\\ Component\\ OptionsResolver\\ OptionsResolver::setDefaults `::
182+ Options with defaults are already marked as optional.
163183
164- // ...
165- protected function setDefaultOptions(OptionsResolverInterface $resolver)
166- {
167- // ...
184+ ..tip ::
168185
169- $resolver->setDefaults(array(
170- 'username' => 'root',
171- ));
172- }
186+ When setting an option as optional, you can't be sure if it's in the array
187+ or not. You have to check if the option exists before using it.
173188
174- This would add a third option - ``username `` - and give it a default value
175- of ``root ``. If the user passes in a ``username `` option, that value will
176- override this default. You don't need to configure ``username `` as an optional
177- option. The ``OptionsResolver `` already knows that options with a default
178- value are optional.
189+ To avoid checking if it exists everytime, you can also set a default of
190+ ``null `` to an option using the ``setDefaults() `` method (see `Set Default Values `_),
191+ this means the element always exists in the array, but with a default of
192+ ``null ``.
179193
180- Default Values thatdepend on another Option
194+ Default Values thatDepend on another Option
181195~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
182196
183197Suppose you add a ``port `` option to the ``Mailer `` class, whose default
184- value you guess based on thehost . You can do that easily by using a
198+ value you guess based on theencryption . You can do that easily by using a
185199closure as the default value::
186200
187201 use Symfony\Component\OptionsResolver\Options;
@@ -193,16 +207,21 @@ closure as the default value::
193207 // ...
194208
195209 $resolver->setDefaults(array(
210+ 'encryption' => null,
196211 'port' => function (Options $options) {
197- if (in_array($options['host'], array('127.0.0.1', 'localhost')) ) {
198- return80 ;
212+ if ('ssl' === $options['encryption'] ) {
213+ return465 ;
199214 }
200215
201216 return 25;
202217 },
203218 ));
204219 }
205220
221+ The:class: `Symfony\\ Component\\ OptionsResolver\\ Options ` class implements
222+ :phpclass: `ArrayAccess `,:phpclass: `Iterator ` and:phpclass: `Countable `. That
223+ means you can handle it just like a normal array containing the options.
224+
206225..caution ::
207226
208227 The first argument of the closure must be typehinted as ``Options ``,
@@ -296,16 +315,16 @@ a ``transport`` option, it can only be one of ``sendmail``, ``mail`` or
296315 // ...
297316
298317 $resolver->setAllowedValues(array(
299- 'transport ' => array('sendmail' , 'mail ', 'smtp '),
318+ 'encryption ' => array(null , 'ssl ', 'tls '),
300319 ));
301320 }
302321
303322There is also an
304323:method: `Symfony\\ Component\\ OptionsResolver\\ OptionsResolver::addAllowedValues `
305324method, which you can use if you want to add an allowed value to the previously
306- set allowed values.
325+ configured allowed values.
307326
308- Configureallowed Types
327+ ConfigureAllowed Types
309328~~~~~~~~~~~~~~~~~~~~~~~
310329
311330You can also specify allowed types. For instance, the ``port `` option can