Merge pull request #348 from goetas/document-container-drop

Document that container aware migrations are not special anymore

Author: goetas

Resources/doc/index.rst

@@ -229,6 +229,67 @@ You can skip single migrations by explicitly adding them to the ``migration_vers
 
 Doctrine will then assume that this migration has already been run and will ignore it.
 
+Migration Dependencies
+----------------------
+
+Migrations can have dependencies on external services (such as geolocation, mailer, data processing services...) that
+can be used to have more powerful migrations. Those dependencies are not automatically injected into your migrations
+but need to be injected using custom migrations factories.
+
+Here is an example on how to inject the service container into your migrations:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/doctrine_migrations.yml
+        doctrine_migrations:
+            services:
+                 'Doctrine\Migrations\Version\MigrationFactory': 'App\Migrations\Factory\MigrationFactoryDecorator'
+
+        # config/services.yml
+        services:
+            Doctrine\Migrations\Version\DbalMigrationFactory: ~
+            App\Migrations\Factory\MigrationFactoryDecorator:
+                decorates: Doctrine\Migrations\Version\DbalMigrationFactory
+                arguments: ['@App\Migrations\Factory\MigrationFactoryDecorator.inner', '@service_container']
+
+
+.. code-block:: php
+
+    declare(strict_types=1);
+
+    namespace App\Migrations\Factory;
+
+    use Doctrine\Migrations\AbstractMigration;
+    use Doctrine\Migrations\Version\MigrationFactory;
+    use Symfony\Component\DependencyInjection\ContainerAwareInterface;
+    use Symfony\Component\DependencyInjection\ContainerInterface;
+
+    class MigrationFactoryDecorator implements MigrationFactory
+    {
+        private $migrationFactory;
+        private $container;
+
+        public function __construct(MigrationFactory $migrationFactory, ContainerInterface $container)
+        {
+            $this->migrationFactory = $migrationFactory;
+            $this->container        = $container;
+        }
+
+        public function createVersion(string $migrationClassName): AbstractMigration
+        {
+            $instance = $this->migrationFactory->createVersion($migrationClassName);
+
+            if ($instance instanceof ContainerAwareInterface) {
+                $instance->setContainer($this->container);
+            }
+
+            return $instance;
+        }
+    }
+
+
 Generating Migrations Automatically
 -----------------------------------
 

UPGRADE.md

@@ -72,3 +72,6 @@ doctrine_migrations:
 Upgrading this bundle to `3.0` will also update the `doctrine/migrations` library to the version `3.0`.
 Backward incompatible changes in `doctrine/migrations` 3.0 
 are documented in the dedicated [UPGRADE](https://github.com/doctrine/migrations/blob/3.0.x/UPGRADE.md) document. 
+
+- The container is not automatically injected anymore when a migration implements `ContainerAwareInterface`. Custom
+migration factories should be used to inject additional dependencies into migrations.