Merge branch '2.3' into 2.4

book/forms.rst

@@ -48,6 +48,7 @@ going to need to build a form. But before you begin, first focus on the generic
         {
             return $this->dueDate;
         }
+        
         public function setDueDate(\DateTime $dueDate = null)
         {
             $this->dueDate = $dueDate;

book/http_cache.rst

@@ -795,13 +795,13 @@ Gateway caches are a great way to make your website perform better. But they
 have one limitation: they can only cache whole pages. If you can't cache
 whole pages or if parts of a page has "more" dynamic parts, you are out of
 luck. Fortunately, Symfony2 provides a solution for these cases, based on a
-technology called `ESI`_, or Edge Side Includes. Akamaï wrote this specification
+technology called `ESI`_, or Edge Side Includes. Akamai wrote this specification
 almost 10 years ago, and it allows specific parts of a page to have a different
 caching strategy than the main page.
 
 The ESI specification describes tags you can embed in your pages to communicate
 with the gateway cache. Only one tag is implemented in Symfony2, ``include``,
-as this is the only useful one outside of Akamaï context:
+as this is the only useful one outside of Akamai context:
 
 .. code-block:: html
 
@@ -936,7 +936,7 @@ used ``render``.
 
 .. note::
 
-    Symfony2 detects if a gateway cache supports ESI via another Akamaï
+    Symfony2 detects if a gateway cache supports ESI via another Akamai
     specification that is supported out of the box by the Symfony2 reverse
     proxy.
 

book/security.rst

@@ -764,13 +764,13 @@ is used to enforce access.
 Each ``access_control`` has several options that configure two different
 things:
 
-* (a) :ref:`should the incoming request match this access control entry <security-book-access-control-matching-options>`
-* (b) :ref:`once it matches, should some sort of access restriction be enforced <security-book-access-control-enforcement-options>`:
+#. :ref:`should the incoming request match this access control entry <security-book-access-control-matching-options>`
+#. :ref:`once it matches, should some sort of access restriction be enforced <security-book-access-control-enforcement-options>`:
 
 .. _security-book-access-control-matching-options:
 
-(a) Matching Options
-....................
+1. Matching Options
+...................
 
 Symfony2 creates an instance of :class:`Symfony\\Component\\HttpFoundation\\RequestMatcher`
 for each ``access_control`` entry, which determines whether or not a given
@@ -865,8 +865,8 @@ will match any ``ip``, ``host`` or ``method``:
 
 .. _security-book-access-control-enforcement-options:
 
-(b) Access Enforcement
-......................
+2. Access Enforcement
+.....................
 
 Once Symfony2 has decided which ``access_control`` entry matches (if any),
 it then *enforces* access restrictions based on the ``roles`` and ``requires_channel``

book/translation.rst

@@ -392,7 +392,7 @@ key ``Symfony2 is great``. To find the French translation, Symfony actually
 checks translation resources for several different locales:
 
 1. First, Symfony looks for the translation in a ``fr_FR`` translation resource
-   (e.g. ``messages.fr_FR.xfliff``);
+   (e.g. ``messages.fr_FR.xliff``);
 
 2. If it wasn't found, Symfony looks for the translation in a ``fr`` translation
    resource (e.g. ``messages.fr.xliff``);

components/config/definition.rst

@@ -396,8 +396,8 @@ process is used to remove some of the differences that result from different
 configuration formats, mainly the differences between YAML and XML.
 
 The separator used in keys is typically ``_`` in YAML and ``-`` in XML. For
-example, ``auto_connect`` in YAML and ``auto-connect``. The normalization would
-make both of these ``auto_connect``.
+example, ``auto_connect`` in YAML and ``auto-connect`` in XML.
+The normalization would make both of these ``auto_connect``.
 
 .. caution::
 

components/console/helpers/dialoghelper.rst

@@ -12,8 +12,8 @@ helper set, which you can get by calling
     $dialog = $this->getHelperSet()->get('dialog');
 
 All the methods inside the Dialog Helper have an
-:class:`Symfony\\Component\\Console\\Output\\OutputInterface` as first the
-argument, the question as the second argument and the default value as last
+:class:`Symfony\\Component\\Console\\Output\\OutputInterface` as the first
+argument, the question as the second argument and the default value as the last
 argument.
 
 Asking the User for confirmation
@@ -52,8 +52,9 @@ if you want to know a bundle name, you can add this to your command::
     );
 
 The user will be asked "Please enter the name of the bundle". They can type
-some name which will be returned by the ``ask`` method. If they leave it empty,
-the default value (``AcmeDemoBundle`` here) is returned.
+some name which will be returned by the
+:method:`Symfony\\Component\\Console\\Helper\\DialogHelper::ask` method.
+If they leave it empty, the default value (``AcmeDemoBundle`` here) is returned.
 
 Autocompletion
 ~~~~~~~~~~~~~~
@@ -235,9 +236,12 @@ this set the seventh argument to ``true``::
         return $colors[$c];
     }, $selected);
 
-    $output->writeln('You have just selected: ' . implode(', ', $selectedColors));
+    $output->writeln(
+        'You have just selected: ' . implode(', ', $selectedColors)
+    );
 
-Now, when the user enters ``1,2``, the result will be: ``You have just selected: blue, yellow``.
+Now, when the user enters ``1,2``, the result will be:
+``You have just selected: blue, yellow``.
 
 Testing a Command which expects input
 -------------------------------------

components/dependency_injection/parameters.rst

@@ -295,7 +295,7 @@ keywords (respectively ``true``, ``false`` and ``null``):
 .. code-block:: xml
 
     <parameters>
-        <parameter key="mailer.send_all_in_once">false</parameters>
+        <parameter key="mailer.send_all_in_once">false</parameter>
     </parameters>
 
     <!-- after parsing

components/dependency_injection/tags.rst

@@ -199,9 +199,6 @@ To begin with, change the ``TransportChain`` class::
             if (array_key_exists($alias, $this->transports)) {
                return $this->transports[$alias];
             }
-            else {
-               return;
-            }
         }
     }
 

components/dom_crawler.rst

@@ -55,11 +55,11 @@ interacting with html links and forms as you traverse through the HTML tree.
 .. note::
 
     The DomCrawler will attempt to automatically fix your HTML to match the
-    official specification. For example, if you nest a `` <p>`` tag inside
-    another `` <p>`` tag, it will be moved to be a sibling of the parent tag.
+    official specification. For example, if you nest a ``<p>`` tag inside
+    another ``<p>`` tag, it will be moved to be a sibling of the parent tag.
     This is expected and is part of the HTML5 spec. But if you're getting
     unexpected behavior, this could be a cause. And while the DomCrawler
-    isn't meant to dump content, you can see the "fixed" version if your HTML
+    isn't meant to dump content, you can see the "fixed" version of your HTML
     by :ref:`dumping it <component-dom-crawler-dumping>`.
 
 Node Filtering
@@ -83,10 +83,12 @@ Anonymous function can be used to filter with more complex criteria::
     use Symfony\Component\DomCrawler\Crawler;
     // ...
 
-    $crawler = $crawler->filter('body > p')->reduce(function (Crawler $node, $i) {
-        // filter even nodes
-        return ($i % 2) == 0;
-    });
+    $crawler = $crawler
+        ->filter('body > p')
+        ->reduce(function (Crawler $node, $i) {
+            // filter even nodes
+            return ($i % 2) == 0;
+        });
 
 To remove a node the anonymous function must return false.
 

components/options_resolver.rst

@@ -50,17 +50,17 @@ The advantages of doing this will become more obvious as you continue::
         $this->options = $resolver->resolve($options);
     }
 
-The options property now is a well defined array with all resolved options readily available::
+The options property now is a well defined array with all resolved options
+readily available::
 
     // ...
-    public function getHost()
+    public function sendMail($from, $to)
     {
-        return $this->options['host'];
-    }
-
-    public function getPassword()
-    {
-        return $this->options['password'];
+        $mail = ...;
+        $mail->setHost($this->options['host']);
+        $mail->setUsername($this->options['username']);
+        $mail->setPassword($this->options['password']);
+        // ...
     }
 
 Configuring the OptionsResolver
@@ -70,6 +70,7 @@ Now, try to actually use the class::
 
     $mailer = new Mailer(array(
         'host'     => 'smtp.example.org',
+        'username' => 'user',
         'password' => 'pa$$word',
     ));
 
@@ -86,7 +87,7 @@ knows which options should be resolved.
     function.
 
 A best practice is to put the configuration in a method (e.g.
-``setDefaultOptions``). You call this method in the constructor to configure
+``configureOptions``). You call this method in the constructor to configure
 the ``OptionsResolver`` class::
 
     use Symfony\Component\OptionsResolver\OptionsResolver;
@@ -99,17 +100,38 @@ the ``OptionsResolver`` class::
         public function __construct(array $options = array())
         {
             $resolver = new OptionsResolver();
-            $this->setDefaultOptions($resolver);
+            $this->configureOptions($resolver);
 
             $this->options = $resolver->resolve($options);
         }
 
-        protected function setDefaultOptions(OptionsResolverInterface $resolver)
+        protected function configureOptions(OptionsResolverInterface $resolver)
         {
             // ... configure the resolver, you will learn this in the sections below
         }
     }
 
+Set Default Values
+~~~~~~~~~~~~~~~~~~
+
+Most of the options have a default value. You can configure these options by
+calling :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setDefaults`::
+
+    // ...
+    protected function setDefaultOptions(OptionsResolverInterface $resolver)
+    {
+        // ...
+
+        $resolver->setDefaults(array(
+            'username' => 'root',
+        ));
+    }
+
+This would add an 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.
+
 Required Options
 ~~~~~~~~~~~~~~~~
 
@@ -135,15 +157,18 @@ If you don't pass a required option, a
 :class:`Symfony\\Component\\OptionsResolver\\Exception\\MissingOptionsException`
 will be thrown.
 
-To determine if an option is required, you can use the
-:method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::isRequired`
-method.
+.. tip::
+
+    To determine if an option is required, you can use the
+    :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::isRequired`
+    method.
 
 Optional Options
 ~~~~~~~~~~~~~~~~
 
 Sometimes, an option can be optional (e.g. the ``password`` option in the
-``Mailer`` class). You can configure these options by calling
+``Mailer`` class), but it doesn't have a default value. You can configure
+these options by calling
 :method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setOptional`::
 
     // ...
@@ -154,34 +179,23 @@ Sometimes, an option can be optional (e.g. the ``password`` option in the
         $resolver->setOptional(array('password'));
     }
 
-Set Default Values
-~~~~~~~~~~~~~~~~~~
-
-Most of the optional options have a default value. You can configure these
-options by calling
-:method:`Symfony\\Component\\OptionsResolver\\OptionsResolver::setDefaults`::
+Options with defaults are already marked as optional.
 
-    // ...
-    protected function setDefaultOptions(OptionsResolverInterface $resolver)
-    {
-        // ...
+.. tip::
 
-        $resolver->setDefaults(array(
-            'username' => 'root',
-        ));
-    }
+    When setting an option as optional, you can't be sure if it's in the array
+    or not. You have to check if the option exists before using it.
 
-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.
+    To avoid checking if it exists everytime, you can also set a default of
+    ``null`` to an option using the ``setDefaults()`` method (see `Set Default Values`_),
+    this means the element always exists in the array, but with a default of
+    ``null``.
 
-Default Values that depend on another Option
+Default Values that Depend on another Option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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
+value you guess based on the encryption. You can do that easily by using a
 closure as the default value::
 
     use Symfony\Component\OptionsResolver\Options;
@@ -193,16 +207,21 @@ closure as the default value::
         // ...
 
         $resolver->setDefaults(array(
+            'encryption' => null,
             'port' => function (Options $options) {
-                if (in_array($options['host'], array('127.0.0.1', 'localhost'))) {
-                    return 80;
+                if ('ssl' === $options['encryption']) {
+                    return 465;
                 }
 
                 return 25;
             },
         ));
     }
 
+The :class:`Symfony\\Component\\OptionsResolver\\Options` class implements
+:phpclass:`ArrayAccess`, :phpclass:`Iterator` and :phpclass:`Countable`. That
+means you can handle it just like a normal array containing the options.
+
 .. caution::
 
     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
         // ...
 
         $resolver->setAllowedValues(array(
-            'transport' => array('sendmail', 'mail', 'smtp'),
+            'encryption' => array(null, 'ssl', 'tls'),
         ));
     }
 
 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 previously
-set allowed values.
+configured allowed values.
 
-Configure allowed Types
+Configure Allowed Types
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 You can also specify allowed types. For instance, the ``port`` option can