Use the shorthand notation when applicable

It's part of the standard

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

@@ -107,7 +107,7 @@ above each action.
 In our application, you need the ``ROLE_ADMIN`` in order to create a new post.
 Using ``@Security``, this looks like:
 
-.. code-block:: php
+::
 
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Security;
@@ -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/browser_kit.rst

@@ -155,7 +155,7 @@ retrieve any cookie while making requests with the client::
 Looping Through Cookies
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-.. code-block:: php
+::
 
     use Acme\Client;
 

components/config/definition.rst

@@ -379,7 +379,7 @@ has a certain value:
     (``null``, ``true``, ``false``), provide a replacement value in case
     the value is ``*.``
 
-.. code-block:: php
+::
 
     $rootNode
         ->children()
@@ -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/caching.rst

@@ -58,7 +58,7 @@ Both ``evaluate()`` and ``compile()`` can handle ``ParsedExpression`` and
 
     var_dump($language->evaluate($expression)); // prints 5
 
-.. code-block:: php
+::
 
     use Symfony\Component\ExpressionLanguage\SerializedParsedExpression;
     // ...

components/expression_language/extending.rst

@@ -29,7 +29,7 @@ This method has 3 arguments:
   function;
 * **evaluator** - A function executed when the expression is evaluated.
 
-.. code-block:: php
+::
 
     use Symfony\Component\ExpressionLanguage\ExpressionLanguage;
 
@@ -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;

components/filesystem/lock_handler.rst

@@ -22,9 +22,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/http_foundation/trusting_proxies.rst

@@ -17,9 +17,7 @@ the actual host may be stored in an ``X-Forwarded-Host`` header.
 
 Since HTTP headers can be spoofed, Symfony does *not* trust these proxy
 headers by default. If you are behind a proxy, you should manually whitelist
-your proxy as follows:
-
-.. code-block:: php
+your proxy as follows::
 
     use Symfony\Component\HttpFoundation\Request;
 

components/options_resolver.rst

@@ -95,7 +95,7 @@ options are buried in the business logic of your code. Use the
 Now all four options are guaranteed to be set. But what happens if the user of
 the ``Mailer`` class makes a mistake?
 
-.. code-block:: php
+::
 
     $mailer = new Mailer(array(
         'usernme' => 'johndoe',  // usernme misspelled (instead of username)

components/process.rst

@@ -310,9 +310,7 @@ Process Pid
     The ``getPid()`` method was introduced in Symfony 2.3.
 
 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/property_access.rst

@@ -288,7 +288,7 @@ can use setters, the magic ``__set()`` method or properties to set values::
 You can also use ``__call()`` to set values but you need to enable the feature,
 see `Enable other Features`_.
 
-.. code-block:: php
+::
 
     // ...
     class Person
@@ -327,7 +327,7 @@ Writing to Array Properties
 The ``PropertyAccessor`` class allows to update the content of arrays stored in
 properties through *adder* and *remover* methods.
 
-.. code-block:: php
+::
 
     // ...
     class Person

components/security/authorization.rst

@@ -54,7 +54,7 @@ recognizes several strategies:
 ``unanimous``
     only grant access if none of the voters has denied access;
 
-.. code-block:: php
+::
 
     use Symfony\Component\Security\Core\Authorization\AccessDecisionManager;
 
@@ -115,7 +115,7 @@ and ``IS_AUTHENTICATED_ANONYMOUSLY`` and grants access based on the current
 level of authentication, i.e. is the user fully authenticated, or only based
 on a "remember-me" cookie, or even authenticated anonymously?
 
-.. code-block:: php
+::
 
     use Symfony\Component\Security\Core\Authentication\AuthenticationTrustResolver;
     use Symfony\Component\Security\Core\Authentication\Token\AnonymousToken;

components/templating.rst

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