Merge branch '3.0' into 3.1

Author: wouterj

best_practices/business-logic.rst

@@ -151,7 +151,7 @@ the class namespace as a parameter:
         app.slugger:
             class: '%slugger.class%'
 
-This practice is cumbersome and completely unnecessary for your own services:
+This practice is cumbersome and completely unnecessary for your own services.
 
 .. best-practice::
 

book/forms.rst

@@ -992,7 +992,7 @@ In :ref:`book-form-creating-form-classes` you will learn how to move the
 form building code into separate classes. When using an external form class
 in the controller, you can pass the action and method as form options::
 
-    use AppBundle\Form\Type\TaskType;
+    use AppBundle\Form\TaskType;
     // ...
 
     $form = $this->createForm(TaskType::class, $task, array(
@@ -1040,8 +1040,8 @@ However, a better practice is to build the form in a separate, standalone PHP
 class, which can then be reused anywhere in your application. Create a new class
 that will house the logic for building the task form::
 
-    // src/AppBundle/Form/Type/TaskType.php
-    namespace AppBundle\Form\Type;
+    // src/AppBundle/Form/TaskType.php
+    namespace AppBundle\Form;
 
     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\FormBuilderInterface;
@@ -1063,7 +1063,7 @@ This new class contains all the directions needed to create the task form. It ca
 be used to quickly build a form object in the controller::
 
     // src/AppBundle/Controller/DefaultController.php
-    use AppBundle\Form\Type\TaskType;
+    use AppBundle\Form\TaskType;
 
     public function newAction()
     {
@@ -1184,7 +1184,7 @@ Define your form type as a service.
         # src/AppBundle/Resources/config/services.yml
         services:
             app.form.type.task:
-                class: AppBundle\Form\Type\TaskType
+                class: AppBundle\Form\TaskType
                 arguments: ["@app.my_service"]
                 tags:
                     - { name: form.type }
@@ -1198,7 +1198,7 @@ Define your form type as a service.
             xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
-                <service id="app.form.type.task" class="AppBundle\Form\Type\TaskType">
+                <service id="app.form.type.task" class="AppBundle\Form\TaskType">
                     <tag name="form.type" />
                     <argument type="service" id="app.my_service"></argument>
                 </service>
@@ -1210,7 +1210,7 @@ Define your form type as a service.
         // src/AppBundle/Resources/config/services.php
         use Symfony\Component\DependencyInjection\Reference;
 
-        $container->register('app.form.type.task', 'AppBundle\Form\Type\TaskType')
+        $container->register('app.form.type.task', 'AppBundle\Form\TaskType')
             ->addArgument(new Reference('app.my_service'))
             ->addTag('form.type')
 
@@ -1318,8 +1318,8 @@ Next, add a new ``category`` property to the ``Task`` class::
 Now that your application has been updated to reflect the new requirements,
 create a form class so that a ``Category`` object can be modified by the user::
 
-    // src/AppBundle/Form/Type/CategoryType.php
-    namespace AppBundle\Form\Type;
+    // src/AppBundle/Form/CategoryType.php
+    namespace AppBundle\Form;
 
     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\FormBuilderInterface;
@@ -1343,12 +1343,10 @@ create a form class so that a ``Category`` object can be modified by the user::
 The end goal is to allow the ``Category`` of a ``Task`` to be modified right
 inside the task form itself. To accomplish this, add a ``category`` field
 to the ``TaskType`` object whose type is an instance of the new ``CategoryType``
-class:
-
-.. code-block:: php
+class::
 
     use Symfony\Component\Form\FormBuilderInterface;
-    use AppBundle\Form\Type\CategoryType;
+    use AppBundle\Form\CategoryType;
 
     public function buildForm(FormBuilderInterface $builder, array $options)
     {

book/from_flat_php_to_symfony2.rst

@@ -123,9 +123,9 @@ is primarily an HTML file that uses a template-like PHP syntax:
     </html>
 
 By convention, the file that contains all the application logic - ``index.php`` -
-is known as a "controller". The term :term:`controller` is a word you'll hear
-a lot, regardless of the language or framework you use. It refers simply
-to the area of *your* code that processes user input and prepares the response.
+is known as a "controller". The term controller is a word you'll hear a lot,
+regardless of the language or framework you use. It refers simply to the area
+of *your* code that processes user input and prepares the response.
 
 In this case, the controller prepares data from the database and then includes
 a template to present that data. With the controller isolated, you could
@@ -312,8 +312,8 @@ to security...
 A "Front Controller" to the Rescue
 ----------------------------------
 
-The solution is to use a :term:`front controller`: a single PHP file through
-which *all* requests are processed. With a front controller, the URIs for the
+The solution is to use a front controller: a single PHP file through which
+*all* requests are processed. With a front controller, the URIs for the
 application change slightly, but start to become more flexible:
 
 .. code-block:: text

book/http_cache.rst

@@ -26,11 +26,11 @@ websites, or is it? In this chapter, you'll see how the Symfony cache
 system works and why this is the best possible approach.
 
 The Symfony cache system is different because it relies on the simplicity
-and power of the HTTP cache as defined in the :term:`HTTP specification`.
-Instead of reinventing a caching methodology, Symfony embraces the standard
-that defines basic communication on the Web. Once you understand the fundamental
-HTTP validation and expiration caching models, you'll be ready to master
-the Symfony cache system.
+and power of the HTTP cache as defined in the `HTTP specification`_. Instead of
+reinventing a caching methodology, Symfony embraces the standard that defines
+basic communication on the Web. Once you understand the fundamental HTTP
+validation and expiration caching models, you'll be ready to master the Symfony
+cache system.
 
 For the purposes of learning how to cache with Symfony, the
 subject is covered in four steps:
@@ -1251,3 +1251,4 @@ Learn more from the Cookbook
 .. _`FrameworkExtraBundle documentation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/cache.html
 .. _`ESI`: http://www.w3.org/TR/esi-lang
 .. _`FOSHttpCacheBundle`: http://foshttpcachebundle.readthedocs.org/
+.. _`HTTP specification`: http://www.w3.org/Protocols/rfc2616/rfc2616.html

book/http_fundamentals.rst

@@ -334,8 +334,8 @@ breaking all of your links?) and the fact that each file *must* manually
 include some set of core files so that security, database connections and
 the "look" of the site can remain consistent.
 
-A much better solution is to use a :term:`front controller`: a single PHP
-file that handles every request coming into your application. For example:
+A much better solution is to use a front controller: a single PHP file that
+handles every request coming into your application. For example:
 
 +------------------------+------------------------+
 | ``/index.php``         | executes ``index.php`` |
@@ -401,8 +401,8 @@ the same simple pattern for every request:
 
 Each "page" of your site is defined in a routing configuration file that
 maps different URLs to different PHP functions. The job of each PHP function,
-called a :term:`controller`, is to use information from the request - along
-with many other tools Symfony makes available - to create and return a ``Response``
+called a controller, is to use information from the request - along with many
+other tools Symfony makes available - to create and return a ``Response``
 object. In other words, the controller is where *your* code goes: it's where
 you interpret the request and create a response.
 

book/routing.rst

@@ -1550,6 +1550,30 @@ a template helper function:
             Read this blog post.
         </a>
 
+.. tip::
+
+    If you are generating the route inside a ``<script>`` element, it's a good
+    practice to escape it for JavaScript:
+
+    .. configuration-block::
+
+        .. code-block:: html+twig
+
+            <script>
+            var route = "{{ path('blog_show', {'slug': 'my-blog-post'})|escape('js') }}";
+            </script>
+
+        .. code-block:: html+php
+        
+            <script>
+            var route = "<?php echo $view->escape(
+                $view['router']->path('blow_show', array(
+                    'slug' => 'my-blog-post',
+                )),
+                'js'
+            ) ?>";
+            </script>
+
 .. index::
    single: Routing; Absolute URLs
 

book/service_container.rst

@@ -39,13 +39,13 @@ the service container makes writing good code so easy.
 What is a Service?
 ------------------
 
-Put simply, a :term:`Service` is any PHP object that performs some sort of
-"global" task. It's a purposefully-generic name used in computer science
-to describe an object that's created for a specific purpose (e.g. delivering
-emails). Each service is used throughout your application whenever you need
-the specific functionality it provides. You don't have to do anything special
-to make a service: simply write a PHP class with some code that accomplishes
-a specific task. Congratulations, you've just created a service!
+Put simply, a service is any PHP object that performs some sort of "global"
+task. It's a purposefully-generic name used in computer science to describe an
+object that's created for a specific purpose (e.g. delivering emails). Each
+service is used throughout your application whenever you need the specific
+functionality it provides. You don't have to do anything special to make a
+service: simply write a PHP class with some code that accomplishes a specific
+task. Congratulations, you've just created a service!
 
 .. note::
 
@@ -72,8 +72,8 @@ are key to being a good developer in almost any language.
 What is a Service Container?
 ----------------------------
 
-A :term:`Service Container` (or *dependency injection container*) is simply
-a PHP object that manages the instantiation of services (i.e. objects).
+A service container (or *dependency injection container*) is simply a PHP
+object that manages the instantiation of services (i.e. objects).
 
 For example, suppose you have a simple PHP class that delivers email messages.
 Without a service container, you must manually create the object whenever

book/translation.rst

@@ -51,9 +51,9 @@ to learn even more. Overall, the process has several steps:
 Configuration
 -------------
 
-Translations are handled by a ``translator`` :term:`service` that uses the
-user's locale to lookup and return translated messages. Before using it,
-enable the ``translator`` in your configuration:
+Translations are handled by a ``translator`` service that uses the user's
+locale to lookup and return translated messages. Before using it, enable the
+``translator`` in your configuration:
 
 .. configuration-block::
 

components/form/introduction.rst

@@ -359,10 +359,12 @@ and then access it whenever you need to build a form.
     this object in some more "global" way so you can access it from anywhere.
 
 Exactly how you gain access to your one form factory is up to you. If you're
-using a :term:`Service Container`, then you should add the form factory to
-your container and grab it out whenever you need to. If your application
-uses global or static variables (not usually a good idea), then you can store
-the object on some static class or do something similar.
+using a service container (like provided with the
+:doc:`DependencyInjection component </components/dependency_injection/introduction>`),
+then you should add the form factory to your container and grab it out whenever
+you need to. If your application uses global or static variables (not usually a
+good idea), then you can store the object on some static class or do something
+similar.
 
 Regardless of how you architect your application, just remember that you
 should only have one form factory and that you'll need to be able to access

cookbook/email/email.rst

@@ -72,19 +72,19 @@ can modify the values in that file, or set the values directly here.
 
 The following configuration attributes are available:
 
-* ``transport``         (``smtp``, ``mail``, ``sendmail``, or ``gmail``)
+* ``transport`` (``smtp``, ``mail``, ``sendmail``, or ``gmail``)
 * ``username``
 * ``password``
 * ``host``
 * ``port``
-* ``encryption``        (``tls``, or ``ssl``)
-* ``auth_mode``         (``plain``, ``login``, or ``cram-md5``)
+* ``encryption`` (``tls``, or ``ssl``)
+* ``auth_mode`` (``plain``, ``login``, or ``cram-md5``)
 * ``spool``
 
   * ``type`` (how to queue the messages, ``file`` or ``memory`` is supported, see :doc:`/cookbook/email/spool`)
   * ``path`` (where to store the messages)
-* ``delivery_address``  (an email address where to send ALL emails)
-* ``disable_delivery``  (set to true to disable delivery completely)
+* ``delivery_address`` (an email address where to send ALL emails)
+* ``disable_delivery`` (set to true to disable delivery completely)
 
 Sending Emails
 --------------
@@ -133,6 +133,8 @@ template might look something like this:
     {# app/Resources/views/Emails/registration.html.twig #}
     <h3>You did it! You registered!</h3>
 
+    Hi {{ name }}! You're successfully registered.
+
     {# example, assuming you have a route named "login" #}
     To login, go to: <a href="{{ url('login') }}">...</a>.