Merge branch '2.8' into 3.4

* 2.8:
  Use the shorthand notation when applicable

Author: javiereguiluz

best_practices/business-logic.rst

@@ -61,9 +61,7 @@ The blog application needs a utility that can transform a post title (e.g.
 part of the post URL.
 
 Let's create a new ``Slugger`` class inside ``src/AppBundle/Utils/`` and
-add the following ``slugify()`` method:
-
-.. code-block:: php
+add the following ``slugify()`` method::
 
     // src/AppBundle/Utils/Slugger.php
     namespace AppBundle\Utils;
@@ -106,9 +104,7 @@ use the class name.
     case, use a snake case id).
 
 Now you can use the custom slugger in any controller class, such as the
-``AdminController``:
-
-.. code-block:: php
+``AdminController``::
 
     use AppBundle\Utils\Slugger;
 
@@ -229,9 +225,7 @@ PHP and annotations.
     Use annotations to define the mapping information of the Doctrine entities.
 
 Annotations are by far the most convenient and agile way of setting up and
-looking for mapping information:
-
-.. code-block:: php
+looking for mapping information::
 
     namespace AppBundle\Entity;
 
@@ -310,9 +304,7 @@ the following command to install the Doctrine fixtures bundle:
     $ composer require "doctrine/doctrine-fixtures-bundle"
 
 Then, enable the bundle in ``AppKernel.php``, but only for the ``dev`` and
-``test`` environments:
-
-.. code-block:: php
+``test`` environments::
 
     use Symfony\Component\HttpKernel\Kernel;
 

best_practices/configuration.rst

@@ -133,9 +133,7 @@ Constants can be used for example in your Twig templates thanks to the
     </p>
 
 And Doctrine entities and repositories can now easily access these values,
-whereas they cannot access the container parameters:
-
-.. code-block:: php
+whereas they cannot access the container parameters::
 
     namespace AppBundle\Repository;
 

best_practices/controllers.rst

@@ -89,9 +89,7 @@ What does the Controller look like
 ----------------------------------
 
 Considering all this, here is an example of what the controller should look like
-for the homepage of our app:
-
-.. code-block:: php
+for the homepage of our app::
 
     namespace AppBundle\Controller;
 
@@ -145,9 +143,7 @@ to automatically query for an entity and pass it as an argument to your controll
     Use the ParamConverter trick to automatically query for Doctrine entities
     when it's simple and convenient.
 
-For example:
-
-.. code-block:: php
+For example::
 
     use AppBundle\Entity\Post;
     use Symfony\Component\Routing\Annotation\Route;
@@ -177,9 +173,7 @@ When Things Get More Advanced
 The above example works without any configuration because the wildcard name ``{id}`` matches
 the name of the property on the entity. If this isn't true, or if you have
 even more complex logic, the easiest thing to do is just query for the entity
-manually. In our application, we have this situation in ``CommentController``:
-
-.. code-block:: php
+manually. In our application, we have this situation in ``CommentController``::
 
     /**
      * @Route("/comment/{postSlug}/new", name="comment_new")
@@ -198,9 +192,7 @@ manually. In our application, we have this situation in ``CommentController``:
     }
 
 You can also use the ``@ParamConverter`` configuration, which is infinitely
-flexible:
-
-.. code-block:: php
+flexible::
 
     use AppBundle\Entity\Post;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\ParamConverter;

best_practices/forms.rst

@@ -88,9 +88,7 @@ makes them easier to re-use later.
 The Symfony Form component allows you to add buttons as fields on your form.
 This is a nice way to simplify the template that renders your form. But if you
 add the buttons directly in your form class, this would effectively limit the
-scope of that form:
-
-.. code-block:: php
+scope of that form::
 
     class PostType extends AbstractType
     {
@@ -173,9 +171,7 @@ can control *how* the form renders at a global level using form theming.
 Handling Form Submits
 ---------------------
 
-Handling a form submit usually follows a similar template:
-
-.. code-block:: php
+Handling a form submit usually follows a similar template::
 
     public function newAction(Request $request)
     {

best_practices/security.rst

@@ -137,9 +137,7 @@ Using Expressions for Complex Security Restrictions
 If your security logic is a little bit more complex, you can use an :doc:`expression </components/expression_language>`
 inside ``@Security``. In the following example, a user can only access the
 controller if their email matches the value returned by the ``getAuthorEmail()``
-method on the ``Post`` object:
-
-.. code-block:: php
+method on the ``Post`` object::
 
     use AppBundle\Entity\Post;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Security;
@@ -170,9 +168,7 @@ need to repeat the expression code using Twig syntax:
     {% endif %}
 
 The easiest solution - if your logic is simple enough - is to add a new method
-to the ``Post`` entity that checks if a given user is its author:
-
-.. code-block:: php
+to the ``Post`` entity that checks if a given user is its author::
 
     // src/AppBundle/Entity/Post.php
     // ...
@@ -192,9 +188,7 @@ to the ``Post`` entity that checks if a given user is its author:
         }
     }
 
-Now you can reuse this method both in the template and in the security expression:
-
-.. code-block:: php
+Now you can reuse this method both in the template and in the security expression::
 
     use AppBundle\Entity\Post;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Security;
@@ -225,9 +219,7 @@ Checking Permissions without @Security
 The above example with ``@Security`` only works because we're using the
 :ref:`ParamConverter <best-practices-paramconverter>`, which gives the expression
 access to the ``post`` variable. If you don't use this, or have some other
-more advanced use-case, you can always do the same security check in PHP:
-
-.. code-block:: php
+more advanced use-case, you can always do the same security check in PHP::
 
     /**
      * @Route("/{id}/edit", name="admin_post_edit")
@@ -266,9 +258,7 @@ of magnitude easier than :doc:`ACLs </security/acl>` and will give
 you the flexibility you need in almost all cases.
 
 First, create a voter class. The following example shows a voter that implements
-the same ``getAuthorEmail()`` logic you used above:
-
-.. code-block:: php
+the same ``getAuthorEmail()`` logic you used above::
 
     namespace AppBundle\Security;
 
@@ -342,9 +332,7 @@ your application will :ref:`autoconfigure <services-autoconfigure>` your securit
 voter and inject an ``AccessDecisionManagerInterface`` instance into it thanks to
 :doc:`autowiring </service_container/autowiring>`.
 
-Now, you can use the voter with the ``@Security`` annotation:
-
-.. code-block:: php
+Now, you can use the voter with the ``@Security`` annotation::
 
     /**
      * @Route("/{id}/edit", name="admin_post_edit")
@@ -356,9 +344,7 @@ Now, you can use the voter with the ``@Security`` annotation:
     }
 
 You can also use this directly with the ``security.authorization_checker`` service or
-via the even easier shortcut in a controller:
-
-.. code-block:: php
+via the even easier shortcut in a controller::
 
     /**
      * @Route("/{id}/edit", name="admin_post_edit")

best_practices/templates.rst

@@ -105,9 +105,7 @@ Markdown content into HTML::
 
 Next, create a new Twig extension and define a new filter called ``md2html``
 using the ``Twig_SimpleFilter`` class. Inject the newly defined ``Markdown``
-class in the constructor of the Twig extension:
-
-.. code-block:: php
+class in the constructor of the Twig extension::
 
     namespace AppBundle\Twig;
 

best_practices/tests.rst

@@ -80,9 +80,7 @@ generator service:
     generator.
 
 Consider the following functional test that uses the ``router`` service to
-generate the URL of the tested page:
-
-.. code-block:: php
+generate the URL of the tested page::
 
     public function testBlogArchives()
     {

components/config/definition.rst

@@ -461,9 +461,7 @@ Documenting the Option
 
 All options can be documented using the
 :method:`Symfony\\Component\\Config\\Definition\\Builder\\NodeDefinition::info`
-method.
-
-.. code-block:: php
+method::
 
     $rootNode
         ->children()

components/dom_crawler.rst

@@ -253,9 +253,7 @@ The crawler supports multiple ways of adding the content::
 
 As the Crawler's implementation is based on the DOM extension, it is also able
 to interact with native :phpclass:`DOMDocument`, :phpclass:`DOMNodeList`
-and :phpclass:`DOMNode` objects:
-
-.. code-block:: php
+and :phpclass:`DOMNode` objects::
 
     $domDocument = new \DOMDocument();
     $domDocument->loadXml('<root><node /><node /></root>');

components/expression_language/extending.rst

@@ -65,9 +65,7 @@ This interface requires one method:
 :method:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunctionProviderInterface::getFunctions`,
 which returns an array of expression functions (instances of
 :class:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunction`) to
-register.
-
-.. code-block:: php
+register::
 
     use Symfony\Component\ExpressionLanguage\ExpressionFunction;
     use Symfony\Component\ExpressionLanguage\ExpressionFunctionProviderInterface;

components/filesystem/lock_handler.rst

@@ -24,9 +24,7 @@ Usage
     The lock handler only works if you're using just one server. If you have
     several hosts, you must not use this helper.
 
-A lock can be used, for example, to allow only one instance of a command to run.
-
-.. code-block:: php
+A lock can be used, for example, to allow only one instance of a command to run::
 
     use Symfony\Component\Filesystem\LockHandler;
 

components/process.rst

@@ -391,9 +391,7 @@ Process Pid
 -----------
 
 You can access the `pid`_ of a running process with the
-:method:`Symfony\\Component\\Process\\Process::getPid` method.
-
-.. code-block:: php
+:method:`Symfony\\Component\\Process\\Process::getPid` method::
 
     use Symfony\Component\Process\Process;
 

components/templating.rst

@@ -187,9 +187,7 @@ takes a list of engines and acts just like a normal templating engine. The
 only difference is that it delegates the calls to one of the other engines. To
 choose which one to use for the template, the
 :method:`EngineInterface::supports() <Symfony\\Component\\Templating\\EngineInterface::supports>`
-method is used.
-
-.. code-block:: php
+method is used::
 
     use Acme\Templating\CustomEngine;
     use Symfony\Component\Templating\PhpEngine;

components/translation.rst

@@ -29,9 +29,7 @@ catalogs*).
 Configuration
 ~~~~~~~~~~~~~
 
-The constructor of the ``Translator`` class needs one argument: The locale.
-
-.. code-block:: php
+The constructor of the ``Translator`` class needs one argument: The locale::
 
     use Symfony\Component\Translation\Translator;
 

components/yaml.rst

@@ -96,9 +96,7 @@ Reading YAML Contents
 ~~~~~~~~~~~~~~~~~~~~~
 
 The :method:`Symfony\\Component\\Yaml\\Yaml::parse` method parses a YAML
-string and converts it to a PHP array:
-
-.. code-block:: php
+string and converts it to a PHP array::
 
     use Symfony\Component\Yaml\Yaml;
 
@@ -108,9 +106,7 @@ string and converts it to a PHP array:
 If an error occurs during parsing, the parser throws a
 :class:`Symfony\\Component\\Yaml\\Exception\\ParseException` exception
 indicating the error type and the line in the original YAML string where the
-error occurred:
-
-.. code-block:: php
+error occurred::
 
     use Symfony\Component\Yaml\Exception\ParseException;
 
@@ -141,9 +137,7 @@ Writing YAML Files
 ~~~~~~~~~~~~~~~~~~
 
 The :method:`Symfony\\Component\\Yaml\\Yaml::dump` method dumps any PHP
-array to its YAML representation:
-
-.. code-block:: php
+array to its YAML representation::
 
     use Symfony\Component\Yaml\Yaml;
 
@@ -175,9 +169,7 @@ representation:
 
 The second argument of the :method:`Symfony\\Component\\Yaml\\Yaml::dump`
 method customizes the level at which the output switches from the expanded
-representation to the inline one:
-
-.. code-block:: php
+representation to the inline one::
 
     echo Yaml::dump($array, 1);
 

components/yaml/yaml_format.rst

@@ -177,9 +177,7 @@ Sequences use a dash followed by a space:
     - Perl
     - Python
 
-The previous YAML file is equivalent to the following PHP code:
-
-.. code-block:: php
+The previous YAML file is equivalent to the following PHP code::
 
     array('PHP', 'Perl', 'Python');
 
@@ -191,9 +189,7 @@ Mappings use a colon followed by a space (``:`` ) to mark each key/value pair:
     MySQL: 5.1
     Apache: 2.2.20
 
-which is equivalent to this PHP code:
-
-.. code-block:: php
+which is equivalent to this PHP code::
 
     array('PHP' => 5.2, 'MySQL' => 5.1, 'Apache' => '2.2.20');
 
@@ -220,9 +216,7 @@ YAML uses indentation with one or more spaces to describe nested collections:
       PHP:    5.2
       Propel: 1.3
 
-The above YAML is equivalent to the following PHP code:
-
-.. code-block:: php
+The above YAML is equivalent to the following PHP code::
 
     array(
         'symfony 1.0' => array(

configuration/environments.rst

@@ -31,9 +31,7 @@ are used:
 * for the ``test`` environment: ``app/config/config_test.yml``
 
 This works via a simple standard that's used by default inside the ``AppKernel``
-class:
-
-.. code-block:: php
+class::
 
     // app/AppKernel.php