Merge branch '2.1' into 2.2

weaverryan · weaverryan · commit 421576363953 · 2013-06-30T13:22:56.000-05:00
diff --git a/components/options_resolver.rst b/components/options_resolver.rst
@@ -19,13 +19,13 @@ You can install the component in 2 different ways:
 Usage
 -----
 
-Imagine you have a ``Person`` class which has 2 options: ``firstName`` and
-``lastName``. These options are going to be handled by the OptionsResolver
+Imagine you have a ``Mailer`` class which has 2 options: ``host`` and
+``password``. These options are going to be handled by the OptionsResolver
 Component.
 
-First, create the ``Person`` class::
+First, create the ``Mailer`` class::
 
-    class Person
+    class Mailer
     {
         protected $options;
 
@@ -56,34 +56,31 @@ The ``$options`` property is an instance of
 means you can handle it just like a normal array::
 
     // ...
-    public function getFirstName()
+    public function getHost()
     {
-        return $this->options['firstName'];
+        return $this->options['host'];
     }
 
-    public function getFullName()
+    public function getPassword()
     {
-        $name = $this->options['firstName'];
-
-        if (isset($this->options['lastName'])) {
-            $name .= ' '.$this->options['lastName'];
-        }
-
-        return $name;
+        return $this->options['password'];
     }
 
+Configuring the OptionsResolver
+-------------------------------
+
 Now, try to actually use the class::
 
-    $person = new Person(array(
-        'firstName' => 'Wouter',
-        'lastName'  => 'de Jong',
+    $mailer = new Mailer(array(
+        'host'     => 'smtp.example.org',
+        'password' => 'pa$$word',
     ));
 
-    echo $person->getFirstName();
+    echo $mailer->getPassword();
 
 Right now, you'll receive a 
 :class:`Symfony\\Component\\OptionsResolver\\Exception\\InvalidOptionsException`,
-which tells you that the options ``firstName`` and ``lastName`` do not exist.
+which tells you that the options ``host`` and ``password`` do not exist.
 This is because you need to configure the ``OptionsResolver`` first, so it
 knows which options should be resolved.
 
@@ -100,7 +97,7 @@ the ``OptionsResolver`` class::
     use Symfony\Component\OptionsResolver\OptionsResolver;
     use Symfony\Component\OptionsResolver\OptionsResolverInterface;
 
-    class Person
+    class Mailer
     {
         protected $options;
 
@@ -119,25 +116,25 @@ the ``OptionsResolver`` class::
     }
 
 Required Options
-----------------
+~~~~~~~~~~~~~~~~
 
-Suppose the ``firstName`` option is required: the class can't work without
-it. You can set the required options by calling
+The ``host`` option is required: the class can't work without it. You can set
+the required options by calling
 :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setRequired`::
 
     // ...
     protected function setDefaultOptions(OptionsResolverInterface $resolver)
     {
-        $resolver->setRequired(array('firstName'));
+        $resolver->setRequired(array('host'));
     }
 
 You are now able to use the class without errors::
 
-    $person = new Person(array(
-        'firstName' => 'Wouter',
+    $mailer = new Mailer(array(
+        'host' => 'smtp.example.org',
     ));
 
-    echo $person->getFirstName(); // 'Wouter'
+    echo $mailer->getHost(); // 'smtp.example.org'
 
 If you don't pass a required option, a
 :class:`Symfony\\Component\\OptionsResolver\\Exception\\MissingOptionsException`
@@ -148,22 +145,22 @@ To determine if an option is required, you can use the
 method.
 
 Optional Options
-----------------
+~~~~~~~~~~~~~~~~
 
-Sometimes, an option can be optional (e.g. the ``lastName`` option in the
-``Person`` class). You can configure these options by calling
+Sometimes, an option can be optional (e.g. the ``password`` option in the
+``Mailer`` class). You can configure these options by calling
 :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setOptional`::
 
     // ...
     protected function setDefaultOptions(OptionsResolverInterface $resolver)
     {
         // ...
 
-        $resolver->setOptional(array('lastName'));
+        $resolver->setOptional(array('password'));
     }
 
 Set Default Values
-------------------
+~~~~~~~~~~~~~~~~~~
 
 Most of the optional options have a default value. You can configure these
 options by calling
@@ -175,14 +172,15 @@ options by calling
         // ...
 
         $resolver->setDefaults(array(
-            'age' => 0,
+            'username' => 'root',
         ));
     }
 
-The default age will be ``0`` now. When the user specifies an age, it gets
-replaced. You don't need to configure ``age`` as an optional option. The
-``OptionsResolver`` already knows that options with a default value are
-optional.
+This would add a third option - ``username`` - and give it a default value
+of ``root``. If the user passes in a ``username`` option, that value will
+override this default. You don't need to configure ``username`` as an optional
+option. The ``OptionsResolver`` already knows that options with a default
+value are optional.
 
 The ``OptionsResolver`` component also has an
 :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::replaceDefaults`
@@ -196,8 +194,8 @@ that is passed has 2 parameters:
 Default Values that depend on another Option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Suppose you add a ``gender`` option to the ``Person`` class, whose default
-value you guess based on the first name. You can do that easily by using a
+Suppose you add a ``port`` option to the ``Mailer`` class, whose default
+value you guess based on the host. You can do that easily by using a
 Closure as the default value::
 
     use Symfony\Component\OptionsResolver\Options;
@@ -208,12 +206,12 @@ Closure as the default value::
         // ...
 
         $resolver->setDefaults(array(
-            'gender' => function (Options $options) {
-                if (GenderGuesser::isMale($options['firstName'])) {
-                    return 'male';
+            'port' => function (Options $options) {
+                if (in_array($options['host'], array('127.0.0.1', 'localhost')) {
+                    return 80;
                 }
                 
-                return 'female';
+                return 25;
             },
         ));
     }
@@ -224,11 +222,11 @@ Closure as the default value::
     otherwise it is considered as the value.
 
 Configure allowed Values
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-Not all values are valid values for options. For instance, the ``gender``
-option can only be ``female`` or ``male``. You can configure these allowed
-values by calling
+Not all values are valid values for options. Suppose the ``Mailer`` class has
+a ``transport`` option, it can only be one of ``sendmail``, ``mail`` or
+``smtp``. You can configure these allowed values by calling
 :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setAllowedValues`::
 
     // ...
@@ -237,20 +235,20 @@ values by calling
         // ...
 
         $resolver->setAllowedValues(array(
-            'gender' => array('male', 'female'),
+            'transport' => array('sendmail', 'mail', 'smtp'),
         ));
     }
 
 There is also an
 :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::addAllowedValues`
-method, which you can use if you want to add an allowed value to the previous
+method, which you can use if you want to add an allowed value to the previously
 set allowed values.
 
 Configure allowed Types
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-You can also specify allowed types. For instance, the ``firstName`` option can
-be anything, but it must be a string. You can configure these types by calling
+You can also specify allowed types. For instance, the ``port`` option can
+be anything, but it must be an integer. You can configure these types by calling
 :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setAllowedTypes`::
 
     // ...
@@ -259,27 +257,26 @@ be anything, but it must be a string. You can configure these types by calling
         // ...
 
         $resolver->setAllowedTypes(array(
-            'firstName' => 'string',
+            'port' => 'integer',
         ));
     }
 
-Possible types are the one associated with the ``is_*`` php functions or a
+Possible types are the ones associated with the ``is_*`` php functions or a
 class name. You can also pass an array of types as the value. For instance,
-``array('null', 'string')`` allows ``firstName`` to be ``null`` or a
-``string``.
+``array('null', 'string')`` allows ``port`` to be ``null`` or a ``string``.
 
 There is also an
 :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::addAllowedTypes`
 method, which you can use to add an allowed type to the previous allowed types.
 
 Normalize the Options
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
-Some values need to be normalized before you can use them. For instance, the
-``firstName`` should always start with an uppercase letter. To do that, you can
-write normalizers. These Closures will be executed after all options are
-passed and return the normalized value. You can configure these normalizers by
-calling
+Some values need to be normalized before you can use them. For instance,
+pretend that the ``host`` should always start with ``http://``. To do that,
+you can write normalizers. These Closures will be executed after all options
+are passed and should return the normalized value. You can configure these
+normalizers by calling
 :method:`Symfony\\Components\\OptionsResolver\\OptionsResolver::setNormalizers`::
 
     // ...
@@ -288,13 +285,37 @@ calling
         // ...
 
         $resolver->setNormalizers(array(
-            'firstName' => function (Options $options, $value) {
-                return ucfirst($value);
+            'host' => function (Options $options, $value) {
+                if ('http://' !== substr($value, 0, 7)) {
+                    $value = 'http://'.$value;
+                }
+
+                return $value;
             },
         ));
     }
 
-You see that the closure also get an ``$options`` parameter. Sometimes, you
-need to use the other options for normalizing.
+You see that the closure also gets an ``$options`` parameter. Sometimes, you
+need to use the other options for normalizing::
+
+    // ...
+    protected function setDefaultOptions(OptionsResolverInterface $resolver)
+    {
+        // ...
+
+        $resolver->setNormalizers(array(
+            'host' => function (Options $options, $value) {
+                if (!in_array(substr($value, 0, 7), array('http://', 'https://')) {
+                    if ($options['ssl']) {
+                        $value = 'https://'.$value;
+                    } else {
+                        $value = 'http://'.$value;
+                    }
+                }
+
+                return $value;
+            },
+        ));
+    }
 
 .. _Packagist: https://packagist.org/packages/symfony/options-resolver
