Deprecate custom schema options

UPGRADE.md

@@ -8,6 +8,21 @@ awareness about deprecated code.
 
 # Upgrade to 3.4
 
+## Deprecated custom schema options.
+
+Custom schema options have been deprecated since they effectively duplicate the functionality of platform options.
+
+The following `Column` class properties and methods have been deprecated:
+
+- `$_customSchemaOptions`,
+- `setCustomSchemaOption()`,
+- `hasCustomSchemaOption()`,
+- `getCustomSchemaOption()`,
+- `setCustomSchemaOptions()`,
+- `getCustomSchemaOptions()`.
+
+Use platform options instead.
+
 ## Deprecated `array` and `object` column types.
 
 The `array` and `object` column types have been deprecated since they use PHP built-in serialization. Without additional

psalm.xml.dist

@@ -337,6 +337,13 @@
                     TODO: remove in 4.0.0
                 -->
                 <referencedMethod name="Doctrine\DBAL\Driver::getSchemaManager"/>
+                <!--
+                    TODO: remove in 4.0.0
+                -->
+                <referencedMethod name="Doctrine\DBAL\Schema\Column::getCustomSchemaOption"/>
+                <referencedMethod name="Doctrine\DBAL\Schema\Column::getCustomSchemaOptions"/>
+                <referencedMethod name="Doctrine\DBAL\Schema\Column::hasCustomSchemaOption"/>
+                <referencedMethod name="Doctrine\DBAL\Schema\Column::setCustomSchemaOption"/>
             </errorLevel>
         </DeprecatedMethod>
         <DeprecatedProperty>
@@ -362,6 +369,10 @@
                     TODO: remove in 4.0.0
                 -->
                 <referencedProperty name="Doctrine\DBAL\Platforms\AbstractPlatform::$doctrineTypeComments"/>
+                <!--
+                    TODO: remove in 4.0.0
+                -->
+                <referencedProperty name="Doctrine\DBAL\Schema\Column::$_customSchemaOptions"/>
             </errorLevel>
         </DeprecatedProperty>
         <DocblockTypeContradiction>

src/Schema/Column.php

@@ -4,6 +4,7 @@
 
 use Doctrine\DBAL\Schema\Exception\UnknownColumnOption;
 use Doctrine\DBAL\Types\Type;
+use Doctrine\Deprecations\Deprecation;
 
 use function array_merge;
 use function is_numeric;
@@ -50,7 +51,11 @@ class Column extends AbstractAsset
     /** @var string|null */
     protected $_comment;
 
-    /** @var mixed[] */
+    /**
+     * @deprecated Use {@link $_platformOptions instead}
+     *
+     * @var mixed[]
+     */
     protected $_customSchemaOptions = [];
 
     /**
@@ -374,55 +379,95 @@ public function getComment()
     }
 
     /**
+     * @deprecated Use {@link setPlatformOption() instead}
+     *
      * @param string $name
      * @param mixed  $value
      *
      * @return Column
      */
     public function setCustomSchemaOption($name, $value)
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/5476',
+            'Column::setCustomSchemaOption() is deprecated. Use setPlatformOption() instead.'
+        );
+
         $this->_customSchemaOptions[$name] = $value;
 
         return $this;
     }
 
     /**
+     * @deprecated Use {@link hasPlatformOption() instead}
+     *
      * @param string $name
      *
      * @return bool
      */
     public function hasCustomSchemaOption($name)
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/5476',
+            'Column::hasCustomSchemaOption() is deprecated. Use hasPlatformOption() instead.'
+        );
+
         return isset($this->_customSchemaOptions[$name]);
     }
 
     /**
+     * @deprecated Use {@link getPlatformOption() instead}
+     *
      * @param string $name
      *
      * @return mixed
      */
     public function getCustomSchemaOption($name)
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/5476',
+            'Column::getCustomSchemaOption() is deprecated. Use getPlatformOption() instead.'
+        );
+
         return $this->_customSchemaOptions[$name];
     }
 
     /**
+     * @deprecated Use {@link setPlatformOptions() instead}
+     *
      * @param mixed[] $customSchemaOptions
      *
      * @return Column
      */
     public function setCustomSchemaOptions(array $customSchemaOptions)
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/5476',
+            'Column::setCustomSchemaOptions() is deprecated. Use setPlatformOptions() instead.'
+        );
+
         $this->_customSchemaOptions = $customSchemaOptions;
 
         return $this;
     }
 
     /**
+     * @deprecated Use {@link getPlatformOptions() instead}
+     *
      * @return mixed[]
      */
     public function getCustomSchemaOptions()
     {
+        Deprecation::trigger(
+            'doctrine/dbal',
+            'https://github.com/doctrine/dbal/pull/5476',
+            'Column::getCustomSchemaOptions() is deprecated. Use getPlatformOptions() instead.'
+        );
+
         return $this->_customSchemaOptions;
     }