Merge branch '2.3' into 2.7

* 2.3:
  [#6219] some tweaks
  Point that route parameters are also Request attributes
  [#6348] some minor tweaks
  [best practices] mostly typos
  [#6275] some minor tweaks
  [quick tour] mostly typos
  remove link-local IPv6 address (fe80::1)
  [#6305] move link reference to the bottom
  Mention IvoryCKEditorBundle in the Symfony Forms doc
  [#6328] minor tweak
  Update extension.rst - added caution box for people trying to remove the default file with services definitions
  Altered single / multiple inheritance sentence
  Replace XLIFF number ids by strings

Author: xabbuh

best_practices/business-logic.rst

@@ -193,7 +193,7 @@ The three entities defined by our sample blog application are a good example:
 Doctrine Mapping Information
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Doctrine Entities are plain PHP objects that you store in some "database".
+Doctrine entities are plain PHP objects that you store in some "database".
 Doctrine only knows about your entities through the mapping metadata configured
 for your model classes. Doctrine supports four metadata formats: YAML, XML,
 PHP and annotations.

best_practices/configuration.rst

@@ -107,9 +107,7 @@ If you've done something like this in the past, it's likely that you've in fact
 *never* actually needed to change that value. Creating a configuration
 option for a value that you are never going to configure just isn't necessary.
 Our recommendation is to define these values as constants in your application.
-You could, for example, define a ``NUM_ITEMS`` constant in the ``Post`` entity:
-
-.. code-block:: php
+You could, for example, define a ``NUM_ITEMS`` constant in the ``Post`` entity::
 
     // src/AppBundle/Entity/Post.php
     namespace AppBundle\Entity;

best_practices/controllers.rst

@@ -73,7 +73,7 @@ Template Configuration
 
 .. best-practice::
 
-    Don't use the ``@Template()`` annotation to configure the template used by
+    Don't use the ``@Template`` annotation to configure the template used by
     the controller.
 
 The ``@Template`` annotation is useful, but also involves some magic. We
@@ -148,7 +148,7 @@ For example:
         ));
     }
 
-Normally, you'd expect a ``$id`` argument to ``showAction``. Instead, by
+Normally, you'd expect a ``$id`` argument to ``showAction()``. Instead, by
 creating a new argument (``$post``) and type-hinting it with the ``Post``
 class (which is a Doctrine entity), the ParamConverter automatically queries
 for an object whose ``$id`` property matches the ``{id}`` value. It will

best_practices/creating-the-project.rst

@@ -104,7 +104,7 @@ ProductBundle, then there's no advantage to having two separate bundles.
 
 .. best-practice::
 
-    Create only one bundle called AppBundle for your application logic
+    Create only one bundle called AppBundle for your application logic.
 
 Implementing a single AppBundle bundle in your projects will make your code
 more concise and easier to understand. Starting in Symfony 2.6, the official
@@ -179,8 +179,6 @@ The changes are pretty superficial, but for now, we recommend that you use
 the Symfony directory structure.
 
 .. _`Composer`: https://getcomposer.org/
-.. _`Get Started`: https://getcomposer.org/doc/00-intro.md
-.. _`Composer download page`: https://getcomposer.org/download/
-.. _`public checksums repository`: https://github.com/sensiolabs/checksums
-.. _`these steps`: http://fabien.potencier.org/signing-project-releases.html
 .. _`Phar extension`: http://php.net/manual/en/intro.phar.php
+.. _`public checksums repository`: https://github.com/sensiolabs/checksums
+.. _`these steps`: http://fabien.potencier.org/signing-project-releases.html

best_practices/forms.rst

@@ -54,7 +54,7 @@ form in its own PHP class::
     Put the form type classes in the ``AppBundle\Form`` namespace, unless you
     use other custom form classes like data transformers.
 
-To use the class, use ``createForm`` and instantiate the new class::
+To use the class, use ``createForm()`` and instantiate the new class::
 
     // ...
     use AppBundle\Form\PostType;
@@ -160,8 +160,8 @@ thing in one line to rendering each part of each field independently. The
 best way depends on how much customization you need.
 
 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:
+is to render the form tags and use the ``form_widget()`` function to render
+all of the fields:
 
 .. code-block:: html+twig
 
@@ -171,7 +171,7 @@ fields:
 
 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.
-See the :doc:`/cookbook/form/form_customization` article for more information
+See the :doc:`/cookbook/form/form_customization` cookbook article for more information
 on this and how you can control *how* the form renders at a global level
 using form theming.
 
@@ -204,9 +204,9 @@ Handling a form submit usually follows a similar template:
 
 There are really only two notable things here. First, we recommend that you
 use a single action for both rendering the form and handling the form submit.
-For example, you *could* have a ``newAction`` that *only* renders the form
-and a ``createAction`` that *only* processes the form submit. Both those
-actions will be almost identical. So it's much simpler to let ``newAction``
+For example, you *could* have a ``newAction()`` that *only* renders the form
+and a ``createAction()`` that *only* processes the form submit. Both those
+actions will be almost identical. So it's much simpler to let ``newAction()``
 handle everything.
 
 Second, we recommend using ``$form->isSubmitted()`` in the ``if`` statement

best_practices/i18n.rst

@@ -47,15 +47,15 @@ Translation Source File Location
 
 .. best-practice::
 
-    Store the translation files in the ``app/Resources/translations/`` directory.
+    Store the translation files in the ``app/Resources/translations/``
+    directory.
 
 Traditionally, Symfony developers have created these files in the
-``Resources/translations/`` directory of each bundle.
-
-But since the ``app/Resources/`` directory is considered the global location
-for the application's resources, storing translations in ``app/Resources/translations/``
+``Resources/translations/`` directory of each bundle. But since the
+``app/Resources/`` directory is considered the global location for the
+application's resources, storing translations in ``app/Resources/translations/``
 centralizes them *and* gives them priority over any other translation file.
-This lets you override translations defined in third-party bundles.
+This let's you override translations defined in third-party bundles.
 
 Translation Keys
 ----------------
@@ -85,7 +85,7 @@ English in the application would be:
     <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
         <file source-language="en" target-language="en" datatype="plaintext" original="file.ext">
             <body>
-                <trans-unit id="1">
+                <trans-unit id="title_post_list">
                     <source>title.post_list</source>
                     <target>Post List</target>
                 </trans-unit>

best_practices/tests.rst

@@ -26,9 +26,7 @@ functional tests, you can quickly spot any big errors before you deploy them:
     Define a functional test that at least checks if your application pages
     are successfully loading.
 
-A functional test can be as easy as this:
-
-.. code-block:: php
+A functional test can be as easy as this::
 
     // src/AppBundle/Tests/ApplicationAvailabilityFunctionalTest.php
     namespace AppBundle\Tests;
@@ -116,10 +114,10 @@ Learn More about Functional Tests
 Consider using the `HautelookAliceBundle`_ to generate real-looking data for
 your test fixtures using `Faker`_ and `Alice`_.
 
-.. _`Faker`: https://github.com/fzaninotto/Faker
-.. _`Alice`: https://github.com/nelmio/alice
 .. _`PhpUnit`: https://phpunit.de/
 .. _`PhpSpec`: http://www.phpspec.net/
-.. _`Mink`: http://mink.behat.org
 .. _`smoke testing`: https://en.wikipedia.org/wiki/Smoke_testing_(software)
+.. _`Mink`: http://mink.behat.org
 .. _`HautelookAliceBundle`: https://github.com/hautelook/AliceBundle
+.. _`Faker`: https://github.com/fzaninotto/Faker
+.. _`Alice`: https://github.com/nelmio/alice

book/translation.rst

@@ -134,7 +134,7 @@ different formats, XLIFF being the recommended format:
         <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
             <file source-language="en" datatype="plaintext" original="file.ext">
                 <body>
-                    <trans-unit id="1">
+                    <trans-unit id="symfony_is_great">
                         <source>Symfony is great</source>
                         <target>J'aime Symfony</target>
                     </trans-unit>
@@ -671,7 +671,7 @@ bundle.
         <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
             <file source-language="en" datatype="plaintext" original="file.ext">
                 <body>
-                    <trans-unit id="1">
+                    <trans-unit id="author.name.not_blank">
                         <source>author.name.not_blank</source>
                         <target>Please enter an author name.</target>
                     </trans-unit>

components/event_dispatcher/introduction.rst

@@ -22,8 +22,8 @@ answer.
 Consider the real-world example where you want to provide a plugin system
 for your project. A plugin should be able to add methods, or do something
 before or after a method is executed, without interfering with other plugins.
-This is not an easy problem to solve with single and multiple inheritance
-(were it possible with PHP) has its own drawbacks.
+This is not an easy problem to solve with single inheritance, and even if 
+multiple inheritance was possible with PHP, it comes with its own drawbacks.
 
 The Symfony EventDispatcher component implements the `Mediator`_ pattern
 in a simple and effective way to make all these things possible and to make

components/translation/usage.rst

@@ -115,11 +115,11 @@ recommended format. These files are parsed by one of the loader classes.
         <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
             <file source-language="en" datatype="plaintext" original="file.ext">
                 <body>
-                    <trans-unit id="1">
+                    <trans-unit id="symfony_is_great">
                         <source>Symfony is great</source>
                         <target>J'aime Symfony</target>
                     </trans-unit>
-                    <trans-unit id="2">
+                    <trans-unit id="symfony.great">
                         <source>symfony.great</source>
                         <target>J'aime Symfony</target>
                     </trans-unit>

cookbook/bundles/extension.rst

@@ -113,6 +113,12 @@ Other available loaders are the ``YamlFileLoader``, ``PhpFileLoader`` and
     The ``IniFileLoader`` can only be used to load parameters and it can only
     load them as strings.
 
+.. caution::
+
+    If you removed the default file with service definitions (i.e.
+    ``app/config/services.yml``), make sure to also remove it from the
+    ``imports`` key in ``app/config/config.yml``.
+
 Using Configuration to Change the Services
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

cookbook/configuration/environments.rst

@@ -328,7 +328,7 @@ The new environment is now accessible via::
     aren't accessible, the front controller is usually protected from external
     IP addresses via the following code at the top of the controller::
 
-        if (!in_array(@$_SERVER['REMOTE_ADDR'], array('127.0.0.1', 'fe80::1', '::1'))) {
+        if (!in_array(@$_SERVER['REMOTE_ADDR'], array('127.0.0.1', '::1'))) {
             die('You are not allowed to access this file. Check '.basename(__FILE__).' for more information.');
         }
 

cookbook/routing/extra_information.rst

@@ -4,10 +4,10 @@
 How to Pass Extra Information from a Route to a Controller
 ==========================================================
 
-Parameters inside the ``defaults`` collection don't necessarily have to
-match a placeholder in the route ``path``. In fact, you can use the
-``defaults`` array to specify extra parameters that will then be accessible as
-arguments to your controller:
+Parameters inside the ``defaults`` collection don't necessarily have to match
+a placeholder in the route ``path``. In fact, you can use the ``defaults``
+array to specify extra parameters that will then be accessible as arguments
+to your controller, and as attributes of the ``Request`` object:
 
 .. configuration-block::
 
@@ -52,12 +52,25 @@ arguments to your controller:
 
         return $collection;
 
-Now, you can access this extra parameter in your controller::
+Now, you can access this extra parameter in your controller, as an argument
+to the controller method::
 
     public function indexAction($page, $title)
     {
         // ...
     }
 
-As you can see, the ``$title`` variable was never defined inside the route path,
-but you can still access its value from inside your controller.
+Alternatively, the title could be accessed through the ``Request`` object::
+
+    use Symfony\Component\HttpFoundation\Request;
+    
+    public function indexAction(Request $request, $page)
+    {
+        $title = $request->attributes->get('title');
+
+        // ...
+    }
+
+As you can see, the ``$title`` variable was never defined inside the route
+path, but you can still access its value from inside your controller, through
+the method's argument, or from the ``Request`` object's ``attributes`` bag.

cookbook/security/access_control.rst

@@ -178,7 +178,7 @@ pattern so that it is only accessible by requests from the local server itself:
             # ...
             access_control:
                 #
-                - { path: ^/internal, roles: IS_AUTHENTICATED_ANONYMOUSLY, ips: [127.0.0.1, fe80::1, ::1] }
+                - { path: ^/internal, roles: IS_AUTHENTICATED_ANONYMOUSLY, ips: [127.0.0.1, ::1] }
                 - { path: ^/internal, roles: ROLE_NO_ACCESS }
 
     .. code-block:: xml
@@ -195,7 +195,7 @@ pattern so that it is only accessible by requests from the local server itself:
                 <!-- ... -->
                 <rule path="^/internal"
                     role="IS_AUTHENTICATED_ANONYMOUSLY"
-                    ips="127.0.0.1, fe80::1, ::1"
+                    ips="127.0.0.1, ::1"
                 />
 
                 <rule path="^/internal" role="ROLE_NO_ACCESS" />
@@ -211,7 +211,7 @@ pattern so that it is only accessible by requests from the local server itself:
                 array(
                     'path' => '^/internal',
                     'role' => 'IS_AUTHENTICATED_ANONYMOUSLY',
-                    'ips' => '127.0.0.1, fe80::1, ::1'
+                    'ips' => '127.0.0.1, ::1'
                 ),
                 array(
                     'path' => '^/internal',
@@ -232,8 +232,8 @@ the external IP address ``10.0.0.1``:
   that does not match an existing role, it just serves as a trick to always
   deny access).
 
-But if the same request comes from ``127.0.0.1``, ``::1`` (the IPv6 loopback
-address) or ``fe80::1`` (the IPv6 link-local address):
+But if the same request comes from ``127.0.0.1`` or ``::1`` (the IPv6 loopback
+address):
 
 * Now, the first access control rule is enabled as both the ``path`` and the
   ``ip`` match: access is allowed as the user always has the

quick_tour/the_architecture.rst

@@ -257,7 +257,7 @@ Understanding the Cache and Logs
 --------------------------------
 
 Symfony applications can contain several configuration files defined in
-several formats (YAML, XML, PHP, etc.) Instead of parsing and combining
+several formats (YAML, XML, PHP, etc.). Instead of parsing and combining
 all those files for each request, Symfony uses its own cache system. In
 fact, the application configuration is only parsed for the very first request
 and then compiled down to plain PHP code stored in the ``app/cache/``
@@ -309,4 +309,4 @@ need to learn a lot to become a Symfony master. Ready to dig into these
 topics now? Look no further - go to the official :doc:`/book/index` and
 pick any topic you want.
 
-.. _Composer:   https://getcomposer.org
+.. _`Composer`:   https://getcomposer.org

quick_tour/the_big_picture.rst

@@ -29,13 +29,17 @@ When developing a Symfony application, your responsibility as a developer
 is to write the code that maps the user's *request* (e.g. ``http://localhost:8000/``)
 to the *resource* associated with it (the ``Homepage`` HTML page).
 
-The code to execute is defined in **actions** and **controllers**. The mapping
-between user's requests and that code is defined via the **routing** configuration.
-And the contents displayed in the browser are usually rendered using **templates**.
+The code to execute is defined as methods of PHP classes. The methods are
+called **actions** and the classes **controllers**, but in practice most
+developers use **controllers** to refer to both of them. The mapping between
+user's requests and that code is defined via the **routing** configuration.
+And the contents displayed in the browser are usually rendered using
+**templates**.
+
+When you go to ``http://localhost:8000/app/example``, Symfony will execute
+the controller in ``src/AppBundle/Controller/DefaultController.php`` and
+render the ``app/Resources/views/default/index.html.twig`` template.
 
-When you browsed ``http://localhost:8000/app/example`` earlier, Symfony executed
-the controller defined in the ``src/AppBundle/Controller/DefaultController.php``
-file and rendered the ``app/Resources/views/default/index.html.twig`` template.
 In the following sections you'll learn in detail the inner workings of Symfony
 controllers, routes and templates.
 
@@ -69,7 +73,7 @@ is called ``Default`` and the PHP class is called ``DefaultController``.
 The methods defined in a controller are called **actions**, they are usually
 associated with one URL of the application and their names are suffixed
 with ``Action``. In this example, the ``Default`` controller has only one
-action called ``index`` and defined in the ``indexAction`` method.
+action called ``index`` and defined in the ``indexAction()`` method.
 
 Actions are usually very short - around 10-15 lines of code - because they
 just call other parts of the application to get or generate the needed
@@ -85,7 +89,7 @@ Routing
 Symfony routes each request to the action that handles it by matching the
 requested URL against the paths configured by the application. Open again
 the ``src/AppBundle/Controller/DefaultController.php`` file and take a look
-at the three lines of code above the ``indexAction`` method::
+at the three lines of code above the ``indexAction()`` method::
 
     // src/AppBundle/Controller/DefaultController.php
     namespace AppBundle\Controller;
@@ -138,7 +142,8 @@ The only content of the ``index`` action is this PHP instruction::
 
 The ``$this->render()`` method is a convenient shortcut to render a template.
 Symfony provides some useful shortcuts to any controller extending from
-the ``Controller`` class.
+the base Symfony :class:`Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller`
+class.
 
 By default, application templates are stored in the ``app/Resources/views/``
 directory. Therefore, the ``default/index.html.twig`` template corresponds
@@ -194,7 +199,7 @@ environments**.
 What is an Environment?
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-An :term:`Environment` represents a group of configurations that's used
+An :term:`environment` represents a group of configurations that's used
 to run your application. Symfony defines two environments by default: ``dev``
 (suited for when developing the application locally) and ``prod`` (optimized
 for when executing the application on production).
@@ -235,7 +240,7 @@ In this example, the ``config_dev.yml`` configuration file imports the common
 with its own options.
 
 For more details on environments, see
-":ref:`Environments & Front Controllers <page-creation-environments>`" article.
+:ref:`the "Environments" section <page-creation-environments>` of the book.
 
 Final Thoughts
 --------------
@@ -246,6 +251,4 @@ how Symfony makes it really easy to implement web sites better and faster.
 If you are eager to learn more about Symfony, dive into the next section:
 ":doc:`The View <the_view>`".
 
-.. _Composer: https://getcomposer.org/
-.. _executable installer: https://getcomposer.org/download
-.. _Twig: http://twig.sensiolabs.org/
+.. _`Twig`: http://twig.sensiolabs.org/