Merge branch '2.3' into 2.5

* 2.3:
  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
  Changed userName to username
  Update slash_in_parameter.rst
  Applied suggestion by Ryan
  Update form_customization.rst
  Merging emphasized notes
  Adder and remover sidenote

Conflicts:
	reference/twig_reference.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(https://github.com/%3C/span%3E$_SERVER['REQUEST_URI']%3Cspan%20class=%22x%20x-first%20x-last%22%3E,%20PHP_URL_PATH);
     if ('/index.php' == $uri) {
         list_action();
     } elseif ('/index.php/show' == $uri && isset($_GET['id'])) {

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

reference/configuration/doctrine.rst

@@ -5,7 +5,7 @@
 DoctrineBundle Configuration ("doctrine")
 =========================================
 
-Full default configuration
+Full Default Configuration
 --------------------------
 
 .. configuration-block::
@@ -180,8 +180,10 @@ Full default configuration
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                                http://symfony.com/schema/dic/doctrine http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/doctrine
+                http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
 
             <doctrine:config>
                 <doctrine:dbal default-connection="default">
@@ -209,16 +211,44 @@ Full default configuration
                     <doctrine:type name="custom">Acme\HelloBundle\MyCustomType</doctrine:type>
                 </doctrine:dbal>
 
-                <doctrine:orm default-entity-manager="default" auto-generate-proxy-classes="false" proxy-namespace="Proxies" proxy-dir="%kernel.cache_dir%/doctrine/orm/Proxies">
-                    <doctrine:entity-manager name="default" query-cache-driver="array" result-cache-driver="array" connection="conn1" class-metadata-factory-name="Doctrine\ORM\Mapping\ClassMetadataFactory">
-                        <doctrine:metadata-cache-driver type="memcache" host="localhost" port="11211" instance-class="Memcache" class="Doctrine\Common\Cache\MemcacheCache" />
+                <doctrine:orm
+                    default-entity-manager="default"
+                    auto-generate-proxy-classes="false"
+                    proxy-namespace="Proxies"
+                    proxy-dir="%kernel.cache_dir%/doctrine/orm/Proxies"
+                >
+                    <doctrine:entity-manager
+                        name="default"
+                        query-cache-driver="array"
+                        result-cache-driver="array"
+                        connection="conn1"
+                        class-metadata-factory-name="Doctrine\ORM\Mapping\ClassMetadataFactory"
+                    >
+                        <doctrine:metadata-cache-driver
+                            type="memcache"
+                            host="localhost"
+                            port="11211"
+                            instance-class="Memcache"
+                            class="Doctrine\Common\Cache\MemcacheCache"
+                        />
+
                         <doctrine:mapping name="AcmeHelloBundle" />
+
                         <doctrine:dql>
-                            <doctrine:string-function name="test_string">Acme\HelloBundle\DQL\StringFunction</doctrine:string-function>
-                            <doctrine:numeric-function name="test_numeric">Acme\HelloBundle\DQL\NumericFunction</doctrine:numeric-function>
-                            <doctrine:datetime-function name="test_datetime">Acme\HelloBundle\DQL\DatetimeFunction</doctrine:datetime-function>
+                            <doctrine:string-function name="test_string">
+                                Acme\HelloBundle\DQL\StringFunction
+                            </doctrine:string-function>
+
+                            <doctrine:numeric-function name="test_numeric">
+                                Acme\HelloBundle\DQL\NumericFunction
+                            </doctrine:numeric-function>
+
+                            <doctrine:datetime-function name="test_datetime">
+                                Acme\HelloBundle\DQL\DatetimeFunction
+                            </doctrine:datetime-function>
                         </doctrine:dql>
                     </doctrine:entity-manager>
+
                     <doctrine:entity-manager name="em2" connection="conn2" metadata-cache-driver="apc">
                         <doctrine:mapping
                             name="DoctrineExtensions"
@@ -235,8 +265,8 @@ Full default configuration
 Configuration Overview
 ----------------------
 
-This following configuration example shows all the configuration defaults that
-the ORM resolves to:
+This following configuration example shows all the configuration defaults
+that the ORM resolves to:
 
 .. code-block:: yaml
 
@@ -258,8 +288,8 @@ certain classes, but those are for very advanced use-cases only.
 Caching Drivers
 ~~~~~~~~~~~~~~~
 
-For the caching drivers you can specify the values "array", "apc", "memcache", "memcached",
-"xcache" or "service".
+For the caching drivers you can specify the values "array", "apc", "memcache",
+"memcached", "xcache" or "service".
 
 The following example shows an overview of the caching configurations:
 
@@ -282,34 +312,34 @@ Mapping Configuration
 ~~~~~~~~~~~~~~~~~~~~~
 
 Explicit definition of all the mapped entities is the only necessary
-configuration for the ORM and there are several configuration options that you
-can control. The following configuration options exist for a mapping:
+configuration for the ORM and there are several configuration options that
+you can control. The following configuration options exist for a mapping:
 
 * ``type`` One of ``annotation``, ``xml``, ``yml``, ``php`` or ``staticphp``.
   This specifies which type of metadata type your mapping uses.
 
-* ``dir`` Path to the mapping or entity files (depending on the driver). If
-  this path is relative it is assumed to be relative to the bundle root. This
-  only works if the name of your mapping is a bundle name. If you want to use
-  this option to specify absolute paths you should prefix the path with the
-  kernel parameters that exist in the DIC (for example %kernel.root_dir%).
+* ``dir`` Path to the mapping or entity files (depending on the driver).
+  If this path is relative it is assumed to be relative to the bundle root.
+  This only works if the name of your mapping is a bundle name. If you want
+  to use this option to specify absolute paths you should prefix the path
+  with the kernel parameters that exist in the DIC (for example ``%kernel.root_dir%``).
 
 * ``prefix`` A common namespace prefix that all entities of this mapping
   share. This prefix should never conflict with prefixes of other defined
-  mappings otherwise some of your entities cannot be found by Doctrine. This
-  option defaults to the bundle namespace + ``Entity``, for example for an
-  application bundle called ``AcmeHelloBundle`` prefix would be
+  mappings otherwise some of your entities cannot be found by Doctrine.
+  This option defaults to the bundle namespace + ``Entity``, for example
+  for an application bundle called ``AcmeHelloBundle`` prefix would be
   ``Acme\HelloBundle\Entity``.
 
 * ``alias`` Doctrine offers a way to alias entity namespaces to simpler,
-  shorter names to be used in DQL queries or for Repository access. When using
-  a bundle the alias defaults to the bundle name.
+  shorter names to be used in DQL queries or for Repository access. When
+  using a bundle the alias defaults to the bundle name.
 
-* ``is_bundle`` This option is a derived value from ``dir`` and by default is
-  set to true if dir is relative proved by a ``file_exists()`` check that
-  returns false. It is false if the existence check returns true. In this case
-  an absolute path was specified and the metadata files are most likely in a
-  directory outside of a bundle.
+* ``is_bundle`` This option is a derived value from ``dir`` and by default
+  is set to true if dir is relative proved by a ``file_exists()`` check
+  that returns false. It is false if the existence check returns true. In
+  this case an absolute path was specified and the metadata files are most
+  likely in a directory outside of a bundle.
 
 .. index::
     single: Configuration; Doctrine DBAL
@@ -363,8 +393,11 @@ The following block shows all possible configuration keys:
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xmlns:doctrine="http://symfony.com/schema/dic/doctrine"
-            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd
-                http://symfony.com/schema/dic/doctrine http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd">
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/doctrine
+                http://symfony.com/schema/dic/doctrine/doctrine-1.0.xsd"
+        >
 
             <doctrine:config>
                 <doctrine:dbal