Deprecate AbstractPlatform commented type APIs

The Type class already has an API for this.
doctrine · Dec 1, 2021 · e88ce6d · e88ce6d
1 parent e4f615a
commit e88ce6d
Show file tree

Hide file tree

Showing 5 changed files with 71 additions and 1 deletion.
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -8,6 +8,19 @@ awareness about deprecated code.
 
 # Upgrade to 3.3
 
+## Deprecated platform "commented type" API
+
+Since `Type::requiresSQLCommentTypeHint()` already allows determining whether a
+type should result in SQL columns with a type hint in their comments, the
+following methods are deprecated:
+
+- `AbstractPlatform::isCommentedDoctrineType()`
+- `AbstractPlatform::initializeCommentedDoctrineTypes()`
+- `AbstractPlatform::markDoctrineTypeCommented()`
+
+The protected property `AbstractPlatform::$doctrineTypeComments` is deprecated
+as well.
+
 ## Deprecated support for Postgres 9
 
 Postgres 9 won't be actively supported in DBAL 4. Consider upgrading to Postgres 10 or later.

diff --git a/psalm.xml.dist b/psalm.xml.dist
@@ -154,6 +154,13 @@
                 <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::getBinaryMaxLength"/>
                 <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::getIsNullExpression"/>
                 <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::getUniqueFieldDeclarationSQL"/>
+                <!--
+                    See https://github.com/doctrine/dbal/pull/5058
+                    TODO: remove in 4.0.0
+                -->
+                <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::isCommentedDoctrineType"/>
+                <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::initializeCommentedDoctrineTypes"/>
+                <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::markedDoctrineTypeCommented"/>
                 <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::supportsAlterTable"/>
                 <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::supportsViews"/>
                 <!--
@@ -224,6 +231,11 @@
                     See https://github.com/doctrine/dbal/pull/4822
                 -->
                 <referencedProperty name="Doctrine\DBAL\Schema\SchemaConfig::$hasExplicitForeignKeyIndexes"/>
+                <!--
+                    See https://github.com/doctrine/dbal/pull/5058
+                    TODO: remove in 4.0.0
+                -->
+                <referencedProperty name="Doctrine\DBAL\Platforms\AbstractPlatform::$doctrineTypeComments"/>
             </errorLevel>
         </DeprecatedProperty>
         <DocblockTypeContradiction>

diff --git a/src/Platforms/AbstractPlatform.php b/src/Platforms/AbstractPlatform.php
@@ -80,6 +80,8 @@ abstract class AbstractPlatform
      * Contains a list of all columns that should generate parseable column comments for type-detection
      * in reverse engineering scenarios.
      *
+     * @deprecated This property is deprecated and will be removed in Doctrine DBAL 4.0.
+     *
      * @var string[]|null
      */
     protected $doctrineTypeComments;
@@ -420,10 +422,19 @@ public function hasDoctrineTypeMappingFor($dbType)
     /**
      * Initializes the Doctrine Type comments instance variable for in_array() checks.
      *
+     * @deprecated This API will be removed in Doctrine DBAL 4.0.
+     *
      * @return void
      */
     protected function initializeCommentedDoctrineTypes()
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/5058',
+            '%s is deprecated and will be removed in Doctrine DBAL 4.0.',
+            __METHOD__
+        );
+
         $this->doctrineTypeComments = [];
 
         foreach (Type::getTypesMap() as $typeName => $className) {
@@ -440,10 +451,19 @@ protected function initializeCommentedDoctrineTypes()
     /**
      * Is it necessary for the platform to add a parsable type comment to allow reverse engineering the given type?
      *
+     * @deprecated Use {@link Type::requiresSQLCommentHint()} instead.
+     *
      * @return bool
      */
     public function isCommentedDoctrineType(Type $doctrineType)
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/5058',
+            '%s is deprecated and will be removed in Doctrine DBAL 4.0. Use Type::requiresSQLCommentHint() instead.',
+            __METHOD__
+        );
+
         if ($this->doctrineTypeComments === null) {
             $this->initializeCommentedDoctrineTypes();
         }
@@ -462,6 +482,13 @@ public function isCommentedDoctrineType(Type $doctrineType)
      */
     public function markDoctrineTypeCommented($doctrineType)
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/5058',
+            '%s is deprecated and will be removed in Doctrine DBAL 4.0. Use Type::requiresSQLCommentHint() instead.',
+            __METHOD__
+        );
+
         if ($this->doctrineTypeComments === null) {
             $this->initializeCommentedDoctrineTypes();
         }
@@ -490,7 +517,7 @@ protected function getColumnComment(Column $column)
     {
         $comment = $column->getComment();
 
-        if ($this->isCommentedDoctrineType($column->getType())) {
+        if ($column->getType()->requiresSQLCommentHint($this)) {
             $comment .= $this->getDoctrineTypeComment($column->getType());
         }
 

diff --git a/src/Platforms/DB2Platform.php b/src/Platforms/DB2Platform.php
@@ -95,6 +95,13 @@ protected function initializeDoctrineTypeMappings()
      */
     public function isCommentedDoctrineType(Type $doctrineType)
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/5058',
+            '%s is deprecated and will be removed in Doctrine DBAL 4.0. Use Type::requiresSQLCommentHint() instead.',
+            __METHOD__
+        );
+
         if ($doctrineType->getName() === Types::BOOLEAN) {
             // We require a commented boolean type in order to distinguish between boolean and smallint
             // as both (have to) map to the same native type.

diff --git a/src/Types/BooleanType.php b/src/Types/BooleanType.php
@@ -4,6 +4,7 @@
 
 use Doctrine\DBAL\ParameterType;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
+use Doctrine\DBAL\Platforms\DB2Platform;
 
 /**
  * Type that maps an SQL boolean to a PHP boolean.
@@ -49,4 +50,14 @@ public function getBindingType()
     {
         return ParameterType::BOOLEAN;
     }
+
+    /**
+     * @return bool
+     */
+    public function requiresSQLCommentHint(AbstractPlatform $platform)
+    {
+        // We require a commented boolean type in order to distinguish between
+        // boolean and smallint as both (have to) map to the same native type.
+        return $platform instanceof DB2Platform;
+    }
 }