Merge branch '2.8' into 3.1

* 2.8:
  [#7220] some minor tweaks
  Use PHP 5.5's ::class notation
  [#7243] minor tweak
  Deletes duplicate "Deprecated" and adds a more explicit example.
  Accepted Suggestions
  Update 'query_builder' option
  Accepted suggestions in the guard documentation
  Accepted suggestions in the guard documentation
  Accepted suggestions in the guard documentation
  Update guard_authentication.rst
  Use PHP 5.5's ::class notation

Author: xabbuh

_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/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);
 

components/form.rst

@@ -648,7 +648,7 @@ option when building each field:
             ->add('dueDate', DateType::class, array(
                 'constraints' => array(
                     new NotBlank(),
-                    new Type('\DateTime'),
+                    new Type(\DateTime::class),
                 )
             ))
             ->getForm();
@@ -667,7 +667,7 @@ option when building each field:
             ->add('dueDate', DateType::class, array(
                 'constraints' => array(
                     new NotBlank(),
-                    new Type('\DateTime'),
+                    new Type(\DateTime::class),
                 )
             ))
             ->getForm();

components/security/authentication.rst

@@ -172,19 +172,19 @@ user. This allows you to use different encoding strategies for different
 types of users. The default :class:`Symfony\\Component\\Security\\Core\\Encoder\\EncoderFactory`
 receives an array of encoders::
 
+    use Acme\Entity\LegacyUser;
     use Symfony\Component\Security\Core\Encoder\EncoderFactory;
     use Symfony\Component\Security\Core\Encoder\MessageDigestPasswordEncoder;
+    use Symfony\Component\Security\Core\User\User;
 
     $defaultEncoder = new MessageDigestPasswordEncoder('sha512', true, 5000);
     $weakEncoder = new MessageDigestPasswordEncoder('md5', true, 1);
 
     $encoders = array(
-        'Symfony\\Component\\Security\\Core\\User\\User' => $defaultEncoder,
-        'Acme\\Entity\\LegacyUser'                       => $weakEncoder,
-
+        User::class       => $defaultEncoder,
+        LegacyUser::class => $weakEncoder,
         // ...
     );
-
     $encoderFactory = new EncoderFactory($encoders);
 
 Each encoder should implement :class:`Symfony\\Component\\Security\\Core\\Encoder\\PasswordEncoderInterface`