Deprecate omitting the charset

This is similar to an issue we have had on the ORM with identifier
generator strategies: we default to some value of a setting, then
something better comes out, and we get stuck with the deprecated setting
for backward compatibility reasons.

In this case, utf8 has been deprecated for years and should no longer be
used according to the official documentation:
https://dev.mysql.com/doc/refman/8.0/en/charset-unicode-utf8.html

This kind of BC-break might be handled better by things such as Symfony
Recipes because it is OK to do such BC breaks there since they only
affect new projects.

UPGRADE.md

@@ -8,6 +8,11 @@ awareness about deprecated code.
 
 # Upgrade to 3.4
 
+## Deprecated omitting the charset when using MySQL
+
+Omitting the charset when using MySQL results in the deprecated `utf8` MySQL
+charset being used. Configure it explicitly when creating a connection.
+
 ## Deprecated `AbstractPlatform` schema introspection methods
 
 The following schema introspection methods have been deprecated:

src/Platforms/AbstractMySQLPlatform.php

@@ -460,6 +460,11 @@ private function buildTableOptions(array $options): string
 
         // Charset
         if (! isset($options['charset'])) {
+            Deprecation::trigger(
+                'doctrine/dbal',
+                'https://github.com/doctrine/dbal/issues/5278',
+                'Omitting the charset option is deprecated, be explicit about it instead. We recommend using "utf8b4"'
+            );
             $options['charset'] = 'utf8';
         }
 

tests/Platforms/MySQLPlatformTest.php

@@ -4,8 +4,10 @@
 
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Platforms\MySQLPlatform;
+use Doctrine\DBAL\Schema\Column;
 use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\TransactionIsolationLevel;
+use Doctrine\DBAL\Types\Type;
 use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
 use InvalidArgumentException;
 
@@ -54,4 +56,11 @@ public function testCollateOptionIsStillSupportedButDeprecated(): void
             $this->platform->getCreateTableSQL($table)[0]
         );
     }
+
+    public function testOmittingTheCharsetIsDeprecated(): void
+    {
+        $table = new Table('a_table', [new Column('a_column', Type::getType('string'))]);
+        $this->expectDeprecationWithIdentifier('https://github.com/doctrine/dbal/issues/5278');
+        $this->platform->getCreateTableSQL($table);
+    }
 }