Introduce consistent Comparator API

UPGRADE.md

@@ -8,6 +8,17 @@ awareness about deprecated code.
 
 # Upgrade to 3.2
 
+## Deprecated static calls to `Comparator::compareSchemas($fromSchema, $toSchema)`
+
+The usage of `Comparator::compareSchemas($fromSchema, $toSchema)` statically is
+deprecated in order to provide a more consistent API.
+
+## Deprecated `Comparator::compare($fromSchema, $toSchema)`
+
+The usage of `Comparator::compare($fromSchema, $toSchema)` is deprecated and 
+replaced by `Comparator::compareSchemas($fromSchema, $toSchema)` in order to
+clarify the purpose of the method.
+
 ## Deprecated `Connection::lastInsertId($name)`
 
 The usage of `Connection::lastInsertId()` with a sequence name is deprecated as unsafe in scenarios with multiple

phpstan.neon.dist

@@ -108,6 +108,15 @@ parameters:
             paths:
                 - %currentWorkingDirectory%/src/Platforms/AbstractPlatform.php
 
+        # See https://github.com/doctrine/dbal/pull/4707
+        # TODO: remove in 4.0.0
+        -
+            message: '~^Dynamic call to static method Doctrine\\DBAL\\Schema\\Comparator::compareSchemas\(\)\.$~'
+            paths:
+                - %currentWorkingDirectory%/src/Schema/AbstractSchemaManager.php
+                - %currentWorkingDirectory%/src/Schema/Comparator.php
+                - %currentWorkingDirectory%/src/Schema/Schema.php
+
         # We're checking for invalid invalid input
         -
             message: "#^Strict comparison using \\!\\=\\= between null and null will always evaluate to false\\.$#"

psalm.xml.dist

@@ -87,6 +87,11 @@
                 -->
                 <file name="src/Schema/AbstractSchemaManager.php" />
                 <file name="src/Schema/PostgreSQLSchemaManager.php" />
+                <!--
+                    See https://github.com/doctrine/dbal/pull/4707
+                    TODO: remove in 4.0.0
+                -->
+                <file name="src/Schema/Comparator.php" />
                 <directory name="tests" />
                 <referencedMethod name="Doctrine\DBAL\Statement::execute"/>
             </errorLevel>

src/Schema/AbstractSchemaManager.php

@@ -694,7 +694,9 @@ public function alterSchema(SchemaDiff $schemaDiff): void
      */
     public function migrateSchema(Schema $toSchema): void
     {
-        $this->alterSchema(Comparator::compareSchemas($this->createSchema(), $toSchema));
+        $schemaDiff = (new Comparator())->compareSchemas($this->createSchema(), $toSchema);
+
+        $this->alterSchema($schemaDiff);
     }
 
     /* alterTable() Methods */

src/Schema/Comparator.php

@@ -3,6 +3,7 @@
 namespace Doctrine\DBAL\Schema;
 
 use Doctrine\DBAL\Types;
+use Doctrine\Deprecations\Deprecation;
 
 use function array_intersect_key;
 use function array_key_exists;
@@ -20,31 +21,18 @@
  */
 class Comparator
 {
-    /**
-     * @return SchemaDiff
-     *
-     * @throws SchemaException
-     */
-    public static function compareSchemas(Schema $fromSchema, Schema $toSchema)
-    {
-        $c = new self();
-
-        return $c->compare($fromSchema, $toSchema);
-    }
-
     /**
      * Returns a SchemaDiff object containing the differences between the schemas $fromSchema and $toSchema.
      *
-     * The returned differences are returned in such a way that they contain the
-     * operations to change the schema stored in $fromSchema to the schema that is
-     * stored in $toSchema.
+     * This method should be called non-statically since it will be declared as non-static in the next major release.
      *
      * @return SchemaDiff
      *
      * @throws SchemaException
      */
-    public function compare(Schema $fromSchema, Schema $toSchema)
+    public static function compareSchemas(Schema $fromSchema, Schema $toSchema)
     {
+        $comparator       = new self();
         $diff             = new SchemaDiff();
         $diff->fromSchema = $fromSchema;
 
@@ -71,7 +59,7 @@ public function compare(Schema $fromSchema, Schema $toSchema)
             if (! $fromSchema->hasTable($tableName)) {
                 $diff->newTables[$tableName] = $toSchema->getTable($tableName);
             } else {
-                $tableDifferences = $this->diffTable(
+                $tableDifferences = $comparator->diffTable(
                     $fromSchema->getTable($tableName),
                     $toSchema->getTable($tableName)
                 );
@@ -134,18 +122,18 @@ public function compare(Schema $fromSchema, Schema $toSchema)
         foreach ($toSchema->getSequences() as $sequence) {
             $sequenceName = $sequence->getShortestName($toSchema->getName());
             if (! $fromSchema->hasSequence($sequenceName)) {
-                if (! $this->isAutoIncrementSequenceInSchema($fromSchema, $sequence)) {
+                if (! $comparator->isAutoIncrementSequenceInSchema($fromSchema, $sequence)) {
                     $diff->newSequences[] = $sequence;
                 }
             } else {
-                if ($this->diffSequence($sequence, $fromSchema->getSequence($sequenceName))) {
+                if ($comparator->diffSequence($sequence, $fromSchema->getSequence($sequenceName))) {
                     $diff->changedSequences[] = $toSchema->getSequence($sequenceName);
                 }
             }
         }
 
         foreach ($fromSchema->getSequences() as $sequence) {
-            if ($this->isAutoIncrementSequenceInSchema($toSchema, $sequence)) {
+            if ($comparator->isAutoIncrementSequenceInSchema($toSchema, $sequence)) {
                 continue;
             }
 
@@ -161,6 +149,24 @@ public function compare(Schema $fromSchema, Schema $toSchema)
         return $diff;
     }
 
+    /**
+     * @deprecated Use non-static call to {@link compareSchemas()} instead.
+     *
+     * @return SchemaDiff
+     *
+     * @throws SchemaException
+     */
+    public function compare(Schema $fromSchema, Schema $toSchema)
+    {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/4707',
+            'Method compare() is deprecated. Use a non-static call to compareSchemas() instead.'
+        );
+
+        return $this->compareSchemas($fromSchema, $toSchema);
+    }
+
     /**
      * @param Schema   $schema
      * @param Sequence $sequence

src/Schema/Schema.php

@@ -437,8 +437,7 @@ public function toDropSql(AbstractPlatform $platform)
      */
     public function getMigrateToSql(Schema $toSchema, AbstractPlatform $platform)
     {
-        $comparator = new Comparator();
-        $schemaDiff = $comparator->compare($this, $toSchema);
+        $schemaDiff = (new Comparator())->compareSchemas($this, $toSchema);
 
         return $schemaDiff->toSql($platform);
     }
@@ -450,8 +449,7 @@ public function getMigrateToSql(Schema $toSchema, AbstractPlatform $platform)
      */
     public function getMigrateFromSql(Schema $fromSchema, AbstractPlatform $platform)
     {
-        $comparator = new Comparator();
-        $schemaDiff = $comparator->compare($fromSchema, $this);
+        $schemaDiff = (new Comparator())->compareSchemas($fromSchema, $this);
 
         return $schemaDiff->toSql($platform);
     }

src/Schema/SchemaDiff.php

@@ -7,7 +7,10 @@
 use function array_merge;
 
 /**
- * Schema Diff.
+ * Differences between two schemas.
+ *
+ * The object contains the operations to change the schema stored in $fromSchema
+ * to a target schema.
  */
 class SchemaDiff
 {