Merge pull request #919 from goetas/query-value-object

Introduce query value object to wrap sql queries

lib/Doctrine/Migrations/AbstractMigration.php

@@ -13,8 +13,8 @@
 use Doctrine\Migrations\Exception\IrreversibleMigration;
 use Doctrine\Migrations\Exception\MigrationException;
 use Doctrine\Migrations\Exception\SkipMigration;
+use Doctrine\Migrations\Query\Query;
 use Psr\Log\LoggerInterface;
-use function func_get_args;
 
 /**
  * The AbstractMigration class is for end users to extend from when creating migrations. Extend this class
@@ -34,7 +34,7 @@ abstract class AbstractMigration
     /** @var LoggerInterface */
     private $logger;
 
-    /** @var mixed[] */
+    /** @var Query[] */
     private $plannedSql = [];
 
     public function __construct(Connection $connection, LoggerInterface $logger)
@@ -142,11 +142,11 @@ protected function addSql(
         array $params = [],
         array $types = []
     ) : void {
-        $this->plannedSql[] = func_get_args();
+        $this->plannedSql[] = new Query($sql, $params, $types);
     }
 
     /**
-     * @return mixed[]
+     * @return Query[]
      */
     public function getSql() : array
     {

lib/Doctrine/Migrations/DbalMigrator.php

@@ -6,6 +6,7 @@
 
 use Doctrine\DBAL\Connection;
 use Doctrine\Migrations\Metadata\MigrationPlanList;
+use Doctrine\Migrations\Query\Query;
 use Doctrine\Migrations\Tools\BytesFormatter;
 use Doctrine\Migrations\Version\Executor;
 use Psr\Log\LoggerInterface;
@@ -51,7 +52,7 @@ public function __construct(
     }
 
     /**
-     * @return string[][]
+     * @return array<string, Query[]>
      */
     private function executeMigrations(
         MigrationPlanList $migrationsPlan,
@@ -85,7 +86,7 @@ private function executeMigrations(
     }
 
     /**
-     * @return array<string, string[]>
+     * @return array<string, Query[]>
      */
     private function executePlan(MigrationPlanList $migrationsPlan, MigratorConfiguration $migratorConfiguration) : array
     {
@@ -110,7 +111,7 @@ private function executePlan(MigrationPlanList $migrationsPlan, MigratorConfigur
     }
 
     /**
-     * @param string[][] $sql
+     * @param array<string, Query[]> $sql
      */
     private function endMigrations(
         StopwatchEvent $stopwatchEvent,

lib/Doctrine/Migrations/FileQueryWriter.php

@@ -7,6 +7,7 @@
 use DateTimeImmutable;
 use DateTimeInterface;
 use Doctrine\Migrations\Generator\FileBuilder;
+use Doctrine\Migrations\Query\Query;
 use Psr\Log\LoggerInterface;
 use function file_put_contents;
 use function is_dir;
@@ -34,7 +35,7 @@ public function __construct(
     }
 
     /**
-     * @param mixed[] $queriesByVersion
+     * @param array<string,Query[]> $queriesByVersion
      */
     public function write(
         string $path,

lib/Doctrine/Migrations/Generator/ConcatenationFileBuilder.php

@@ -6,6 +6,7 @@
 
 use DateTimeImmutable;
 use DateTimeInterface;
+use Doctrine\Migrations\Query\Query;
 use function sprintf;
 
 /**
@@ -15,7 +16,7 @@
  */
 final class ConcatenationFileBuilder implements FileBuilder
 {
-    /** @param string[][] $queriesByVersion */
+    /** @param array<string,Query[]> $queriesByVersion */
     public function buildMigrationFile(
         array $queriesByVersion,
         string $direction,
@@ -25,12 +26,10 @@ public function buildMigrationFile(
         $string = sprintf("-- Doctrine Migration File Generated on %s\n", $now->format('Y-m-d H:i:s'));
 
         foreach ($queriesByVersion as $version => $queries) {
-            $version = (string) $version;
-
             $string .= "\n-- Version " . $version . "\n";
 
             foreach ($queries as $query) {
-                $string .= $query . ";\n";
+                $string .= $query->getStatement() . ";\n";
             }
         }
 

lib/Doctrine/Migrations/Generator/FileBuilder.php

@@ -5,6 +5,7 @@
 namespace Doctrine\Migrations\Generator;
 
 use DateTimeInterface;
+use Doctrine\Migrations\Query\Query;
 
 /**
  * The ConcatenationFileBuilder class is responsible for building a migration SQL file from an array of queries per version.
@@ -13,6 +14,6 @@
  */
 interface FileBuilder
 {
-    /** @param string[][] $queriesByVersion */
+    /** @param array<string,Query[]> $queriesByVersion */
     public function buildMigrationFile(array $queriesByVersion, string $direction, ?DateTimeInterface $now = null) : string;
 }

lib/Doctrine/Migrations/Migrator.php

@@ -5,16 +5,17 @@
 namespace Doctrine\Migrations;
 
 use Doctrine\Migrations\Metadata\MigrationPlanList;
+use Doctrine\Migrations\Query\Query;
 
 /**
- * The DbalMigrator class is responsible for generating and executing the SQL for a migration.
+ * The Migrator interface is responsible for generating and executing the SQL for a migration.
  *
  * @internal
  */
 interface Migrator
 {
     /**
-     * @return array<string, string[]> A list of SQL statements executed, grouped by migration version
+     * @return array<string, Query[]> A list of SQL statements executed, grouped by migration version
      */
     public function migrate(MigrationPlanList $migrationsPlan, MigratorConfiguration $migratorConfiguration) : array;
 }

lib/Doctrine/Migrations/Query/Exception/InvalidArguments.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Migrations\Query\Exception;
+
+use Doctrine\Migrations\Exception\MigrationException;
+use InvalidArgumentException;
+use function sprintf;
+
+class InvalidArguments extends InvalidArgumentException implements MigrationException
+{
+    public static function wrongTypesArgumentCount(string $statement, int $parameters, int $types) : self
+    {
+        return new self(sprintf(
+            'The number of types (%s) is higher than the number of passed parameters (%s) for the query "%s".',
+            $types,
+            $parameters,
+            $statement
+        ));
+    }
+}

lib/Doctrine/Migrations/Query/Query.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Migrations\Query;
+
+use Doctrine\Migrations\Query\Exception\InvalidArguments;
+use function count;
+
+/**
+ * The Query wraps the sql query, parameters and types.
+ */
+final class Query
+{
+    /** @var string */
+    private $statement;
+
+    /** @var mixed[] */
+    private $parameters;
+
+    /** @var mixed[] */
+    private $types;
+
+    /**
+     * @param mixed[] $parameters
+     * @param mixed[] $types
+     */
+    public function __construct(string $statement, array $parameters = [], array $types = [])
+    {
+        if (count($types) > count($parameters)) {
+            throw InvalidArguments::wrongTypesArgumentCount($statement, count($parameters), count($types));
+        }
+
+        $this->statement  = $statement;
+        $this->parameters = $parameters;
+        $this->types      = $types;
+    }
+
+    public function __toString() : string
+    {
+        return $this->statement;
+    }
+
+    public function getStatement() : string
+    {
+        return $this->statement;
+    }
+
+    /** @return mixed[] */
+    public function getParameters() : array
+    {
+        return $this->parameters;
+    }
+
+    /** @return mixed[] */
+    public function getTypes() : array
+    {
+        return $this->types;
+    }
+}

lib/Doctrine/Migrations/QueryWriter.php

@@ -4,6 +4,8 @@
 
 namespace Doctrine\Migrations;
 
+use Doctrine\Migrations\Query\Query;
+
 /**
  * The QueryWriter defines the interface used for writing migration SQL queries to a file on disk.
  *
@@ -12,7 +14,7 @@
 interface QueryWriter
 {
     /**
-     * @param string[][] $queriesByVersion
+     * @param array<string,Query[]> $queriesByVersion
      */
     public function write(
         string $path,