Merge branch '2.7' into 2.8

* 2.7:
  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()
  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
  improved accuracy
  fix typo
  explicit differences between 'data' & 'empty_data' in FormType

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

@@ -22,7 +22,7 @@ answer.
 Consider the real-world example where you want to provide a plugin system
 for your project. A plugin should be able to add methods, or do something
 before or after a method is executed, without interfering with other plugins.
-This is not an easy problem to solve with single inheritance, and even if 
+This is not an easy problem to solve with single inheritance, and even if
 multiple inheritance was possible with PHP, it comes with its own drawbacks.
 
 The Symfony EventDispatcher component implements the `Mediator`_ pattern
@@ -198,7 +198,6 @@ determine which instance is passed.
     to tag services as event listeners::
 
         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\ContainerAwareEventDispatcher;
@@ -208,23 +207,19 @@ determine which instance is passed.
         $containerBuilder->addCompilerPass(new RegisterListenersPass());
 
         // register the event dispatcher service
-        $containerBuilder->setDefinition('event_dispatcher', new Definition(
-            ContainerAwareEventDispatcher::class,
-            array(new Reference('service_container'))
-        ));
+        $containerBuilder->register('event_dispatcher', ContainerAwareEventDispatcher::class)
+            ->addArgument(new Reference('service_container'));
 
         // register your event listener service
-        $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
@@ -441,7 +436,7 @@ EventDispatcher Aware Events and Listeners
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``EventDispatcher`` always passes the dispatched event, the event's
-name and a reference to itself to the listeners. This can lead to some advanced 
+name and a reference to itself to the listeners. This can lead to some advanced
 applications of the ``EventDispatcher`` including dispatching other events inside
 listeners, chaining events or even lazy loading listeners into the dispatcher object.
 

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,

console/logging.rst

@@ -110,21 +110,14 @@ First configure a listener for console exception events in the service container
 
         // app/config/services.php
         use AppBundle\EventListener\ConsoleExceptionListener;
-        use Symfony\Component\DependencyInjection\Definition;
         use Symfony\Component\DependencyInjection\Reference;
 
-        $definitionConsoleExceptionListener = new Definition(
-            ConsoleExceptionListener::class,
-            array(new Reference('logger'))
-        );
-        $definitionConsoleExceptionListener->addTag(
-            'kernel.event_listener',
-            array('event' => 'console.exception')
-        );
-        $container->setDefinition(
-            'app.listener.command_exception',
-            $definitionConsoleExceptionListener
-        );
+        $container->register('app.listener.command_exception', ConsoleExceptionListener::class)
+            ->addArgument(new Reference('logger'))
+            ->addTag(
+                'kernel.event_listener',
+                array('event' => 'console.exception')
+            );
 
 Then implement the actual listener::
 
@@ -211,21 +204,14 @@ First configure a listener for console terminate events in the service container
 
         // app/config/services.php
         use AppBundle\EventListener\ErrorLoggerListener;
-        use Symfony\Component\DependencyInjection\Definition;
         use Symfony\Component\DependencyInjection\Reference;
 
-        $definitionErrorLoggerListener = new Definition(
-            ErrorLoggerListener::class,
-            array(new Reference('logger'))
-        );
-        $definitionErrorLoggerListener->addTag(
-            'kernel.event_listener',
-            array('event' => 'console.terminate')
-        );
-        $container->setDefinition(
-            'app.listener.command_error',
-            $definitionErrorLoggerListener
-        );
+        $container->register('app.listener.command_error', ErrorLoggerListener::class)
+            ->addArgument(new Reference('logger'))
+            ->addTag(
+                'kernel.event_listener',
+                array('event' => 'console.terminate')
+            );
 
 Then implement the actual listener::
 

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

@@ -226,13 +226,10 @@ argument:
 
         // app/config/services.php
         use AppBundle\Controller\HelloController;
-        use Symfony\Component\DependencyInjection\Definition;
         use Symfony\Component\DependencyInjection\Reference;
 
-        $container->setDefinition('app.hello_controller', new Definition(
-            HelloController::class,
-            array(new Reference('templating'))
-        ));
+        $container->register('app.hello_controller', HelloController::class)
+            ->addArgument(new Reference('templating'));
 
 Rather than fetching the ``templating`` service from the container, you can
 inject *only* the exact service(s) that you need directly into the controller.

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: