Merge branch '2.5' into 2.6

* 2.5:
  Fix up the final sentence to be a bit cleaner.
  SetDescription required on Product entities
  typo fix
  Fixed typo
  Modifying the best practice to use form_start() instead of <form
  Proposing that we make the service names *just* a little bit longer
  fix elseif statement
  Fixed wrong indentation
  Bot fixes
  tweaks to the Twig reference
  Removed unnecessary use statement in code example in the debugging cookbook
  [Form] document $deep and $flatten of getErrors()
  describe how to access form errors
  Changed userName to username
  Update slash_in_parameter.rst
  Applied suggestion by Ryan
  Update form_customization.rst
  Merging emphasized notes
  Adder and remover sidenote

best_practices/business-logic.rst

@@ -81,7 +81,7 @@ Next, define a new service for that class.
     # app/config/services.yml
     services:
         # keep your service names short
-        slugger:
+        app.slugger:
             class: AppBundle\Utils\Slugger
 
 Traditionally, the naming convention for a service involved following the
@@ -92,7 +92,8 @@ your code will be easier to read and use.
 .. best-practice::
 
     The name of your application's services should be as short as possible,
-    ideally just one simple word.
+    but unique enough that you can search your project for the service if
+    you ever need to.
 
 Now you can use the custom slugger in any controller class, such as the
 ``AdminController``:
@@ -104,7 +105,7 @@ Now you can use the custom slugger in any controller class, such as the
         // ...
 
         if ($form->isSubmitted() && $form->isValid()) {
-            $slug = $this->get('slugger')->slugify($post->getTitle());
+            $slug = $this->get('app.slugger')->slugify($post->getTitle());
             $post->setSlug($slug);
 
             // ...
@@ -143,7 +144,7 @@ the class namespace as a parameter:
         slugger.class: AppBundle\Utils\Slugger
 
     services:
-        slugger:
+        app.slugger:
             class: "%slugger.class%"
 
 This practice is cumbersome and completely unnecessary for your own services:

best_practices/forms.rst

@@ -157,29 +157,15 @@ There are a lot of ways to render your form, ranging from rendering the entire
 thing in one line to rendering each part of each field independently. The
 best way depends on how much customization you need.
 
-The simplest way - which is especially useful during development - is to render
-the form tags manually and then use ``form_widget()`` to render all of the fields:
+One of the simplest ways - which is especially useful during development -
+is to render the form tags and use ``form_widget()`` to render all of the
+fields:
 
 .. code-block:: html+jinja
 
-    <form method="POST" {{ form_enctype(form) }}>
+    {{ form_start(form, {'attr': {'class': 'my-form-class'} }) }}
         {{ form_widget(form) }}
-    </form>
-
-.. best-practice::
-
-    Don't use the ``form()`` or ``form_start()`` functions to render the
-    starting and ending form tags.
-
-Experienced Symfony developers will recognize that we're rendering the ``<form>``
-tags manually instead of using the ``form_start()`` or ``form()`` functions.
-While those are convenient, they take away from some clarity with little
-benefit.
-
-.. tip::
-
-    The exception is a delete form because it's really just one button and
-    so benefits from some of these extra shortcuts.
+    {{ form_end(form) }}
 
 If you need more control over how your fields are rendered, then you should
 remove the ``form_widget(form)`` function and render your fields individually.

book/doctrine.rst

@@ -1105,6 +1105,7 @@ Now you can see this new code in action! Imagine you're inside a controller::
             $product = new Product();
             $product->setName('Foo');
             $product->setPrice(19.99);
+            $product->setDescription('Lorem ipsum dolor');
             // relate this product to the category
             $product->setCategory($category);
 

book/from_flat_php_to_symfony2.rst

@@ -367,7 +367,7 @@ on the requested URI:
     require_once 'controllers.php';
 
     // route the request internally
-    $uri = $_SERVER['REQUEST_URI'];
+    $uri = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
     if ('/index.php' == $uri) {
         list_action();
     } elseif ('/index.php/show' == $uri && isset($_GET['id'])) {

components/form/introduction.rst

@@ -663,29 +663,45 @@ and the errors will display next to the fields on error.
 Accessing Form Errors
 ~~~~~~~~~~~~~~~~~~~~~
 
+.. versionadded:: 2.5
+    Before Symfony 2.5, ``getErrors()`` returned an array of ``FormError``
+    objects. The return value was changed to ``FormErrorIterator`` in Symfony
+    2.5.
+
+.. versionadded:: 2.5
+    The ``$deep`` and ``$flatten`` arguments were introduced in Symfony 2.5.
+
 You can use the :method:`Symfony\\Component\\Form\\FormInterface::getErrors`
-method to access the list of errors. Each element is a :class:`Symfony\\Component\\Form\\FormError`
-object::
+method to access the list of errors. It returns a
+:class:`Symfony\\Component\\Form\\FormErrorIterator` instance::
 
     $form = ...;
 
     // ...
 
-    // an array of FormError objects, but only errors attached to this form level (e.g. "global errors)
+    // a FormErrorIterator instance, but only errors attached to this form level (e.g. "global errors)
     $errors = $form->getErrors();
 
-    // an array of FormError objects, but only errors attached to the "firstName" field
+    // a FormErrorIterator instance, but only errors attached to the "firstName" field
     $errors = $form['firstName']->getErrors();
 
-    // a string representation of all errors of the whole form tree
-    $errors = $form->getErrorsAsString();
+    // a FormErrorIterator instance in a flattened structure
+    // use getOrigin() to determine the form causing the error
+    $errors = $form->getErrors(true);
 
-.. note::
+    // a FormErrorIterator instance representing the form tree structure
+    $errors = $form->getErrors(true, false);
+
+.. tip::
+
+    In older Symfony versions, ``getErrors()`` returned an array. To use the
+    errors the same way in Symfony 2.5 or newer, you have to pass them to
+    PHP's :phpfunction:`iterator_to_array` function::
+
+        $errorsAsArray = iterator_to_array($form->getErrors());
 
-    If you enable the :ref:`error_bubbling <reference-form-option-error-bubbling>`
-    option on a field, calling ``getErrors()`` on the parent form will include
-    errors from that field. However, there is no way to determine which field
-    an error was originally attached to.
+    This is useful, for example, if you want to use PHP's ``array_`` function
+    on the form errors.
 
 .. _Packagist: https://packagist.org/packages/symfony/form
 .. _Twig:      http://twig.sensiolabs.org

contributing/documentation/overview.rst

@@ -170,7 +170,7 @@ Now you can **sync your fork** by executing the following command:
     $ git merge upstream/2.3
 
 This command will update the ``2.3`` branch, which is the one you used to
-create the new branch for your changes. If have used another base branch,
+create the new branch for your changes. If you have used another base branch,
 e.g. ``master``, replace the ``2.3`` with the appropriate branch name.
 
 Great! Now you can proceed by following the same steps explained in the previous

cookbook/debugging.rst

@@ -47,8 +47,6 @@ below::
     $loader = require_once __DIR__.'/../app/autoload.php';
     require_once __DIR__.'/../app/AppKernel.php';
 
-    use Symfony\Component\HttpFoundation\Request;
-
     $kernel = new AppKernel('dev', true);
     // $kernel->loadClassCache();
     $request = Request::createFromGlobals();

cookbook/form/form_collections.rst

@@ -463,9 +463,9 @@ we talk about next!).
 
 .. caution::
 
-    If no ``addTag`` **and** ``removeTag`` method is found, the form will
-    still use ``setTag`` even if ``by_reference`` is ``false``. You'll learn
-    more about the ``removeTag`` method later in this article.
+    You have to create **both** ``addTag`` and ``removeTag`` methods, 
+    otherwise the form will still use ``setTag`` even if ``by_reference`` is ``false``. 
+    You'll learn more about the ``removeTag`` method later in this article.
 
 .. sidebar:: Doctrine: Cascading Relations and saving the "Inverse" side
 

cookbook/form/form_customization.rst

@@ -67,11 +67,19 @@ just one line:
 
     .. code-block:: jinja
 
+        {# renders all fields #}
         {{ form_widget(form) }}
 
+        {# renders all fields *and* the form start and end tags #}
+        {{ form(form) }}
+
     .. code-block:: php
 
-        <?php echo $view['form']->widget($form); ?>
+        <!-- renders all fields -->
+        <?php echo $view['form']->widget($form) ?>
+
+        <!-- renders all fields *and* the form start and end tags -->
+        <?php echo $view['form']->form($form) ?>
 
 The remainder of this recipe will explain how every part of the form's markup
 can be modified at several different levels. For more information about form

cookbook/routing/slash_in_parameter.rst

@@ -5,12 +5,12 @@ How to Allow a "/" Character in a Route Parameter
 =================================================
 
 Sometimes, you need to compose URLs with parameters that can contain a slash
-``/``. For example, take the classic ``/hello/{name}`` route. By default,
+``/``. For example, take the classic ``/hello/{username}`` route. By default,
 ``/hello/Fabien`` will match this route but not ``/hello/Fabien/Kris``. This
 is because Symfony uses this character as separator between route parts.
 
 This guide covers how you can modify a route so that ``/hello/Fabien/Kris``
-matches the ``/hello/{name}`` route, where ``{name}`` equals ``Fabien/Kris``.
+matches the ``/hello/{username}`` route, where ``{username}`` equals ``Fabien/Kris``.
 
 Configure the Route
 -------------------
@@ -27,10 +27,10 @@ a more permissive regex path.
     .. code-block:: yaml
 
         _hello:
-            path:     /hello/{name}
+            path:     /hello/{username}
             defaults: { _controller: AcmeDemoBundle:Demo:hello }
             requirements:
-                name: .+
+                username: .+
 
     .. code-block:: xml
 
@@ -40,9 +40,9 @@ a more permissive regex path.
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/routing http://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="_hello" path="/hello/{name}">
+            <route id="_hello" path="/hello/{username}">
                 <default key="_controller">AcmeDemoBundle:Demo:hello</default>
-                <requirement key="name">.+</requirement>
+                <requirement key="username">.+</requirement>
             </route>
         </routes>
 
@@ -52,10 +52,10 @@ a more permissive regex path.
         use Symfony\Component\Routing\Route;
 
         $collection = new RouteCollection();
-        $collection->add('_hello', new Route('/hello/{name}', array(
+        $collection->add('_hello', new Route('/hello/{username}', array(
             '_controller' => 'AcmeDemoBundle:Demo:hello',
         ), array(
-            'name' => '.+',
+            'username' => '.+',
         )));
 
         return $collection;
@@ -75,4 +75,4 @@ a more permissive regex path.
             }
         }
 
-That's it! Now, the ``{name}`` parameter can contain the ``/`` character.
+That's it! Now, the ``{username}`` parameter can contain the ``/`` character.

cookbook/security/target_path.rst

@@ -67,4 +67,4 @@ Next, create your own ``ExceptionListener``::
         }
     }
 
-Add as much or few logic here as required for your scenario!
+Add as much or as little logic here as required for your scenario!

reference/configuration/assetic.rst

@@ -4,8 +4,8 @@
 AsseticBundle Configuration ("assetic")
 =======================================
 
-Full default Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Full Default Configuration
+--------------------------
 
 .. configuration-block::