Dispatch events for migration execution (#114)

* Dispatch events for migration execution

* drop symfony dispatcher from dev deps

* Readme

README.md

@@ -177,12 +177,23 @@ Implement `executeQuery()` to run checks or other code before/after each query.
 Interface of this method mimics interface of `Doctrine\DBAL\Connection::executeQuery()`.
 
 #### Alter generated migration SQLs:
+
 You can implement custom `MigrationAnalyzer` and register it as a service.
 This allows you to alter generated SQLs (e.g. add `ALGORITHM=INSTANT`) and assign them to proper phase.
 
+#### Hook to migration execution:
+
+If you pass `Psr\EventDispatcher\EventDispatcherInterface` to `MigrationService`, you can hook into migration execution.
+Dispatched events are:
+- `MigrationExecutionStartedEvent`
+- `MigrationExecutionSucceededEvent`
+- `MigrationExecutionFailedEvent`
+
+All events have `MigrationPhase` enum and `Migration` instance available.
+
 #### Run all queries within transaction:
 
-You can change your template (or a single migration) to extend; `TransactionalMigration`.
+You can change your template (or a single migration) to extend `TransactionalMigration`.
 That causes each phases to be executed within migration.
 Be aware that many databases (like MySQL) does not support transaction over DDL operations (ALTER and such).
 

composer.json

@@ -8,6 +8,7 @@
         "php": "^8.1",
         "doctrine/dbal": "^3.6.0 || ^4.0.0",
         "doctrine/orm": "^3.0.0",
+        "psr/event-dispatcher": "^1.0",
         "symfony/console": "^5.4.0 || ^6.0.0 || ^7.0.0"
     },
     "require-dev": {

phpcs.xml.dist

@@ -278,7 +278,6 @@
     <rule ref="SlevomatCodingStandard.Classes.RequireSelfReference"/>
     <rule ref="SlevomatCodingStandard.Classes.TraitUseDeclaration" />
     <rule ref="SlevomatCodingStandard.Classes.TraitUseSpacing" />
-    <rule ref="SlevomatCodingStandard.Classes.DisallowConstructorPropertyPromotion" />
     <rule ref="SlevomatCodingStandard.Commenting.DocCommentSpacing">
         <properties>
             <property name="linesCountBeforeFirstContent" value="0"/>

src/Event/MigrationExecutionFailedEvent.php

@@ -0,0 +1,21 @@
+<?php declare(strict_types = 1);
+
+namespace ShipMonk\Doctrine\Migration\Event;
+
+use ShipMonk\Doctrine\Migration\Migration;
+use ShipMonk\Doctrine\Migration\MigrationPhase;
+use Throwable;
+
+class MigrationExecutionFailedEvent
+{
+
+    public function __construct(
+        public readonly Migration $migration,
+        public readonly string $version,
+        public readonly MigrationPhase $phase,
+        public readonly Throwable $exception,
+    )
+    {
+    }
+
+}

src/Event/MigrationExecutionStartedEvent.php

@@ -0,0 +1,19 @@
+<?php declare(strict_types = 1);
+
+namespace ShipMonk\Doctrine\Migration\Event;
+
+use ShipMonk\Doctrine\Migration\Migration;
+use ShipMonk\Doctrine\Migration\MigrationPhase;
+
+class MigrationExecutionStartedEvent
+{
+
+    public function __construct(
+        public readonly Migration $migration,
+        public readonly string $version,
+        public readonly MigrationPhase $phase,
+    )
+    {
+    }
+
+}

src/Event/MigrationExecutionSucceededEvent.php

@@ -0,0 +1,19 @@
+<?php declare(strict_types = 1);
+
+namespace ShipMonk\Doctrine\Migration\Event;
+
+use ShipMonk\Doctrine\Migration\Migration;
+use ShipMonk\Doctrine\Migration\MigrationPhase;
+
+class MigrationExecutionSucceededEvent
+{
+
+    public function __construct(
+        public readonly Migration $migration,
+        public readonly string $version,
+        public readonly MigrationPhase $phase,
+    )
+    {
+    }
+
+}

src/MigrationService.php

@@ -9,6 +9,10 @@
 use Doctrine\ORM\EntityManagerInterface;
 use Doctrine\ORM\Tools\SchemaTool;
 use LogicException;
+use Psr\EventDispatcher\EventDispatcherInterface;
+use ShipMonk\Doctrine\Migration\Event\MigrationExecutionFailedEvent;
+use ShipMonk\Doctrine\Migration\Event\MigrationExecutionStartedEvent;
+use ShipMonk\Doctrine\Migration\Event\MigrationExecutionSucceededEvent;
 use Throwable;
 use function file_get_contents;
 use function file_put_contents;
@@ -33,22 +37,26 @@ class MigrationService
 
     private MigrationVersionProvider $versionProvider;
 
-    private MigrationAnalyzer $migrationsAnalyzer;
+    private MigrationAnalyzer $migrationAnalyzer;
+
+    private ?EventDispatcherInterface $eventDispatcher;
 
     public function __construct(
         EntityManagerInterface $entityManager,
         MigrationConfig $config,
         ?MigrationExecutor $executor = null,
         ?MigrationVersionProvider $versionProvider = null,
-        ?MigrationAnalyzer $migrationsAnalyzer = null,
+        ?MigrationAnalyzer $migrationAnalyzer = null,
+        ?EventDispatcherInterface $eventDispatcher = null,
     )
     {
         $this->entityManager = $entityManager;
         $this->connection = $entityManager->getConnection();
         $this->config = $config;
         $this->executor = $executor ?? new MigrationDefaultExecutor($this->connection);
         $this->versionProvider = $versionProvider ?? new MigrationDefaultVersionProvider();
-        $this->migrationsAnalyzer = $migrationsAnalyzer ?? new MigrationDefaultAnalyzer();
+        $this->migrationAnalyzer = $migrationAnalyzer ?? new MigrationDefaultAnalyzer();
+        $this->eventDispatcher = $eventDispatcher;
     }
 
     public function getConfig(): MigrationConfig
@@ -67,17 +75,22 @@ public function executeMigration(string $version, MigrationPhase $phase): Migrat
     {
         $migration = $this->getMigration($version);
 
-        if ($migration instanceof TransactionalMigration) {
-            try {
-                $this->connection->beginTransaction();
+        $this->eventDispatcher?->dispatch(new MigrationExecutionStartedEvent($migration, $version, $phase));
+
+        try {
+            if ($migration instanceof TransactionalMigration) {
+                $run = $this->connection->transactional(function () use ($migration, $version, $phase): MigrationRun {
+                    return $this->doExecuteMigration($migration, $version, $phase);
+                });
+            } else {
                 $run = $this->doExecuteMigration($migration, $version, $phase);
-                $this->connection->commit();
-            } catch (Throwable $e) {
-                $this->connection->rollBack();
-                throw $e;
             }
-        } else {
-            $run = $this->doExecuteMigration($migration, $version, $phase);
+
+            $this->eventDispatcher?->dispatch(new MigrationExecutionSucceededEvent($migration, $version, $phase));
+
+        } catch (Throwable $e) {
+            $this->eventDispatcher?->dispatch(new MigrationExecutionFailedEvent($migration, $version, $phase, $e));
+            throw $e;
         }
 
         return $run;
@@ -231,7 +244,7 @@ private function excludeTablesFromSchema(Schema $schema): void
      */
     public function generateMigrationFile(array $sqls): MigrationFile
     {
-        $statements = $this->migrationsAnalyzer->analyze($sqls);
+        $statements = $this->migrationAnalyzer->analyze($sqls);
         $statementsBefore = $statementsAfter = [];
 
         foreach ($statements as $statement) {

tests/MigrationServiceTest.php

@@ -5,6 +5,9 @@
 use Doctrine\ORM\EntityManagerInterface;
 use LogicException;
 use PHPUnit\Framework\TestCase;
+use Psr\EventDispatcher\EventDispatcherInterface;
+use ShipMonk\Doctrine\Migration\Event\MigrationExecutionStartedEvent;
+use ShipMonk\Doctrine\Migration\Event\MigrationExecutionSucceededEvent;
 use function array_map;
 use function file_get_contents;
 use function glob;
@@ -22,9 +25,24 @@ class MigrationServiceTest extends TestCase
 
     public function testInitGenerationExecution(): void
     {
+        $invokedCount = self::exactly(4);
+        $eventDispatcher = $this->createMock(EventDispatcherInterface::class);
+        $eventDispatcher->expects($invokedCount)
+            ->method('dispatch')
+            ->willReturnCallback(static function (object $event) use ($invokedCount): object {
+                match ($invokedCount->numberOfInvocations()) {
+                    1 => self::assertInstanceOf(MigrationExecutionStartedEvent::class, $event, $event::class),
+                    2 => self::assertInstanceOf(MigrationExecutionSucceededEvent::class, $event, $event::class),
+                    3 => self::assertInstanceOf(MigrationExecutionStartedEvent::class, $event, $event::class),
+                    4 => self::assertInstanceOf(MigrationExecutionSucceededEvent::class, $event, $event::class),
+                    default => self::fail('Unexpected event'),
+                };
+                return $event;
+            });
+
         [$entityManager] = $this->createEntityManagerAndLogger();
         $connection = $entityManager->getConnection();
-        $service = $this->createMigrationService($entityManager);
+        $service = $this->createMigrationService($entityManager, eventDispatcher: $eventDispatcher);
 
         $migrationTableName = $service->getConfig()->getMigrationTableName();
 
@@ -134,7 +152,7 @@ public function getNextVersion(): string
         };
         [$entityManager, $logger] = $this->createEntityManagerAndLogger();
 
-        $migrationsService = $this->createMigrationService($entityManager, [], false, $versionProvider);
+        $migrationsService = $this->createMigrationService($entityManager, versionProvider: $versionProvider);
 
         $migrationsService->initializeMigrationTable();
         $logger->clean();
@@ -296,6 +314,7 @@ private function createMigrationService(
         bool $transactional = false,
         ?MigrationVersionProvider $versionProvider = null,
         ?MigrationAnalyzer $statementAnalyzer = null,
+        ?EventDispatcherInterface $eventDispatcher = null,
     ): MigrationService
     {
         $migrationsDir = $this->getMigrationsTestDir();
@@ -329,6 +348,7 @@ private function createMigrationService(
             null,
             $versionProvider,
             $statementAnalyzer,
+            $eventDispatcher,
         );
     }