Merge pull request #5204 from greg0ire/deprecate-type-comment-methods

Deprecate methods related to type comments
doctrine · Jan 23, 2022 · b347cdb · b347cdb
2 parents fec83d6 + 9a929bb
commit b347cdb
Show file tree

Hide file tree

Showing 4 changed files with 33 additions and 1 deletion.
diff --git a/UPGRADE.md b/UPGRADE.md
@@ -6,6 +6,14 @@ awareness about deprecated code.
 - Use of our low-overhead runtime deprecation API, details:
   https://github.com/doctrine/deprecations/
 
+# Upgrade to 3.4
+
+# Deprecated `AbstractPlatform::getColumnComment()` and `AbstractPlatform::getDoctrineTypeComment()`
+
+DBAL no longer needs column comments to ensure proper diffing. Note that both
+methods should probably have been marked as internal as these comments were an
+implementation detail of the DBAL.
+
 # Upgrade to 3.3
 
 ## Deprecated `Type::canRequireSQLConversion()`.

diff --git a/docs/en/explanation/dc2type-comments.rst b/docs/en/explanation/dc2type-comments.rst
@@ -47,4 +47,5 @@ no longer the case. They must be kept in order to keep the
 platform-unaware comparison APIs working though.
 
 It is important to note that these comments are an implementation detail
-of the DBAL and should not be relied upon by application code.
+of the DBAL and should not be relied upon by application code. They are
+removed in DBAL 4.0.
diff --git a/psalm.xml.dist b/psalm.xml.dist
@@ -224,6 +224,11 @@
                     See https://github.com/doctrine/dbal/pull/5136
                 -->
                 <referencedMethod name="Doctrine\DBAL\Types\Type::canRequireSQLConversion"/>
+                <!--
+                    TODO: remove in 4.0.0
+                    See https://github.com/doctrine/dbal/pull/5204
+                -->
+                <referencedMethod name="Doctrine\DBAL\Platforms\AbstractPlatform::getColumnComment"/>
             </errorLevel>
         </DeprecatedMethod>
         <DeprecatedProperty>

diff --git a/src/Platforms/AbstractPlatform.php b/src/Platforms/AbstractPlatform.php
@@ -499,20 +499,38 @@ public function markDoctrineTypeCommented($doctrineType)
     /**
      * Gets the comment to append to a column comment that helps parsing this type in reverse engineering.
      *
+     * @deprecated This method will be removed without replacement.
+     *
      * @return string
      */
     public function getDoctrineTypeComment(Type $doctrineType)
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/5107',
+            '%s is deprecated and will be removed in Doctrine DBAL 4.0.',
+            __METHOD__
+        );
+
         return '(DC2Type:' . $doctrineType->getName() . ')';
     }
 
     /**
      * Gets the comment of a passed column modified by potential doctrine type comment hints.
      *
+     * @deprecated This method will be removed without replacement.
+     *
      * @return string|null
      */
     protected function getColumnComment(Column $column)
     {
+        Deprecation::triggerIfCalledFromOutside(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/5107',
+            '%s is deprecated and will be removed in Doctrine DBAL 4.0.',
+            __METHOD__
+        );
+
         $comment = $column->getComment();
 
         if ($column->getType()->requiresSQLCommentHint($this)) {