Merge branch '2.7'

* 2.7: (22 commits)
  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
  Added a reference to the Bootstrap 3 form theme
  remove versionadded directives for old versions
  Fixed wrong indentation
  Bot fixes
  refer to the VarDumper component for dump()
  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
  ...

Author: weaverryan

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'])) {

book/security.rst

@@ -1546,9 +1546,6 @@ do the following:
             ),
         ));
 
-.. versionadded:: 2.2
-    The BCrypt encoder was introduced in Symfony 2.2.
-
 You can now calculate the hashed password either programmatically
 (e.g. ``password_hash('ryanpass', PASSWORD_BCRYPT, array('cost' => 12));``)
 or via some online tool.

book/templating.rst

@@ -1487,12 +1487,33 @@ in a JavaScript string, use the ``js`` context:
 Debugging
 ---------
 
-When using PHP, you can use :phpfunction:`var_dump` if you need to quickly find
-the value of a variable passed. This is useful, for example, inside your
-controller. The same can be achieved when using Twig thanks to the Debug
-extension.
+When using PHP, you can use the
+:ref:`dump() function from the VarDumper component <components-var-dumper-dump>`
+if you need to quickly find the value of a variable passed. This is useful,
+for example, inside your controller::
 
-Template parameters can then be dumped using the ``dump`` function:
+    // src/AppBundle/Controller/ArticleController.php
+    namespace AppBundle\Controller;
+
+    // ...
+
+    class ArticleController extends Controller
+    {
+        public function recentListAction()
+        {
+            $articles = ...;
+            dump($articles);
+
+            // ...
+        }
+    }
+
+.. note::
+
+    The output of the ``dump()`` function is then rendered in the web developer
+    toolbar.
+
+The same mechanism can be used in Twig templates thanks to ``dump`` function:
 
 .. code-block:: html+jinja
 

components/filesystem/introduction.rst

@@ -6,11 +6,6 @@ The Filesystem Component
 
     The Filesystem component provides basic utilities for the filesystem.
 
-.. versionadded:: 2.1
-    The Filesystem component was introduced in Symfony 2.1. Previously, the
-    ``Filesystem`` class was located in the HttpKernel component.
-
-
 .. tip::
 
     A lock handler feature was introduce in symfony 2.6.

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

components/var_dumper/introduction.rst

@@ -20,6 +20,8 @@ You can install the component in 2 different ways:
 * :doc:`Install it via Composer </components/using_components>` (``symfony/var-dumper`` on `Packagist`_);
 * Use the official Git repository (https://github.com/symfony/var-dumper).
 
+.. _components-var-dumper-dump:
+
 The dump() Function
 -------------------
 

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
@@ -93,9 +101,18 @@ rendering a form. In other words, if you want to customize one portion of
 how a form is rendered, you'll import a *theme* which contains a customization
 of the appropriate form fragments.
 
-Symfony comes with a default theme (`form_div_layout.html.twig`_ in Twig and
-``FrameworkBundle:Form`` in PHP) that defines each and every fragment needed
-to render every part of a form.
+Symfony comes with four **built-in form themes** that define each and every
+fragment needed to render every part of a form:
+
+* `form_div_layout.html.twig`_, wraps each form field inside a ``<div>`` element.
+* `form_table_layout.html.twig`_, wraps the entire form inside a ``<table>``
+  element and each form field inside a ``<tr>`` element.
+* `bootstrap_3_layout.html.twig`_, wraps each form field inside a ``<div>`` element
+  with the appropriate CSS classes to apply the default `Bootstrap 3 CSS framework`_
+  styles.
+* `bootstrap_3_horizontal_layout.html.twig`_, it's similar to the previous theme,
+  but the CSS classes applied are the ones used to display the forms horizontally
+  (i.e. the label and the widget in the same row).
 
 In the next section you will learn how to customize a theme by overriding
 some or all of its fragments.
@@ -1059,3 +1076,7 @@ The array passed as the second argument contains form "variables". For
 more details about this concept in Twig, see :ref:`twig-reference-form-variables`.
 
 .. _`form_div_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_div_layout.html.twig
+.. _`form_table_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/form_table_layout.html.twig
+.. _`bootstrap_3_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_layout.html.twig
+.. _`bootstrap_3_horizontal_layout.html.twig`: https://github.com/symfony/symfony/blob/master/src/Symfony/Bridge/Twig/Resources/views/Form/bootstrap_3_horizontal_layout.html.twig
+.. _`Bootstrap 3 CSS framework`: http://getbootstrap.com/

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/entity_provider.rst

@@ -877,7 +877,3 @@ then instead of these properties being checked, your ``isEqualTo`` method
 is simply called, and you can check whatever properties you want. Unless
 you understand this, you probably *won't* need to implement this interface
 or worry about it.
-
-.. versionadded:: 2.1
-    In Symfony 2.1, the ``equals`` method was removed from ``UserInterface``
-    and the ``EquatableInterface`` was introduced in its place.

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::