Merge branch '3.2'

* 3.2: (22 commits)
  add missing config formats
  [symfony#7224] fix indentation
  [symfony#7220] some minor tweaks
  [symfony#7196] add versionadded directive
  Explained how to improve the readability of long numeric literals
  Fix typo in workflow usage code lock
  Added "How to Use a Custom Version Strategy for Assets"
  Use PHP 5.5's ::class notation
  Update state-machines.rst
  [PHPUnitBridge] Fix copy/paste error
  [PHPUnitBridge] Fix copy/paste error
  [symfony#7243] minor tweak
  Deletes duplicate "Deprecated" and adds a more explicit example.
  Accepted Suggestions
  Update 'query_builder' option
  Mentioned %env(...)% variables in Best Practices book
  Accepted suggestions in the guard documentation
  Accepted suggestions in the guard documentation
  Accepted suggestions in the guard documentation
  Update guard_authentication.rst
  ...

Author: xabbuh

_build/conf.py

@@ -112,8 +112,11 @@
 lexers['terminal'] = TerminalLexer()
 
 config_block = {
+    'apache': 'Apache',
     'markdown': 'Markdown',
+    'nginx': 'Nginx',
     'rst': 'reStructuredText',
+    'terminal': 'Terminal',
     'varnish3': 'Varnish 3',
     'varnish4': 'Varnish 4'
 }

_includes/service_container/_my_mailer.rst.inc

@@ -27,9 +27,10 @@
     .. code-block:: php
 
         // app/config/services.php
+        use AppBundle\Mailer;
         use Symfony\Component\DependencyInjection\Definition;
 
         $container->setDefinition('app.mailer', new Definition(
-            'AppBundle\Mailer',
+            Mailer::class,
             array('sendmail')
         ));

best_practices/configuration.rst

@@ -175,8 +175,20 @@ Moving Sensitive Options Outside of Symfony Entirely
 
 When dealing with sensitive options, like database credentials, we also recommend
 that you store them outside the Symfony project and make them available
-through environment variables. Learn how to do it in the following article:
-:doc:`/configuration/external_parameters`.
+through environment variables:
+
+.. code-block:: yaml
+
+    # app/config/config.yml
+    doctrine:
+        dbal:
+            # ...
+            password: "%env(DB_PASSWORD)%"
+
+.. versionadded:: 3.2
+    Support for runtime environment variables via the ``%env(...)%`` syntax
+    was added in Symfony 3.2. Prior to version 3.2, you needed to use the
+    :doc:`special SYMFONY__ variables </configuration/external_parameters>`.
 
 .. _`feature toggles`: https://en.wikipedia.org/wiki/Feature_toggle
 .. _`constant() function`: http://twig.sensiolabs.org/doc/functions/constant.html

best_practices/forms.rst

@@ -19,6 +19,7 @@ form in its own PHP class::
 
     namespace AppBundle\Form;
 
+    use AppBundle\Entity\Post;
     use Symfony\Component\Form\AbstractType;
     use Symfony\Component\Form\FormBuilderInterface;
     use Symfony\Component\OptionsResolver\OptionsResolver;
@@ -42,7 +43,7 @@ form in its own PHP class::
         public function configureOptions(OptionsResolver $resolver)
         {
             $resolver->setDefaults(array(
-                'data_class' => 'AppBundle\Entity\Post'
+                'data_class' => Post::class,
             ));
         }
     }

bundles/extension.rst

@@ -137,14 +137,17 @@ Your bundles can also add their own classes into this file thanks to the
 ``addClassesToCompile()`` method. Define the classes to compile as an array of
 their fully qualified class names::
 
+    use AppBundle\Manager\UserManager;
+    use AppBundle\Utils\Slugger;
+
     // ...
     public function load(array $configs, ContainerBuilder $container)
     {
         // ...
 
         $this->addClassesToCompile(array(
-            'AppBundle\\Manager\\UserManager',
-            'AppBundle\\Utils\\Slugger',
+            UserManager::class,
+            Slugger::class,
             // ...
         ));
     }

bundles/override.rst

@@ -45,6 +45,7 @@ example, the implementing class for the ``original-service-id`` is changed to
     // src/Acme/DemoBundle/DependencyInjection/Compiler/OverrideServiceCompilerPass.php
     namespace Acme\DemoBundle\DependencyInjection\Compiler;
 
+    use Acme\DemoBundle\YourService;
     use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
     use Symfony\Component\DependencyInjection\ContainerBuilder;
 
@@ -53,7 +54,7 @@ example, the implementing class for the ``original-service-id`` is changed to
         public function process(ContainerBuilder $container)
         {
             $definition = $container->getDefinition('original-service-id');
-            $definition->setClass('Acme\DemoBundle\YourService');
+            $definition->setClass(YourService::class);
         }
     }
 

components/class_loader/class_loader.rst

@@ -59,10 +59,10 @@ looked for in a location list to ease the vendoring of a sub-set of classes
 for large projects::
 
     $loader->addPrefixes(array(
-        'Doctrine\\Common'           => __DIR__.'/vendor/doctrine/common/lib',
-        'Doctrine\\DBAL\\Migrations' => __DIR__.'/vendor/doctrine/migrations/lib',
-        'Doctrine\\DBAL'             => __DIR__.'/vendor/doctrine/dbal/lib',
-        'Doctrine'                   => __DIR__.'/vendor/doctrine/orm/lib',
+        'Doctrine\Common'          => __DIR__.'/vendor/doctrine/common/lib',
+        'Doctrine\DBAL\Migrations' => __DIR__.'/vendor/doctrine/migrations/lib',
+        'Doctrine\DBAL'            => __DIR__.'/vendor/doctrine/dbal/lib',
+        'Doctrine'                 => __DIR__.'/vendor/doctrine/orm/lib',
     ));
 
 In this example, if you try to use a class in the ``Doctrine\Common`` namespace

components/class_loader/psr4_class_loader.rst

@@ -38,17 +38,15 @@ The directory structure will look like this:
     demo.php
 
 In ``demo.php`` you are going to parse the ``config.yml`` file. To do that, you
-first need to configure the ``Psr4ClassLoader``:
-
-.. code-block:: php
+first need to configure the ``Psr4ClassLoader``::
 
     use Symfony\Component\ClassLoader\Psr4ClassLoader;
     use Symfony\Component\Yaml\Yaml;
 
     require __DIR__.'/lib/ClassLoader/Psr4ClassLoader.php';
 
     $loader = new Psr4ClassLoader();
-    $loader->addPrefix('Symfony\\Component\\Yaml\\', __DIR__.'/lib/Yaml');
+    $loader->addPrefix('Symfony\Component\Yaml\\', __DIR__.'/lib/Yaml');
     $loader->register();
 
     $data = Yaml::parse(file_get_contents(__DIR__.'/config.yml'));

components/dependency_injection/autowiring.rst

@@ -73,10 +73,11 @@ service is marked as autowired:
 
     .. code-block:: php
 
+        use Acme\TwitterClient;
         use Symfony\Component\DependencyInjection\Definition;
 
         // ...
-        $definition = new Definition('Acme\TwitterClient');
+        $definition = new Definition(TwitterClient::class);
         $definition->setAutowired(true);
 
         $container->setDefinition('twitter_client', $definition);
@@ -147,9 +148,8 @@ modifying the class depending of them.
 
 To follow this best practice, constructor arguments must be typehinted with interfaces
 and not concrete classes. It allows to replace easily the current implementation
-if necessary. It also allows to use other transformers.
-
-Let's introduce a ``TransformerInterface``::
+if necessary. It also allows to use other transformers. You can create a
+``TransformerInterface`` containing just one method (``transform()``)::
 
     namespace Acme;
 
@@ -161,18 +161,15 @@ Let's introduce a ``TransformerInterface``::
 Then edit ``Rot13Transformer`` to make it implementing the new interface::
 
     // ...
-
     class Rot13Transformer implements TransformerInterface
-
-    // ...
-
+    {
+        // ...
+    }
 
 And update ``TwitterClient`` to depend of this new interface::
 
     class TwitterClient
     {
-        // ...
-
         public function __construct(TransformerInterface $transformer)
         {
              // ...
@@ -212,12 +209,13 @@ subsystem isn't able to find itself the interface implementation to register:
 
     .. code-block:: php
 
+        use Acme\TwitterClient;
         use Symfony\Component\DependencyInjection\Definition;
 
         // ...
         $container->register('rot13_transformer', 'Acme\Rot13Transformer');
 
-        $clientDefinition = new Definition('Acme\TwitterClient');
+        $clientDefinition = new Definition(TwitterClient::class);
         $clientDefinition->setAutowired(true);
         $container->setDefinition('twitter_client', $clientDefinition);
 
@@ -350,23 +348,27 @@ and a Twitter client using it:
 
     .. code-block:: php
 
+        use Acme\Rot13Transformer;
+        use Acme\TransformerInterface;
+        use Acme\TwitterClient;
+        use Acme\UppercaseTransformer;
         use Symfony\Component\DependencyInjection\Reference;
         use Symfony\Component\DependencyInjection\Definition;
 
         // ...
-        $rot13Definition = new Definition('Acme\Rot13Transformer');
-        $rot13Definition->setAutowiringTypes(array('Acme\TransformerInterface'));
+        $rot13Definition = new Definition(Rot13Transformer::class);
+        $rot13Definition->setAutowiringTypes(array(TransformerInterface::class));
         $container->setDefinition('rot13_transformer', $rot13Definition);
 
-        $clientDefinition = new Definition('Acme\TwitterClient');
+        $clientDefinition = new Definition(TwitterClient::class);
         $clientDefinition->setAutowired(true);
         $container->setDefinition('twitter_client', $clientDefinition);
 
-        $uppercaseDefinition = new Definition('Acme\UppercaseTransformer');
+        $uppercaseDefinition = new Definition(UppercaseTransformer::class);
         $uppercaseDefinition->setAutowired(true);
         $container->setDefinition('uppercase_transformer', $uppercaseDefinition);
 
-        $uppercaseClientDefinition = new Definition('Acme\TwitterClient', array(
+        $uppercaseClientDefinition = new Definition(TwitterClient::class, array(
             new Reference('uppercase_transformer'),
         ));
         $container->setDefinition('uppercase_twitter_client', $uppercaseClientDefinition);

components/event_dispatcher.rst

@@ -201,27 +201,28 @@ determine which instance is passed.
         use Symfony\Component\DependencyInjection\Definition;
         use Symfony\Component\DependencyInjection\ParameterBag\ParameterBag;
         use Symfony\Component\DependencyInjection\Reference;
+        use Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher;
         use Symfony\Component\EventDispatcher\DependencyInjection\RegisterListenersPass;
 
         $containerBuilder = new ContainerBuilder(new ParameterBag());
         $containerBuilder->addCompilerPass(new RegisterListenersPass());
 
         // register the event dispatcher service
         $containerBuilder->setDefinition('event_dispatcher', new Definition(
-            'Symfony\Component\EventDispatcher\ContainerAwareEventDispatcher',
+            ContainerAwareEventDispatcher::class,
             array(new Reference('service_container'))
         ));
 
         // register your event listener service
-        $listener = new Definition('AcmeListener');
+        $listener = new Definition(\AcmeListener::class);
         $listener->addTag('kernel.event_listener', array(
             'event' => 'foo.action',
             'method' => 'onFooAction',
         ));
         $containerBuilder->setDefinition('listener_service_id', $listener);
 
         // register an event subscriber
-        $subscriber = new Definition('AcmeSubscriber');
+        $subscriber = new Definition(\AcmeSubscriber::class);
         $subscriber->addTag('kernel.event_subscriber');
         $containerBuilder->setDefinition('subscriber_service_id', $subscriber);