Merge branch '2.4'

Conflicts:
	reference/dic_tags.rst

book/installation.rst

@@ -247,8 +247,8 @@ If there are any issues, correct them now before moving on.
     .. code-block:: bash
 
 		$ APACHEUSER=`ps aux | grep -E '[a]pache|[h]ttpd' | grep -v root | head -1 | cut -d\  -f1`
-		$ sudo setfacl -R -m u:$APACHEUSER:rwX -m u:`whoami`:rwX app/cache app/logs
-		$ sudo setfacl -dR -m u:$APACHEUSER:rwX -m u:`whoami`:rwX app/cache app/logs
+		$ sudo setfacl -R -m u:"$APACHEUSER":rwX -m u:`whoami`:rwX app/cache app/logs
+		$ sudo setfacl -dR -m u:"$APACHEUSER":rwX -m u:`whoami`:rwX app/cache app/logs
 
     **3. Without using ACL**
 

book/validation.rst

@@ -113,8 +113,9 @@ Next, to actually validate an ``Author`` object, use the ``validate`` method
 on the ``validator`` service (class :class:`Symfony\\Component\\Validator\\Validator`).
 The job of the ``validator`` is easy: to read the constraints (i.e. rules)
 of a class and verify whether or not the data on the object satisfies those
-constraints. If validation fails, an array of errors is returned. Take this
-simple example from inside a controller::
+constraints. If validation fails, a non-empty list of errors
+(class :class:`Symfony\\Component\\Validator\\ConstraintViolationList`) is
+returned. Take this simple example from inside a controller:
 
     // ...
     use Symfony\Component\HttpFoundation\Response;

components/dom_crawler.rst

@@ -95,6 +95,65 @@ To remove a node the anonymous function must return false.
     All filter methods return a new :class:`Symfony\\Component\\DomCrawler\\Crawler`
     instance with filtered content.
 
+Both the :method:`Symfony\\Component\\DomCrawler\\Crawler::filterXPath` and
+:method:`Symfony\\Component\\DomCrawler\\Crawler::filter` methods work with
+XML namespaces, which can be either automatically discovered or registered
+explicitly.
+
+.. versionadded:: 2.4
+    Auto discovery and explicit registration of namespaces was introduced
+    in Symfony 2.4.
+
+Consider the XML below:
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <entry
+      xmlns="http://www.w3.org/2005/Atom"
+      xmlns:media="http://search.yahoo.com/mrss/"
+      xmlns:yt="http://gdata.youtube.com/schemas/2007">
+        <id>tag:youtube.com,2008:video:kgZRZmEc9j4</id>
+        <yt:accessControl action="comment" permission="allowed"/>
+        <yt:accessControl action="videoRespond" permission="moderated"/>
+        <media:group>
+            <media:title type="plain">Chordates - CrashCourse Biology #24</media:title>
+            <yt:aspectRatio>widescreen</yt:aspectRatio>
+        </media:group>
+    </entry>
+
+This can be filtered with the  ``Crawler`` without needing to register namespace
+aliases both with :method:`Symfony\\Component\\DomCrawler\\Crawler::filterXPath`::
+
+    $crawler = $crawler->filterXPath('//default:entry/media:group//yt:aspectRatio');
+
+and :method:`Symfony\\Component\\DomCrawler\\Crawler::filter`::
+
+    use Symfony\Component\CssSelector\CssSelector;
+
+    CssSelector::disableHtmlExtension();
+    $crawler = $crawler->filter('default|entry media|group yt|aspectRatio');
+
+.. note::
+
+    The default namespace is registered with a prefix "default". It can be
+    changed with the
+    :method:`Symfony\\Component\\DomCrawler\\Crawler::setDefaultNamespacePrefix`
+    method.
+
+    The default namespace is removed when loading the content if it's the only
+    namespace in the document. It's done to simplify the xpath queries.
+
+Namespaces can be explicitly registered with the
+:method:`Symfony\\Component\\DomCrawler\\Crawler::registerNamespace` method::
+
+    $crawler->registerNamespace('m', 'http://search.yahoo.com/mrss/');
+    $crawler = $crawler->filterXPath('//m:group//yt:aspectRatio');
+
+.. caution::
+
+    To query XML with a CSS selector, the HTML extension needs to be disabled with
+    :method:`CssSelector::disableHtmlExtension <Symfony\\Component\\CssSelector\\CssSelector::disableHtmlExtension>`
+    to avoid converting the selector to lowercase.
+
 Node Traversing
 ~~~~~~~~~~~~~~~
 

components/form/introduction.rst

@@ -66,15 +66,23 @@ factory.
 Request Handling
 ~~~~~~~~~~~~~~~~
 
-To process form data, you'll need to grab information off of the request (typically
-``$_POST`` data) and pass the array of submitted data to
-:method:`Symfony\\Component\\Form\\Form::bind`. The Form component optionally
-integrates with Symfony's :doc:`HttpFoundation </components/http_foundation/introduction>`
-component to make this even easier.
+.. versionadded:: 2.3
+    The ``handleRequest()`` method was added in Symfony 2.3.
 
-To integrate the HttpFoundation component, add the
-:class:`Symfony\\Component\\Form\\Extension\\HttpFoundation\\HttpFoundationExtension`
-to your form factory::
+To process form data, you'll need to call the :method:`Symfony\\Component\\Form\\Form::handleRequest`
+method::
+
+    $form->handleRequest();
+
+Behind the scenes, this uses a :class:`Symfony\\Component\\Form\\NativeRequestHandler`
+object to read data off of the correct PHP superglobals (i.e. ``$_POST`` or
+``$_GET``) based on the HTTP method configured on the form (POST is default).
+
+.. sidebar:: Integration with the HttpFoundation Component
+
+    If you use the HttpFoundation component, then you should add the
+    :class:`Symfony\\Component\\Form\\Extension\\HttpFoundation\\HttpFoundationExtension`
+    to your form factory::
 
     use Symfony\Component\Form\Forms;
     use Symfony\Component\Form\Extension\HttpFoundation\HttpFoundationExtension;
@@ -83,14 +91,15 @@ to your form factory::
         ->addExtension(new HttpFoundationExtension())
         ->getFormFactory();
 
-Now, when you process a form, you can pass the :class:`Symfony\\Component\\HttpFoundation\\Request`
-object to :method:`Symfony\\Component\\Form\\Form::bind` instead of the raw
-array of submitted values.
+        Now, when you process a form, you can pass the :class:`Symfony\\Component\\HttpFoundation\\Request`
+        object to :method:`Symfony\\Component\\Form\\Form::handleRequest`::
 
-.. note::
+            $form->handleRequest($request);
 
-    For more information about the HttpFoundation component or how to
-    install it, see :doc:`/components/http_foundation/introduction`.
+    .. note::
+
+        For more information about the HttpFoundation component or how to
+        install it, see :doc:`/components/http_foundation/introduction`.
 
 CSRF Protection
 ~~~~~~~~~~~~~~~
@@ -480,7 +489,7 @@ to do that in the ":ref:`form-rendering-template`" section.
 Handling Form Submissions
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To handle form submissions, use the :method:`Symfony\\Component\\Form\\Form::bind`
+To handle form submissions, use the :method:`Symfony\\Component\\Form\\Form::handleRequest`
 method:
 
 .. configuration-block::
@@ -497,19 +506,17 @@ method:
 
         $request = Request::createFromGlobals();
 
-        if ($request->isMethod('POST')) {
-            $form->bind($request);
+        $form->handleRequest($request);
 
-            if ($form->isValid()) {
-                $data = $form->getData();
+        if ($form->isValid()) {
+            $data = $form->getData();
 
-                // ... perform some action, such as saving the data to the database
+            // ... perform some action, such as saving the data to the database
 
-                $response = new RedirectResponse('/task/success');
-                $response->prepare($request);
+            $response = new RedirectResponse('/task/success');
+            $response->prepare($request);
 
-                return $response->send();
-            }
+            return $response->send();
         }
 
         // ...
@@ -525,17 +532,14 @@ method:
                 ->add('dueDate', 'date')
                 ->getForm();
 
-            // only process the form if the request is a POST request
-            if ($request->isMethod('POST')) {
-                $form->bind($request);
+            $form->handleRequest($request);
 
-                if ($form->isValid()) {
-                    $data = $form->getData();
+            if ($form->isValid()) {
+                $data = $form->getData();
 
-                    // ... perform some action, such as saving the data to the database
+                // ... perform some action, such as saving the data to the database
 
-                    return $this->redirect($this->generateUrl('task_success'));
-                }
+                return $this->redirect($this->generateUrl('task_success'));
             }
 
             // ...
@@ -546,25 +550,15 @@ This defines a common form "workflow", which contains 3 different possibilities:
 1) On the initial GET request (i.e. when the user "surfs" to your page),
    build your form and render it;
 
-If the request is a POST, process the submitted data (via ``bind``). Then:
-
-2) if the form is invalid, re-render the form (which will now contain errors)
-3) if the form is valid, perform some action and redirect;
-
-.. note::
-
-    If you're not using HttpFoundation, just pass the POST'ed data directly
-    to ``bind``::
-
-        if (isset($_POST[$form->getName()])) {
-            $form->bind($_POST[$form->getName()]);
+If the request is a POST, process the submitted data (via ``handleRequest()``).
+Then:
 
-            // ...
-        }
+2) if the form is invalid, re-render the form (which will now contain errors);
+3) if the form is valid, perform some action and redirect.
 
-    If you're uploading files, you'll need to do a little bit more work by
-    merging the ``$_POST`` array with the ``$_FILES`` array before passing
-    it into ``bind``.
+Luckily, you don't need to decide whether or not a form has been submitted.
+Just pass the current request to the ``handleRequest()`` method. Then, the Form
+component will do all the necessary work for you.
 
 .. _component-form-intro-validation:
 

contributing/documentation/overview.rst

@@ -29,17 +29,17 @@ Consistent with Symfony's source code, the documentation repository is split int
 multiple branches, corresponding to the different versions of Symfony itself.
 The ``master`` branch holds the documentation for the development branch of the code.
 
-Unless you're documenting a feature that was introduced *after* Symfony 2.2
-(e.g. in Symfony 2.3), your changes should always be based on the 2.2 branch.
-To do this checkout the 2.2 branch before the next step:
+Unless you're documenting a feature that was introduced *after* Symfony 2.3
+(e.g. in Symfony 2.4), your changes should always be based on the 2.3 branch.
+To do this checkout the 2.3 branch before the next step:
 
 .. code-block:: bash
 
-    $ git checkout 2.2
+    $ git checkout 2.3
 
 .. tip::
 
-    Your base branch (e.g. 2.2) will become the "Applies to" in the :ref:`doc-contributing-pr-format`
+    Your base branch (e.g. 2.3) will become the "Applies to" in the :ref:`doc-contributing-pr-format`
     that you'll use later.
 
 Next, create a dedicated branch for your changes (for organization):
@@ -57,17 +57,17 @@ Creating a Pull Request
 Following the example, the pull request will default to be between your
 ``improving_foo_and_bar`` branch and the ``symfony-docs`` ``master`` branch.
 
-If you have made your changes based on the 2.2 branch then you need to change
-the base branch to be 2.2 on the preview page by clicking the ``edit`` button
+If you have made your changes based on the 2.3 branch then you need to change
+the base branch to be 2.3 on the preview page by clicking the ``edit`` button
 on the top left:
 
 .. image:: /images/docs-pull-request-change-base.png
    :align: center
 
 .. note::
 
-  All changes made to a branch (e.g. 2.2) will be merged up to each "newer"
-  branch (e.g. 2.3, master, etc) for the next release on a weekly basis.
+  All changes made to a branch (e.g. 2.3) will be merged up to each "newer"
+  branch (e.g. 2.4, master, etc) for the next release on a weekly basis.
 
 GitHub covers the topic of `pull requests`_ in detail.
 

contributing/documentation/standards.rst

@@ -125,6 +125,14 @@ Language Standards
 * Do not use `Serial (Oxford) Commas`_;
 * You should use a form of *you* instead of *we* (i.e. avoid the first person
   point of view: use the second instead).
+* When referencing a hypothetical person, such as "a user with a session cookie", gender-neutral
+  pronouns (they/their/them) should be used. For example, instead of:
+
+     * he or she, use they
+     * him or her, use them
+     * his or her, use their
+     * his or hers, use theirs
+     * himself or herself, use themselves
 
 .. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code
 .. _`Twig Coding Standards`: http://twig.sensiolabs.org/doc/coding_standards.html

cookbook/form/direct_submit.rst

@@ -27,7 +27,7 @@ submissions::
 
             return $this->redirect($this->generateUrl('task_success'));
         }
-        
+
         return $this->render('AcmeTaskBundle:Default:new.html.twig', array(
             'form' => $form->createView(),
         ));
@@ -45,9 +45,9 @@ Calling Form::submit() manually
 
 In some cases, you want better control over when exactly your form is submitted
 and what data is passed to it. Instead of using the
-:method:`Symfony\Component\Form\FormInterface::handleRequest`
+:method:`Symfony\\Component\\Form\\FormInterface::handleRequest`
 method, pass the submitted data directly to
-:method:`Symfony\Component\Form\FormInterface::submit`::
+:method:`Symfony\\Component\\Form\\FormInterface::submit`::
 
     use Symfony\Component\HttpFoundation\Request;
     // ...
@@ -76,8 +76,8 @@ method, pass the submitted data directly to
 .. tip::
 
     Forms consisting of nested fields expect an array in
-    :method:`Symfony\Component\Form\FormInterface::submit`. You can also submit
-    individual fields by calling :method:`Symfony\Component\Form\FormInterface::submit`
+    :method:`Symfony\\Component\\Form\\FormInterface::submit`. You can also submit
+    individual fields by calling :method:`Symfony\\Component\\Form\\FormInterface::submit`
     directly on the field::
 
         $form->get('firstName')->submit('Fabien');
@@ -90,7 +90,7 @@ Passing a Request to Form::submit() (deprecated)
 .. versionadded:: 2.3
     Before Symfony 2.3, the ``submit`` method was known as ``bind``.
 
-Before Symfony 2.3, the :method:`Symfony\Component\Form\FormInterface::submit`
+Before Symfony 2.3, the :method:`Symfony\\Component\\Form\\FormInterface::submit`
 method accepted a :class:`Symfony\\Component\\HttpFoundation\\Request` object as
 a convenient shortcut to the previous example::
 
@@ -118,7 +118,7 @@ a convenient shortcut to the previous example::
         ));
     }
 
-Passing the :class:`Symfony\\Component\HttpFoundation\\Request` directly to
+Passing the :class:`Symfony\\Component\\HttpFoundation\\Request` directly to
 :method:`Symfony\\Component\\Form\\FormInterface::submit` still works, but is
 deprecated and will be removed in Symfony 3.0. You should use the method
-:method:`Symfony\Component\Form\FormInterface::handleRequest` instead.
+:method:`Symfony\\Component\\Form\\FormInterface::handleRequest` instead.

cookbook/map.rst.inc

@@ -132,9 +132,12 @@
   * :doc:`/cookbook/security/acl`
   * :doc:`/cookbook/security/acl_advanced`
   * :doc:`/cookbook/security/force_https`
+  * :doc:`/cookbook/security/host_restriction`
   * :doc:`/cookbook/security/form_login`
   * :doc:`/cookbook/security/securing_services`
   * :doc:`/cookbook/security/custom_provider`
+  * :doc:`/cookbook/security/custom_password_authenticator`
+  * :doc:`/cookbook/security/api_key_authentication`
   * :doc:`/cookbook/security/custom_authentication_provider`
   * :doc:`/cookbook/security/target_path`