Fix: #6146 - utf8/utf8mb3 alias causes redundant ALTER TABLE changes

src/Platforms/AbstractMySQLPlatform.php

@@ -29,6 +29,7 @@
 use function sprintf;
 use function str_replace;
 use function strtolower;
+use function version_compare;
 
 /**
  * Provides the base implementation for the lowest versions of supported MySQL-like database platforms.
@@ -839,4 +840,14 @@ private function indexAssetsByLowerCaseName(array $assets): array
 
         return $result;
     }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @link https://dev.mysql.com/doc/refman/8.0/en/charset-unicode-utf8mb3.html
+     */
+    public function informationSchemaUsesUtf8mb3(Connection $connection): bool
+    {
+        return version_compare($connection->getServerVersion(), '8.0.30') >= 0;
+    }
 }

src/Platforms/MariaDBPlatform.php

@@ -4,6 +4,7 @@
 
 namespace Doctrine\DBAL\Platforms;
 
+use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Platforms\Keywords\KeywordList;
 use Doctrine\DBAL\Platforms\Keywords\MariaDBKeywords;
 use Doctrine\DBAL\Schema\ForeignKeyConstraint;
@@ -14,6 +15,7 @@
 use function array_merge;
 use function count;
 use function in_array;
+use function version_compare;
 
 /**
  * Provides the behavior, features and SQL dialect of the MariaDB database platform of the oldest supported version.
@@ -162,4 +164,21 @@ protected function createReservedKeywordsList(): KeywordList
     {
         return new MariaDBKeywords();
     }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @link https://mariadb.com/kb/en/unicode/
+     * @link https://mariadb.com/kb/en/old-mode/
+     */
+    public function informationSchemaUsesUtf8mb3(Connection $connection): bool
+    {
+        if (version_compare($connection->getServerVersion(), '10.6.0') < 0) {
+            return false;
+        }
+
+        $oldMode = (string) $connection->fetchOne('SELECT @old_mode');
+
+        return ! str_contains($oldMode, 'UTF8_IS_UTF8MB3');
+    }
 }

src/Platforms/MySQL/CharsetMetadataProvider.php

@@ -7,5 +7,7 @@
 /** @internal */
 interface CharsetMetadataProvider
 {
+    public function normalizeCharset(string $charset): string;
+
     public function getDefaultCharsetCollation(string $charset): ?string;
 }

src/Platforms/MySQL/CharsetMetadataProvider/CachingCharsetMetadataProvider.php

@@ -18,6 +18,11 @@ public function __construct(private readonly CharsetMetadataProvider $charsetMet
     {
     }
 
+    public function normalizeCharset(string $charset): string
+    {
+        return $this->charsetMetadataProvider->normalizeCharset($charset);
+    }
+
     public function getDefaultCharsetCollation(string $charset): ?string
     {
         if (array_key_exists($charset, $this->cache)) {

src/Platforms/MySQL/CharsetMetadataProvider/ConnectionCharsetMetadataProvider.php

@@ -11,13 +11,28 @@
 /** @internal */
 final class ConnectionCharsetMetadataProvider implements CharsetMetadataProvider
 {
-    public function __construct(private readonly Connection $connection)
+    public function __construct(private readonly Connection $connection, private bool $useUtf8mb3)
     {
     }
 
+    public function normalizeCharset(string $charset): string
+    {
+        if ($this->useUtf8mb3 && $charset === 'utf8') {
+            return 'utf8mb3';
+        }
+
+        if (! $this->useUtf8mb3 && $charset === 'utf8mb3') {
+            return 'utf8';
+        }
+
+        return $charset;
+    }
+
     /** @throws Exception */
     public function getDefaultCharsetCollation(string $charset): ?string
     {
+        $charset = $this->normalizeCharset($charset);
+
         $collation = $this->connection->fetchOne(
             <<<'SQL'
             SELECT DEFAULT_COLLATE_NAME

src/Platforms/MySQL/CollationMetadataProvider.php

@@ -7,5 +7,7 @@
 /** @internal */
 interface CollationMetadataProvider
 {
+    public function normalizeCollation(string $collation): string;
+
     public function getCollationCharset(string $collation): ?string;
 }

src/Platforms/MySQL/CollationMetadataProvider/CachingCollationMetadataProvider.php

@@ -18,6 +18,11 @@ public function __construct(private readonly CollationMetadataProvider $collatio
     {
     }
 
+    public function normalizeCollation(string $collation): string
+    {
+        return $this->collationMetadataProvider->normalizeCollation($collation);
+    }
+
     public function getCollationCharset(string $collation): ?string
     {
         if (array_key_exists($collation, $this->cache)) {

src/Platforms/MySQL/CollationMetadataProvider/ConnectionCollationMetadataProvider.php

@@ -8,16 +8,34 @@
 use Doctrine\DBAL\Exception;
 use Doctrine\DBAL\Platforms\MySQL\CollationMetadataProvider;
 
+use function str_starts_with;
+use function substr;
+
 /** @internal */
 final class ConnectionCollationMetadataProvider implements CollationMetadataProvider
 {
-    public function __construct(private readonly Connection $connection)
+    public function __construct(private readonly Connection $connection, private bool $useUtf8mb3)
     {
     }
 
+    public function normalizeCollation(string $collation): string
+    {
+        if ($this->useUtf8mb3 && str_starts_with($collation, 'utf8_')) {
+            return 'utf8mb3' . substr($collation, 4);
+        }
+
+        if (! $this->useUtf8mb3 && str_starts_with($collation, 'utf8mb3_')) {
+            return 'utf8' . substr($collation, 7);
+        }
+
+        return $collation;
+    }
+
     /** @throws Exception */
     public function getCollationCharset(string $collation): ?string
     {
+        $collation = $this->normalizeCollation($collation);
+
         $charset = $this->connection->fetchOne(
             <<<'SQL'
 SELECT CHARACTER_SET_NAME

src/Platforms/MySQL/Comparator.php

@@ -82,10 +82,20 @@ private function normalizeTable(Table $table): Table
      */
     private function normalizeOptions(array $options): array
     {
-        if (isset($options['charset']) && ! isset($options['collation'])) {
-            $options['collation'] = $this->charsetMetadataProvider->getDefaultCharsetCollation($options['charset']);
-        } elseif (isset($options['collation']) && ! isset($options['charset'])) {
-            $options['charset'] = $this->collationMetadataProvider->getCollationCharset($options['collation']);
+        if (isset($options['charset'])) {
+            $options['charset'] = $this->charsetMetadataProvider->normalizeCharset($options['charset']);
+
+            if (! isset($options['collation'])) {
+                $options['collation'] = $this->charsetMetadataProvider->getDefaultCharsetCollation($options['charset']);
+            }
+        }
+
+        if (isset($options['collation'])) {
+            $options['collation'] = $this->collationMetadataProvider->normalizeCollation($options['collation']);
+
+            if (! isset($options['charset'])) {
+                $options['charset'] = $this->collationMetadataProvider->getCollationCharset($options['collation']);
+            }
         }
 
         return $options;

src/Schema/MySQLSchemaManager.php

@@ -316,13 +316,15 @@ protected function _getPortableTableForeignKeyDefinition(array $tableForeignKey)
     /** @throws Exception */
     public function createComparator(): Comparator
     {
+        $useUtf8mb3 = $this->platform->informationSchemaUsesUtf8mb3($this->connection);
+
         return new MySQL\Comparator(
             $this->platform,
             new CachingCharsetMetadataProvider(
-                new ConnectionCharsetMetadataProvider($this->connection),
+                new ConnectionCharsetMetadataProvider($this->connection, $useUtf8mb3),
             ),
             new CachingCollationMetadataProvider(
-                new ConnectionCollationMetadataProvider($this->connection),
+                new ConnectionCollationMetadataProvider($this->connection, $useUtf8mb3),
             ),
             $this->getDefaultTableOptions(),
         );

tests/Platforms/MySQL/CollationMetadataProvider/ConnectionCharsetMetadataProviderTest.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Tests\Platforms\MySQL\CollationMetadataProvider;
+
+use Doctrine\DBAL\Connection;
+use Doctrine\DBAL\Platforms\MySQL\CharsetMetadataProvider\ConnectionCharsetMetadataProvider;
+use PHPUnit\Framework\TestCase;
+
+class ConnectionCharsetMetadataProviderTest extends TestCase
+{
+    public function testNormalizeCharset(): void
+    {
+        $connection = $this->createMock(Connection::class);
+
+        $utf8Provider = new ConnectionCharsetMetadataProvider($connection, false);
+
+        self::assertSame('utf8', $utf8Provider->normalizeCharset('utf8'));
+        self::assertSame('utf8', $utf8Provider->normalizeCharset('utf8mb3'));
+        self::assertSame('foobar', $utf8Provider->normalizeCharset('foobar'));
+
+        $utf8mb3Provider = new ConnectionCharsetMetadataProvider($connection, true);
+
+        self::assertSame('utf8mb3', $utf8mb3Provider->normalizeCharset('utf8'));
+        self::assertSame('utf8mb3', $utf8mb3Provider->normalizeCharset('utf8mb3'));
+        self::assertSame('foobar', $utf8mb3Provider->normalizeCharset('foobar'));
+    }
+}

tests/Platforms/MySQL/CollationMetadataProvider/ConnectionCollationMetadataProviderTest.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Tests\Platforms\MySQL\CollationMetadataProvider;
+
+use Doctrine\DBAL\Connection;
+use Doctrine\DBAL\Platforms\MySQL\CollationMetadataProvider\ConnectionCollationMetadataProvider;
+use PHPUnit\Framework\TestCase;
+
+class ConnectionCollationMetadataProviderTest extends TestCase
+{
+    public function testNormalizeCcollation(): void
+    {
+        $connection = $this->createMock(Connection::class);
+
+        $utf8Provider = new ConnectionCollationMetadataProvider($connection, false);
+
+        self::assertSame('utf8_unicode_ci', $utf8Provider->normalizeCollation('utf8_unicode_ci'));
+        self::assertSame('utf8_unicode_ci', $utf8Provider->normalizeCollation('utf8mb3_unicode_ci'));
+        self::assertSame('foobar_unicode_ci', $utf8Provider->normalizeCollation('foobar_unicode_ci'));
+
+        $utf8mb3Provider = new ConnectionCollationMetadataProvider($connection, true);
+
+        self::assertSame('utf8mb3_unicode_ci', $utf8mb3Provider->normalizeCollation('utf8_unicode_ci'));
+        self::assertSame('utf8mb3_unicode_ci', $utf8mb3Provider->normalizeCollation('utf8mb3_unicode_ci'));
+        self::assertSame('foobar_unicode_ci', $utf8mb3Provider->normalizeCollation('foobar_unicode_ci'));
+    }
+}

tests/Platforms/MySQL/ComparatorTest.php

@@ -4,12 +4,19 @@
 
 namespace Doctrine\DBAL\Tests\Platforms\MySQL;
 
+use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\Platforms\MySQL\CharsetMetadataProvider;
+use Doctrine\DBAL\Platforms\MySQL\CharsetMetadataProvider\ConnectionCharsetMetadataProvider;
 use Doctrine\DBAL\Platforms\MySQL\CollationMetadataProvider;
+use Doctrine\DBAL\Platforms\MySQL\CollationMetadataProvider\ConnectionCollationMetadataProvider;
 use Doctrine\DBAL\Platforms\MySQL\Comparator;
 use Doctrine\DBAL\Platforms\MySQL\DefaultTableOptions;
 use Doctrine\DBAL\Platforms\MySQLPlatform;
+use Doctrine\DBAL\Schema\Column;
+use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\Tests\Schema\AbstractComparatorTestCase;
+use Doctrine\DBAL\Types\StringType;
+use PHPUnit\Framework\Attributes\DataProvider;
 
 class ComparatorTest extends AbstractComparatorTestCase
 {
@@ -22,4 +29,81 @@ protected function setUp(): void
             new DefaultTableOptions('utf8mb4', 'utf8mb4_general_ci'),
         );
     }
+
+    #[DataProvider('utf8AndUtf8mb3MismatchesProvider')]
+    public function testUtf8AndUtf8mb3Mismatches(bool $useUtf8mb3, string $defaultCharset): void
+    {
+        $connection = $this->createMock(Connection::class);
+        $platform   = new MySQLPlatform();
+
+        $utf8Comparator = new Comparator(
+            $platform,
+            new ConnectionCharsetMetadataProvider($connection, $useUtf8mb3),
+            new ConnectionCollationMetadataProvider($connection, $useUtf8mb3),
+            new DefaultTableOptions($defaultCharset, $defaultCharset . '_unicode_ci'),
+        );
+
+        $table1 = new Table('t1', [
+            new Column('c', new StringType(), [
+                'length' => 8,
+                'platformOptions' => ['collation' => 'utf8_unicode_ci'],
+            ]),
+        ]);
+        $table2 = new Table('t2', [
+            new Column('c', new StringType(), [
+                'length' => 8,
+                'platformOptions' => ['collation' => 'utf8mb3_unicode_ci'],
+            ]),
+        ]);
+        $table3 = new Table('t3', [
+            new Column('c', new StringType(), [
+                'length' => 8,
+                'platformOptions' => ['collation' => 'utf8mb4_unicode_ci'],
+            ]),
+        ]);
+
+        self::assertEmpty($utf8Comparator->compareTables($table1, $table2)->getModifiedColumns());
+        self::assertEmpty($utf8Comparator->compareTables($table2, $table1)->getModifiedColumns());
+        self::assertNotEmpty($utf8Comparator->compareTables($table1, $table3)->getModifiedColumns());
+        self::assertNotEmpty($utf8Comparator->compareTables($table3, $table1)->getModifiedColumns());
+        self::assertNotEmpty($utf8Comparator->compareTables($table2, $table3)->getModifiedColumns());
+        self::assertNotEmpty($utf8Comparator->compareTables($table3, $table2)->getModifiedColumns());
+
+        $table4 = new Table('t4', [
+            new Column('c', new StringType(), [
+                'length' => 8,
+                'platformOptions' => ['charset' => 'utf8'],
+            ]),
+        ]);
+        $table5 = new Table('t5', [
+            new Column('c', new StringType(), [
+                'length' => 8,
+                'platformOptions' => ['charset' => 'utf8mb3'],
+            ]),
+        ]);
+        $table6 = new Table('t6', [
+            new Column('c', new StringType(), [
+                'length' => 8,
+                'platformOptions' => ['charset' => 'utf8mb4'],
+            ]),
+        ]);
+
+        self::assertEmpty($utf8Comparator->compareTables($table4, $table5)->getModifiedColumns());
+        self::assertEmpty($utf8Comparator->compareTables($table5, $table4)->getModifiedColumns());
+        self::assertNotEmpty($utf8Comparator->compareTables($table4, $table6)->getModifiedColumns());
+        self::assertNotEmpty($utf8Comparator->compareTables($table6, $table4)->getModifiedColumns());
+        self::assertNotEmpty($utf8Comparator->compareTables($table5, $table6)->getModifiedColumns());
+        self::assertNotEmpty($utf8Comparator->compareTables($table6, $table5)->getModifiedColumns());
+    }
+
+    /** @return iterable<array{bool,string}> */
+    public static function utf8AndUtf8mb3MismatchesProvider(): iterable
+    {
+        yield [false, 'utf8'];
+        yield [true, 'utf8'];
+        yield [false, 'utf8mb3'];
+        yield [true, 'utf8mb3'];
+        yield [false, 'utf8mb4'];
+        yield [true, 'utf8mb4'];
+    }
 }

tests/Platforms/MySQL/MariaDBJsonComparatorTest.php

@@ -28,12 +28,22 @@ protected function setUp(): void
         $this->comparator = new Comparator(
             new MariaDBPlatform(),
             new class implements CharsetMetadataProvider {
+                public function normalizeCharset(string $charset): string
+                {
+                    return $charset;
+                }
+
                 public function getDefaultCharsetCollation(string $charset): ?string
                 {
                     return null;
                 }
             },
             new class implements CollationMetadataProvider {
+                public function normalizeCollation(string $collation): string
+                {
+                    return $collation;
+                }
+
                 public function getCollationCharset(string $collation): ?string
                 {
                     return null;