Deprecate "collate" default table option

"collation" is what is expected now on the DBAL side.
doctrine · Feb 14, 2022 · 04e73d1 · 04e73d1
1 parent 1b75234
commit 04e73d1
Show file tree

Hide file tree

Showing 8 changed files with 43 additions and 8 deletions.
diff --git a/ConnectionFactory.php b/ConnectionFactory.php
@@ -11,6 +11,7 @@
 use Doctrine\DBAL\Exception\DriverException;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Types\Type;
+use Doctrine\Deprecations\Deprecation;
 
 use function array_merge;
 use function defined;
@@ -86,6 +87,11 @@ public function createConnection(array $params, ?Configuration $config = null, ?
                        after dropping support for doctrine/dbal 2, since this
                        package requires doctrine/dbal 3.3.2 or higher. */
                     if (isset($params['defaultTableOptions']['collate']) && defined('Doctrine\DBAL\Connection::PARAM_ASCII_STR_ARRAY')) {
+                        Deprecation::trigger(
+                            'doctrine/doctrine-bundle',
+                            'https://github.com/doctrine/dbal/issues/5214',
+                            'The "collate" default table option is deprecated in favor of "collation" and will be removed in doctrine/doctrine-bundle 3.0. '
+                        );
                         $params['defaultTableOptions']['collation'] = $params['defaultTableOptions']['collate'];
                         unset($params['defaultTableOptions']['collate']);
                     }

diff --git a/DependencyInjection/Configuration.php b/DependencyInjection/Configuration.php
@@ -22,6 +22,7 @@
 use function class_exists;
 use function constant;
 use function count;
+use function defined;
 use function implode;
 use function in_array;
 use function is_array;
@@ -143,6 +144,10 @@ private function getDbalConnectionsNode(): ArrayNodeDefinition
 
         $this->configureDbalDriverNode($connectionNode);
 
+        $collationKey = defined('Doctrine\DBAL\Connection::PARAM_ASCII_STR_ARRAY')
+            ? 'collate'
+            : 'collation';
+
         $connectionNode
             ->fixXmlConfig('option')
             ->fixXmlConfig('mapping_type')
@@ -186,7 +191,10 @@ private function getDbalConnectionsNode(): ArrayNodeDefinition
                     ->prototype('scalar')->end()
                 ->end()
                 ->arrayNode('default_table_options')
-                    ->info("This option is used by the schema-tool and affects generated SQL. Possible keys include 'charset','collate', and 'engine'.")
+                ->info(sprintf(
+                    "This option is used by the schema-tool and affects generated SQL. Possible keys include 'charset','%s', and 'engine'.",
+                    $collationKey
+                ))
                     ->useAttributeAsKey('name')
                     ->prototype('scalar')->end()
                 ->end()

diff --git a/Resources/doc/configuration.rst b/Resources/doc/configuration.rst
@@ -133,7 +133,8 @@ Configuration Reference
                             # Affects schema-tool. If absent, DBAL chooses defaults
                             # based on the platform. Examples here are for MySQL.
                             # charset:      utf8
-                            # collate:      utf8_unicode_ci
+                            # collate:      utf8_unicode_ci # When using doctrine/dbal 2.x
+                            # collation:    utf8_unicode_ci # When using doctrine/dbal 3.x
                             # engine:       InnoDB
 
                         replicas:
@@ -486,7 +487,10 @@ Configuration Reference
 
                         <!-- example -->
                         <doctrine:default-table-option name="charset">utf8</doctrine:default-table-option>
+                        <!-- when using doctrine/dbal 2.x -->
                         <doctrine:default-table-option name="collate">utf8_unicode_ci</doctrine:default-table-option>
+                        <!-- when using doctrine/dbal 3.x -->
+                        <doctrine:default-table-option name="collation">utf8_unicode_ci</doctrine:default-table-option>
                         <doctrine:default-table-option name="engine">InnoDB</doctrine:default-table-option>
 
                         <!-- example -->
@@ -972,7 +976,8 @@ can configure. The following block shows all possible configuration keys:
                     # Affects schema-tool. If absent, DBAL chooses defaults
                     # based on the platform.
                     charset:              utf8
-                    collate:              utf8_unicode_ci
+                    collate:              utf8_unicode_ci # when using doctrine/dbal 2.x
+                    collation:            utf8_unicode_ci # when using doctrine/dbal 3.x
                     engine:               InnoDB
 
     .. code-block:: xml
@@ -1057,7 +1062,10 @@ can configure. The following block shows all possible configuration keys:
                     <doctrine:option key="foo">bar</doctrine:option>
                     <doctrine:mapping-type name="enum">string</doctrine:mapping-type>
                     <doctrine:default-table-option name="charset">utf8</doctrine:default-table-option>
+                    <!-- when using doctrine/dbal 2.x -->
                     <doctrine:default-table-option name="collate">utf8_unicode_ci</doctrine:default-table-option>
+                    <!-- when using doctrine/dbal 3.x -->
+                    <doctrine:default-table-option name="collation">utf8_unicode_ci</doctrine:default-table-option>
                     <doctrine:default-table-option name="engine">InnoDB</doctrine:default-table-option>
                     <doctrine:type name="custom">Acme\HelloBundle\MyCustomType</doctrine:type>
                 </doctrine:dbal>

diff --git a/Tests/ConnectionFactoryTest.php b/Tests/ConnectionFactoryTest.php
@@ -14,6 +14,7 @@
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 use Doctrine\DBAL\Platforms\MySQLPlatform;
 use Doctrine\DBAL\Schema\AbstractSchemaManager;
+use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
 use Exception;
 use Throwable;
 
@@ -27,6 +28,8 @@ class_exists(\Doctrine\DBAL\Platforms\MySqlPlatform::class);
 
 class ConnectionFactoryTest extends TestCase
 {
+    use VerifyDeprecations;
+
     public function testContainer(): void
     {
         $typesConfig  = [];
@@ -118,7 +121,10 @@ public function testCollateMapsToCollationForMySql(): void
             self::markTestSkipped('This test is only relevant for DBAL >= 3.3');
         }
 
-        $factory    = new ConnectionFactory([]);
+        $factory = new ConnectionFactory([]);
+        $this->expectDeprecationWithIdentifier(
+            'https://github.com/doctrine/dbal/issues/5214'
+        );
         $connection = $factory->createConnection([
             'driver' => 'pdo_mysql',
             'defaultTableOptions' => ['collate' => 'my_collation'],

diff --git a/Tests/DependencyInjection/AbstractDoctrineExtensionTest.php b/Tests/DependencyInjection/AbstractDoctrineExtensionTest.php
@@ -618,11 +618,11 @@ public function testSingleEntityManagerDefaultTableOptions(): void
         $defaults = $param['defaultTableOptions'];
 
         $this->assertArrayHasKey('charset', $defaults);
-        $this->assertArrayHasKey('collate', $defaults);
+        $this->assertArrayHasKey('collation', $defaults);
         $this->assertArrayHasKey('engine', $defaults);
 
         $this->assertEquals('utf8mb4', $defaults['charset']);
-        $this->assertEquals('utf8mb4_unicode_ci', $defaults['collate']);
+        $this->assertEquals('utf8mb4_unicode_ci', $defaults['collation']);
         $this->assertEquals('InnoDB', $defaults['engine']);
     }
 

diff --git a/Tests/DependencyInjection/Fixtures/config/xml/orm_single_em_default_table_options.xml b/Tests/DependencyInjection/Fixtures/config/xml/orm_single_em_default_table_options.xml
@@ -10,7 +10,7 @@
         <dbal default-connection="default">
             <connection name="default" dbname="db">
                 <default-table-option name="charset">utf8mb4</default-table-option>
-                <default-table-option name="collate">utf8mb4_unicode_ci</default-table-option>
+                <default-table-option name="collation">utf8mb4_unicode_ci</default-table-option>
                 <default-table-option name="engine">InnoDB</default-table-option>
             </connection>
         </dbal>

diff --git a/Tests/DependencyInjection/Fixtures/config/yml/orm_single_em_default_table_options.yml b/Tests/DependencyInjection/Fixtures/config/yml/orm_single_em_default_table_options.yml
@@ -6,7 +6,7 @@ doctrine:
                 dbname: db
                 default_table_options:
                   charset:      utf8mb4
-                  collate:      utf8mb4_unicode_ci
+                  collation:    utf8mb4_unicode_ci
                   engine:       InnoDB
 
     orm:

diff --git a/UPGRADE-2.6.md b/UPGRADE-2.6.md
@@ -0,0 +1,7 @@
+UPGRADE FROM 2.5 to 2.6
+=======================
+
+Configuration
+-------------
+ * The `collate` default table option is deprecated in favor of `collation`
+