Merge branch '3.2'

* 3.2: (23 commits)
  Update options_resolver.rst
  Fixed a minor typo
  Fixed a minor typo
  add labels for old headlines
  fix versionadded directives
  Removed "encryption" and "auth_mode" from the list of %env()% compatible options
  Fixed ... again ... the versionadded directives
  Added the missing "versionadded" directives
  add mail transport as deprecated
  Minor tweaks
  update swiftmailer reference
  Replace calls to setDefinition() by register()
  [PhpUnitBridge] fix Stopwatch API usage
  use namespaced PHPUnit TestCase class
  use namespaced PHPUnit TestCase class
  Better explain empty_data values
  Readd mixed type for empty_data, it can be string, array or object
  Tried to write the important points more explicitly
  Updated the example add added a caution
  Addressed @stof's comment
  ...

Author: xabbuh

_includes/service_container/_my_mailer.rst.inc

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

components/event_dispatcher.rst

@@ -195,7 +195,6 @@ determine which instance is passed.
     a compiler pass called ``RegisterListenersPass()`` in the container builder::
 
         use Symfony\Component\DependencyInjection\ContainerBuilder;
-        use Symfony\Component\DependencyInjection\Definition;
         use Symfony\Component\DependencyInjection\ParameterBag\ParameterBag;
         use Symfony\Component\DependencyInjection\Reference;
         use Symfony\Component\EventDispatcher\EventDispatcher;
@@ -209,17 +208,15 @@ determine which instance is passed.
         $containerBuilder->register('event_dispatcher', EventDispatcher::class);
 
         // register an event listener
-        $listener = new Definition(\AcmeListener::class);
-        $listener->addTag('kernel.event_listener', array(
-            'event' => 'acme.foo.action',
-            'method' => 'onFooAction',
-        ));
-        $containerBuilder->setDefinition('listener_service_id', $listener);
+        $containerBuilder->register('listener_service_id', \AcmeListener::class)
+            ->addTag('kernel.event_listener', array(
+                'event' => 'acme.foo.action',
+                'method' => 'onFooAction',
+            ));
 
         // register an event subscriber
-        $subscriber = new Definition(\AcmeSubscriber::class);
-        $subscriber->addTag('kernel.event_subscriber');
-        $containerBuilder->setDefinition('subscriber_service_id', $subscriber);
+        $containerBuilder->register('subscriber_service_id', \AcmeSubscriber::class)
+            ->addTag('kernel.event_subscriber');
 
     By default, the listeners pass assumes that the event dispatcher's service
     id is ``event_dispatcher``, that event listeners are tagged with the

components/options_resolver.rst

@@ -90,7 +90,7 @@ the ``Mailer`` class makes a mistake?
 .. code-block:: php
 
     $mailer = new Mailer(array(
-        'usernme' => 'johndoe',  // usernAme misspelled
+        'usernme' => 'johndoe',  // usernme misspelled (instead of username)
     ));
 
 No error will be shown. In the best case, the bug will appear during testing,

components/phpunit_bridge.rst

@@ -190,17 +190,18 @@ Use Case
 
 If you have this kind of time-related tests::
 
+    use PHPUnit\Framework\TestCase;
     use Symfony\Component\Stopwatch\Stopwatch;
 
-    class MyTest extends \PHPUnit_Framework_TestCase
+    class MyTest extends TestCase
     {
         public function testSomething()
         {
             $stopwatch = new Stopwatch();
 
-            $stopwatch->start();
+            $stopwatch->start('event_name');
             sleep(10);
-            $duration = $stopwatch->stop();
+            $duration = $stopwatch->stop('event_name')->getDuration();
 
             $this->assertEquals(10, $duration);
         }
@@ -245,12 +246,13 @@ following listener in your PHPUnit configuration:
 As a result, the following is guaranteed to work and is no longer a transient
 test::
 
+    use PHPUnit\Framework\TestCase;
     use Symfony\Component\Stopwatch\Stopwatch;
 
     /**
      * @group time-sensitive
      */
-    class MyTest extends \PHPUnit_Framework_TestCase
+    class MyTest extends TestCase
     {
         public function testSomething()
         {
@@ -297,9 +299,10 @@ Use Case
 Consider the following example that uses the ``checkMX`` option of the ``Email``
 constraint to test the validity of the email domain::
 
+    use PHPUnit\Framework\TestCase;
     use Symfony\Component\Validator\Constraints\Email;
 
-    class MyTest extends \PHPUnit_Framework_TestCase
+    class MyTest extends TestCase
     {
         public function testEmail()
         {
@@ -315,12 +318,13 @@ In order to avoid making a real network connection, add the ``@dns-sensitive``
 annotation to the class and use the ``DnsMock::withMockedHosts()`` to configure
 the data you expect to get for the given hosts::
 
+    use PHPUnit\Framework\TestCase;
     use Symfony\Component\Validator\Constraints\Email;
 
     /**
      * @group dns-sensitive
      */
-    class MyTest extends \PHPUnit_Framework_TestCase
+    class MyTest extends TestCase
     {
         public function testEmails()
         {

controller/error_pages.rst

@@ -296,13 +296,12 @@ In that case, you might want to override one or both of the ``showAction()`` and
             // app/config/services.php
             use AppBundle\Controller\CustomExceptionController;
             use Symfony\Component\DependencyInjection\Reference;
-            use Symfony\Component\DependencyInjection\Definition;
 
-            $definition = new Definition(CustomExceptionController::class, array(
-                new Reference('twig'),
-                '%kernel.debug%'
-            ));
-            $container->setDefinition('app.exception_controller', $definition);
+            $container->register('app.exception_controller', CustomExceptionController::class)
+                ->setArguments(array(
+                    new Reference('twig'),
+                    '%kernel.debug%',
+                ));
 
     And then configure ``twig.exception_controller`` using the controller as
     services syntax (e.g. ``app.exception_controller:showAction``).

controller/service.rst

@@ -234,7 +234,7 @@ argument:
         use AppBundle\Controller\HelloController;
         use Symfony\Component\DependencyInjection\Reference;
 
-        $container->register(HelloController::class)
+        $container->register('app.hello_controller', HelloController::class)
             ->addArgument(new Reference('templating'));
 
 Rather than fetching the ``templating`` service from the container, you can

controller/upload_file.rst

@@ -283,13 +283,10 @@ Then, define a service for this class:
 
         // app/config/services.php
         use AppBundle\FileUploader;
-        use Symfony\Component\DependencyInjection\Definition;
 
         // ...
-        $container->setDefinition('app.brochure_uploader', new Definition(
-            FileUploader::class,
-            array('%brochures_directory%')
-        ));
+        $container->register('app.brochure_uploader', FileUploader::class)
+            ->addArgument('%brochures_directory%');
 
 Now you're ready to use this service in the controller::
 
@@ -411,21 +408,17 @@ Now, register this class as a Doctrine listener:
 
         // app/config/services.php
         use AppBundle\EventListener\BrochureUploaderListener;
-        use Symfony\Component\DependencyInjection\Definition;
         use Symfony\Component\DependencyInjection\Reference;
 
         // ...
-        $definition = new Definition(
-            BrochureUploaderListener::class,
-            array(new Reference('brochures_directory'))
-        );
-        $definition->addTag('doctrine.event_listener', array(
-            'event' => 'prePersist',
-        ));
-        $definition->addTag('doctrine.event_listener', array(
-            'event' => 'preUpdate',
-        ));
-        $container->setDefinition('app.doctrine_brochure_listener', $definition);
+        $container->register('app.doctrine_brochure_listener', BrochureUploaderListener::class)
+            ->addArgument(new Reference('brochures_directory'))
+            ->addTag('doctrine.event_listener', array(
+                'event' => 'prePersist',
+            ))
+            ->addTag('doctrine.event_listener', array(
+                'event' => 'prePersist',
+            ));
 
 This listener is now automatically executed when persisting a new Product
 entity. This way, you can remove everything related to uploading from the

doctrine/event_listeners_subscribers.rst

@@ -84,7 +84,6 @@ managers that use this connection.
         use AppBundle\EventListener\SearchIndexer;
         use AppBundle\EventListener\SearchIndexer2;
         use AppBundle\EventListener\SearchIndexerSubscriber;
-        use Symfony\Component\DependencyInjection\Definition;
 
         $container->loadFromExtension('doctrine', array(
             'dbal' => array(

doctrine/mongodb_session_storage.rst

@@ -77,7 +77,6 @@ need to change/add some parameters in the main configuration file:
     .. code-block:: php
 
         use Symfony\Component\DependencyInjection\Reference;
-        use Symfony\Component\DependencyInjection\Definition;
         use Symfony\Component\HttpFoundation\Session\Storage\Handler\MongoDbSessionHandler;
 
         $container->loadFromExtension('framework', array(
@@ -89,20 +88,19 @@ need to change/add some parameters in the main configuration file:
             ),
         ));
 
-        $container->setDefinition('mongo_client', new Definition(
-            \MongoClient::class,
-            array(
+        $container->register('mongo_client', \MongoClient::class)
+            ->setArguments(array(
                 // if using a username and password
                 array('mongodb://%mongodb_username%:%mongodb_password%@%mongodb_host%:27017'),
                 // if not using a username and password
                 array('mongodb://%mongodb_host%:27017'),
-            )
-        ));
+            ));
 
-        $container->setDefinition('session.handler.mongo', new Definition(
-            MongoDbSessionHandler::class,
-            array(new Reference('mongo_client'), '%mongo.session.options%')
-        ));
+        $container->register('session.handler.mongo', MongoDbSessionHandler::class)
+            ->setArguments(array(
+                new Reference('mongo_client'),
+                '%mongo.session.options%',
+            ));
 
 The parameters used above should be defined somewhere in your application, often in your main
 parameters configuration:
@@ -149,7 +147,6 @@ parameters configuration:
     .. code-block:: php
 
         use Symfony\Component\DependencyInjection\Reference;
-        use Symfony\Component\DependencyInjection\Definition;
 
         $container->setParameter('mongo.session.options', array(
             'database'   => 'session_db', // your MongoDB database name

doctrine/pdo_session_storage.rst

@@ -52,6 +52,8 @@ To use it, you just need to change some parameters in the main configuration fil
 
         // app/config/config.php
 
+        use Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler;
+
         // ...
         $container->loadFromExtension('framework', array(
             // ...
@@ -61,11 +63,11 @@ To use it, you just need to change some parameters in the main configuration fil
             ),
         ));
 
-        $storageDefinition = new Definition(PdoSessionHandler::class, array(
-            'mysql:dbname=mydatabase',
-            array('db_username' => 'myuser', 'db_password' => 'mypassword')
-        ));
-        $container->setDefinition('session.handler.pdo', $storageDefinition);
+        $container->register('session.handler.pdo', PdoSessionHandler::class)
+            ->setArguments(array(
+                'mysql:dbname=mydatabase',
+                array('db_username' => 'myuser', 'db_password' => 'mypassword'),
+            ));
 
 Configuring the Table and Column Names
 --------------------------------------
@@ -106,15 +108,14 @@ a second array argument to ``PdoSessionHandler``:
 
         // app/config/config.php
 
-        use Symfony\Component\DependencyInjection\Definition;
         use Symfony\Component\HttpFoundation\Session\Storage\Handler\PdoSessionHandler;
         // ...
 
-        $storageDefinition = new Definition(PdoSessionHandler::class, array(
-            'mysql:dbname=mydatabase',
-            array('db_table' => 'sessions', 'db_username' => 'myuser', 'db_password' => 'mypassword')
-        ));
-        $container->setDefinition('session.handler.pdo', $storageDefinition);
+        $container->register('session.handler.pdo', PdoSessionHandler::class)
+            ->setArguments(array(
+                'mysql:dbname=mydatabase',
+                array('db_table' => 'sessions', 'db_username' => 'myuser', 'db_password' => 'mypassword'),
+            ));
 
 These are parameters that you must configure: