Merge branch '2.7' into 2.8

Conflicts:
	form/form_dependencies.rst
	templating.rst

Author: wouterj

best_practices/business-logic.rst

@@ -15,7 +15,7 @@ Inside here, you can create whatever directories you want to organize things:
 
 .. code-block:: text
 
-    symfony2-project/
+    symfony-project/
     ├─ app/
     ├─ src/
     │  └─ AppBundle/
@@ -33,7 +33,7 @@ and put things there:
 
 .. code-block:: text
 
-    symfony2-project/
+    symfony-project/
     ├─ app/
     ├─ src/
     │  ├─ Acme/
@@ -176,7 +176,7 @@ The three entities defined by our sample blog application are a good example:
 
 .. code-block:: text
 
-    symfony2-project/
+    symfony-project/
     ├─ ...
     └─ src/
        └─ AppBundle/

best_practices/controllers.rst

@@ -85,10 +85,10 @@ it more difficult to know which template is being rendered. It also makes
 it less obvious to beginners that a controller should always return a Response
 object (unless you're using a view layer).
 
-How the Controller Looks
-------------------------
+What does the Controller look like
+----------------------------------
 
-Considering all this, here is an example of how the controller should look
+Considering all this, here is an example of what the controller should look like
 for the homepage of our app:
 
 .. code-block:: php

components/expression_language.rst

@@ -21,7 +21,7 @@ How can the Expression Engine Help Me?
 --------------------------------------
 
 The purpose of the component is to allow users to use expressions inside
-configuration for more complex logic. For some examples, the Symfony2 Framework
+configuration for more complex logic. For some examples, the Symfony Framework
 uses expressions in security, for validation rules and in route matching.
 
 Besides using the component in the framework itself, the ExpressionLanguage

components/filesystem.rst

@@ -64,6 +64,10 @@ On POSIX filesystems, directories are created with a default mode value
     You can pass an array or any :phpclass:`Traversable` object as the first
     argument.
 
+.. note::
+
+    This function ignores already existing directories.
+
 exists
 ~~~~~~
 

components/yaml/yaml_format.rst

@@ -158,7 +158,7 @@ YAML uses the ISO-8601 standard to express dates:
 
 .. code-block:: yaml
 
-    2001-12-14t21:59:43.10-05:00
+    2001-12-14T21:59:43.10-05:00
 
 .. code-block:: yaml
 

configuration.rst

@@ -112,14 +112,14 @@ There are *two* ways to know *what* keys you can configure:
 
 #. Use the :doc:`Reference Section </reference/index>`;
 
-#. Use the ``config:dump`` command;
+#. Use the ``config:dump-reference`` command.
 
 For example, if you want to configure something in Twig, you can see an example
 dump of all available configuration options by running:
 
 .. code-block:: terminal
 
-    $ php app/console config:dump twig
+    $ php app/console config:dump-reference twig
 
 .. index::
    single: Environments; Introduction
@@ -183,7 +183,7 @@ can also load XML files or PHP files.
 
 .. _config-parameter-intro:
 
-The parameters key: Parameters (Variables)
+The parameters Key: Parameters (Variables)
 ------------------------------------------
 
 Another special key is called ``parameters``: it's used to define *variables* that

controller.rst

@@ -328,7 +328,7 @@ object. To get it in your controller, just add it as an argument and
 
     use Symfony\Component\HttpFoundation\Request;
 
-    public function indexAction($firstName, $lastName, Request $request)
+    public function indexAction(Request $request, $firstName, $lastName)
     {
         $page = $request->query->get('page', 1);
 

form/form_dependencies.rst

@@ -101,6 +101,7 @@ Next, register this as a service and tag it with ``form.type``:
         services:
             app.form.type.task:
                 class: AppBundle\Form\TaskType
+                arguments: ['@doctrine.orm.entity_manager']
                 tags:
                     - { name: form.type }
 
@@ -114,6 +115,7 @@ Next, register this as a service and tag it with ``form.type``:
 
             <services>
                 <service id="app.form.type.task" class="AppBundle\Form\TaskType">
+                    <argument type="service" id="doctrine.orm.entity_manager"/>
                     <tag name="form.type" />
                 </service>
             </services>
@@ -127,6 +129,7 @@ Next, register this as a service and tag it with ``form.type``:
                 'app.form.type.task',
                 'AppBundle\Form\TaskType'
             )
+            ->addArgument('@doctrine.orm.entity_manager')
             ->addTag('form.type')
         ;
 

page_creation.rst

@@ -81,7 +81,7 @@ to creating a page?
 #. *Create a controller*: The method below the route - ``numberAction()`` - is called
    the *controller*: this is a function where *you* build the page and ultimately
    return a ``Response`` object. You'll learn more about :doc:`controllers </controller>`
-   in their own section, including how to return JSON responses;
+   in their own section, including how to return JSON responses.
 
 The Web Debug Toolbar: Debugging Dream
 --------------------------------------
@@ -129,7 +129,7 @@ variable so we can render that::
             $number = mt_rand(0, 100);
 
             return $this->render('lucky/number.html.twig', array(
-                'number' => $number
+                'number' => $number,
             ));
         }
     }

routing.rst

@@ -120,7 +120,7 @@ Thanks to these two routes:
 
 * If the user goes to ``/blog/*``, the second route is matched and ``showAction()``
   is executed. Because the route path is ``/blog/{slug}``, a ``$slug`` variable is
-  passed to ``showAction`` matching that value. For example, if the user goes to
+  passed to ``showAction()`` matching that value. For example, if the user goes to
   ``/blog/yay-routing``, then ``$slug`` will equal ``yay-routing``.
 
 Whenever you have a ``{placeholder}`` in your route path, that portion becomes a
@@ -363,7 +363,7 @@ With all of this in mind, check out this advanced example:
         {
             /**
              * @Route(
-             *     "/articles/{_locale}/{year}/{title}.{_format}",
+             *     "/articles/{_locale}/{year}/{slug}.{_format}",
              *     defaults={"_format": "html"},
              *     requirements={
              *         "_locale": "en|fr",
@@ -372,7 +372,7 @@ With all of this in mind, check out this advanced example:
              *     }
              * )
              */
-            public function showAction($_locale, $year, $title)
+            public function showAction($_locale, $year, $slug)
             {
             }
         }
@@ -381,7 +381,7 @@ With all of this in mind, check out this advanced example:
 
         # app/config/routing.yml
         article_show:
-          path:     /articles/{_locale}/{year}/{title}.{_format}
+          path:     /articles/{_locale}/{year}/{slug}.{_format}
           defaults: { _controller: AppBundle:Article:show, _format: html }
           requirements:
               _locale:  en|fr
@@ -398,7 +398,7 @@ With all of this in mind, check out this advanced example:
                 http://symfony.com/schema/routing/routing-1.0.xsd">
 
             <route id="article_show"
-                path="/articles/{_locale}/{year}/{title}.{_format}">
+                path="/articles/{_locale}/{year}/{slug}.{_format}">
 
                 <default key="_controller">AppBundle:Article:show</default>
                 <default key="_format">html</default>
@@ -418,7 +418,7 @@ With all of this in mind, check out this advanced example:
         $collection = new RouteCollection();
         $collection->add(
             'article_show',
-            new Route('/articles/{_locale}/{year}/{title}.{_format}', array(
+            new Route('/articles/{_locale}/{year}/{slug}.{_format}', array(
                 '_controller' => 'AppBundle:Article:show',
                 '_format'     => 'html',
             ), array(
@@ -502,11 +502,11 @@ The pattern has three parts, each separated by a colon:
 
 For example, a ``_controller`` value of ``AppBundle:Blog:show`` means:
 
-=============  ==================  ==============
+=============  ==================  ================
 Bundle         Controller Class    Method Name
-=============  ==================  ==============
-``AppBundle``  ``BlogController``  ``showAction``
-=============  ==================  ==============
+=============  ==================  ================
+``AppBundle``  ``BlogController``  ``showAction()``
+=============  ==================  ================
 
 The controller might look like this::
 
@@ -524,7 +524,7 @@ The controller might look like this::
     }
 
 Notice that Symfony adds the string ``Controller`` to the class name (``Blog``
-=> ``BlogController``) and ``Action`` to the method name (``show`` => ``showAction``).
+=> ``BlogController``) and ``Action`` to the method name (``show`` => ``showAction()``).
 
 You could also refer to this controller using its fully-qualified class name
 and method: ``AppBundle\Controller\BlogController::showAction``. But if you

service_container/service_decoration.rst

@@ -18,7 +18,7 @@ the original service is lost:
             # this replaces the old app.mailer definition with the new one, the
             # old definition is lost
             app.mailer:
-                class AppBundle\DecoratingMailer
+                class: AppBundle\DecoratingMailer
 
     .. code-block:: xml
 

setup.rst

@@ -91,6 +91,9 @@ optional second argument of the ``new`` command:
     # use the most recent 'lts' version (Long Term Support version)
     $ symfony new my_project_name lts
 
+Each version has its *own* documentation, which you can select on any documentation
+page.
+
 .. note::
 
     Read the :doc:`Symfony Release process </contributing/community/releases>`
@@ -288,7 +291,7 @@ Go Deeper with Setup
 .. _`Phar extension`: http://php.net/manual/en/intro.phar.php
 .. _`Symfony Standard Edition`: https://github.com/symfony/symfony-standard
 .. _`The Symfony Demo application`: https://github.com/symfony/symfony-demo
-.. _`The Symfony CMF Standard Edition`: https://github.com/symfony-cmf/symfony-cmf-standard
+.. _`The Symfony CMF Standard Edition`: https://github.com/symfony-cmf/standard-edition
 .. _`Symfony CMF`: http://cmf.symfony.com/
 .. _`The Symfony REST Edition`: https://github.com/gimler/symfony-rest-edition
 .. _`FOSRestBundle`: https://github.com/FriendsOfSymfony/FOSRestBundle

setup/bundles.rst

@@ -189,6 +189,13 @@ adding a ``setDefined()`` method. The recommended check in this case would be::
         // code for the new OptionsResolver API
     }
 
+.. tip::
+
+    There is one case when you actually can rely on the
+    ``Symfony\Component\HttpKernel\Kernel::VERSION_ID`` constant: when trying
+    to detect the version of the ``symfony/http-kernel`` component, because it
+    is the component where this constant is defined.
+
 .. _`symfony/phpunit-bridge package`: https://github.com/symfony/phpunit-bridge
 .. _`Official Symfony Guide to Upgrade from 2.x to 3.0`: https://github.com/symfony/symfony/blob/2.8/UPGRADE-3.0.md
 .. _`SensioLabs DeprecationDetector`: https://github.com/sensiolabs-de/deprecation-detector

templating.rst

@@ -575,10 +575,10 @@ Creating links to other pages in your application is one of the most common
 jobs for a template. Instead of hardcoding URLs in templates, use the ``path``
 Twig function (or the ``router`` helper in PHP) to generate URLs based on
 the routing configuration. Later, if you want to modify the URL of a particular
-page, all you'll need to do is change the routing configuration; the templates
+page, all you'll need to do is change the routing configuration: the templates
 will automatically generate the new URL.
 
-First, link to the "_welcome" page, which is accessible via the following routing
+First, link to the "welcome" page, which is accessible via the following routing
 configuration:
 
 .. configuration-block::
@@ -593,7 +593,7 @@ configuration:
         class WelcomeController extends Controller
         {
             /**
-             * @Route("/", name="_welcome")
+             * @Route("/", name="welcome")
              */
             public function indexAction()
             {
@@ -604,7 +604,7 @@ configuration:
     .. code-block:: yaml
 
         # app/config/routing.yml
-        _welcome:
+        welcome:
             path:     /
             defaults: { _controller: AppBundle:Welcome:index }
 
@@ -617,7 +617,7 @@ configuration:
             xsi:schemaLocation="http://symfony.com/schema/routing
                 http://symfony.com/schema/routing/routing-1.0.xsd">
 
-            <route id="_welcome" path="/">
+            <route id="welcome" path="/">
                 <default key="_controller">AppBundle:Welcome:index</default>
             </route>
         </routes>
@@ -629,7 +629,7 @@ configuration:
         use Symfony\Component\Routing\RouteCollection;
 
         $collection = new RouteCollection();
-        $collection->add('_welcome', new Route('/', array(
+        $collection->add('welcome', new Route('/', array(
             '_controller' => 'AppBundle:Welcome:index',
         )));
 
@@ -641,11 +641,11 @@ To link to the page, just use the ``path`` Twig function and refer to the route:
 
     .. code-block:: html+twig
 
-        <a href="{{ path('_welcome') }}">Home</a>
+        <a href="{{ path('welcome') }}">Home</a>
 
     .. code-block:: html+php
 
-        <a href="<?php echo $view['router']->path('_welcome') ?>">Home</a>
+        <a href="<?php echo $view['router']->path('welcome') ?>">Home</a>
 
 .. versionadded:: 2.8
     The ``path()`` PHP templating helper was introduced in Symfony 2.8. Prior
@@ -710,7 +710,7 @@ route:
 
 In this case, you need to specify both the route name (``article_show``) and
 a value for the ``{slug}`` parameter. Using this route, revisit the
-``recent_list`` template from the previous section and link to the articles
+``recent_list.html.twig`` template from the previous section and link to the articles
 correctly:
 
 .. configuration-block::
@@ -743,12 +743,12 @@ correctly:
 
         .. code-block:: html+twig
 
-            <a href="{{ url('_welcome') }}">Home</a>
+            <a href="{{ url('welcome') }}">Home</a>
 
         .. code-block:: html+php
 
             <a href="<?php echo $view['router']->url(
-                '_welcome',
+                'welcome',
                 array()
             ) ?>">Home</a>
 
@@ -909,14 +909,14 @@ block of the base template.
 
 You can also include assets located in your bundles' ``Resources/public`` folder.
 You will need to run the ``php app/console assets:install target [--symlink]``
-command, which moves (or symlinks) files into the correct location. (target
+command, which copies (or symlinks) files into the correct location. (target
 is by default "web").
 
 .. code-block:: html+twig
 
     <link href="{{ asset('bundles/acmedemo/css/contact.css') }}" rel="stylesheet" />
 
-The end result is a page that includes both the ``main.css`` and ``contact.css``
+The end result is a page that includes ``main.js`` and both the ``main.css`` and ``contact.css``
 stylesheets.
 
 Referencing the Request, User or Session
@@ -938,7 +938,7 @@ Suppose ``description`` equals ``I <3 this product``:
 .. code-block:: twig
 
     <!-- output escaping is on automatically -->
-    {{ description }} <!-- I &lt3 this product -->
+    {{ description }} <!-- I &lt;3 this product -->
 
     <!-- disable output escaping with the raw filter -->
     {{ description|raw }} <!-- I <3 this product -->