Use the shorthand notation when applicable

Author: greg0ire

best_practices/business-logic.rst

@@ -57,9 +57,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;
@@ -96,9 +94,7 @@ your code will be easier to read and use.
     you ever need to.
 
 Now you can use the custom slugger in any controller class, such as the
-``AdminController``:
-
-.. code-block:: php
+``AdminController``::
 
     public function createAction(Request $request)
     {
@@ -203,9 +199,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;
 
@@ -284,9 +278,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;
 
@@ -129,9 +127,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 Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
@@ -161,9 +157,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")
@@ -182,9 +176,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\Route;

best_practices/forms.rst

@@ -94,9 +94,7 @@ makes them easier to re-use later.
 
 Since Symfony 2.3, you can 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
+directly in your form class, this would effectively limit the scope of that form::
 
     class PostType extends AbstractType
     {
@@ -178,9 +176,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

@@ -130,9 +130,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\Route;
@@ -163,9 +161,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
     // ...
@@ -185,9 +181,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;
@@ -217,9 +211,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")
@@ -257,9 +249,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;
 
@@ -313,9 +303,7 @@ To enable the security voter in the application, define a new service:
             tags:
                - { name: security.voter }
 
-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")
@@ -327,9 +315,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

@@ -115,9 +115,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``
-service in the constructor of the Twig extension:
-
-.. code-block:: php
+service 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

@@ -417,9 +417,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

@@ -260,9 +260,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::
 
     $document = new \DOMDocument();
     $document->loadXml('<root><node /><node /></root>');

components/expression_language/extending.rst

@@ -68,9 +68,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;