Deprecated usage of binary fields whose length exceeds the platform maximum

Closes #3187.

UPGRADE.md

 # Upgrade to 2.8
 
+## Deprecated usage of binary fields whose length exceeds the platform maximum
+
+- The usage of binary fields whose length exceeds the maximum field size on a given platform is deprecated.
+  Use binary fields of a size which fits all target platforms, or use blob explicitly instead.
+
 ## Removed dependency on doctrine/common
 
 The dependency on doctrine/common package has been removed.

lib/Doctrine/DBAL/Platforms/AbstractPlatform.php

@@ -42,6 +42,7 @@ use Doctrine\DBAL\Schema\TableDiff;
 use Doctrine\DBAL\TransactionIsolationLevel;
 use Doctrine\DBAL\Types;
 use Doctrine\DBAL\Types\Type;
+use const E_USER_DEPRECATED;
 use function addcslashes;
 use function array_map;
 use function array_merge;
@@ -68,6 +69,7 @@ use function strlen;
 use function strpos;
 use function strtolower;
 use function strtoupper;
+use function trigger_error;
 
 /**
  * Base class for all DatabasePlatforms. The DatabasePlatforms are the central
@@ -325,7 +327,17 @@ abstract class AbstractPlatform
 
         $fixed = $field['fixed'] ?? false;
 
-        if ($field['length'] > $this->getBinaryMaxLength()) {
+        $maxLength = $this->getBinaryMaxLength();
+
+        if ($field['length'] > $maxLength) {
+            if ($maxLength > 0) {
+                @trigger_error(sprintf(
+                    'Binary field length %d is greater than supported by the platform (%d)',
+                    $field['length'],
+                    $maxLength
+                ), E_USER_DEPRECATED);
+            }
+
             return $this->getBlobTypeDeclarationSQL($field);
         }
 

tests/Doctrine/Tests/DBAL/Platforms/AbstractMySQLPlatformTestCase.php

@@ -519,16 +519,27 @@ abstract class AbstractMySQLPlatformTestCase extends AbstractPlatformTestCase
         self::assertSame('VARBINARY(255)', $this->_platform->getBinaryTypeDeclarationSQL(array()));
         self::assertSame('VARBINARY(255)', $this->_platform->getBinaryTypeDeclarationSQL(array('length' => 0)));
         self::assertSame('VARBINARY(65535)', $this->_platform->getBinaryTypeDeclarationSQL(array('length' => 65535)));
-        self::assertSame('MEDIUMBLOB', $this->_platform->getBinaryTypeDeclarationSQL(array('length' => 65536)));
-        self::assertSame('MEDIUMBLOB', $this->_platform->getBinaryTypeDeclarationSQL(array('length' => 16777215)));
-        self::assertSame('LONGBLOB', $this->_platform->getBinaryTypeDeclarationSQL(array('length' => 16777216)));
 
         self::assertSame('BINARY(255)', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true)));
         self::assertSame('BINARY(255)', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true, 'length' => 0)));
         self::assertSame('BINARY(65535)', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true, 'length' => 65535)));
-        self::assertSame('MEDIUMBLOB', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true, 'length' => 65536)));
-        self::assertSame('MEDIUMBLOB', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true, 'length' => 16777215)));
-        self::assertSame('LONGBLOB', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true, 'length' => 16777216)));
+    }
+
+    /**
+     * @group legacy
+     * @expectedDeprecation Binary field length 65536 is greater than supported by the platform (65535)
+     * @expectedDeprecation Binary field length 16777215 is greater than supported by the platform (65535)
+     * @expectedDeprecation Binary field length 16777216 is greater than supported by the platform (65535)
+     */
+    public function testReturnsBinaryTypeLongerThanMaxDeclarationSQL()
+    {
+        self::assertSame('MEDIUMBLOB', $this->_platform->getBinaryTypeDeclarationSQL(['length' => 65536]));
+        self::assertSame('MEDIUMBLOB', $this->_platform->getBinaryTypeDeclarationSQL(['length' => 16777215]));
+        self::assertSame('LONGBLOB', $this->_platform->getBinaryTypeDeclarationSQL(['length' => 16777216]));
+
+        self::assertSame('MEDIUMBLOB', $this->_platform->getBinaryTypeDeclarationSQL(['fixed' => true, 'length' => 65536]));
+        self::assertSame('MEDIUMBLOB', $this->_platform->getBinaryTypeDeclarationSQL(['fixed' => true, 'length' => 16777215]));
+        self::assertSame('LONGBLOB', $this->_platform->getBinaryTypeDeclarationSQL(['fixed' => true, 'length' => 16777216]));
     }
 
     public function testDoesNotPropagateForeignKeyCreationForNonSupportingEngines()

tests/Doctrine/Tests/DBAL/Platforms/AbstractPlatformTestCase.php

@@ -830,6 +830,11 @@ abstract class AbstractPlatformTestCase extends \Doctrine\Tests\DbalTestCase
         $this->_platform->getBinaryTypeDeclarationSQL(array());
     }
 
+    public function testReturnsBinaryTypeLongerThanMaxDeclarationSQL()
+    {
+        $this->markTestSkipped('Not applicable to the platform');
+    }
+
     /**
      * @group DBAL-553
      */

tests/Doctrine/Tests/DBAL/Platforms/AbstractSQLServerPlatformTestCase.php

@@ -981,12 +981,20 @@ abstract class AbstractSQLServerPlatformTestCase extends AbstractPlatformTestCas
         self::assertSame('VARBINARY(255)', $this->_platform->getBinaryTypeDeclarationSQL(array()));
         self::assertSame('VARBINARY(255)', $this->_platform->getBinaryTypeDeclarationSQL(array('length' => 0)));
         self::assertSame('VARBINARY(8000)', $this->_platform->getBinaryTypeDeclarationSQL(array('length' => 8000)));
-        self::assertSame('VARBINARY(MAX)', $this->_platform->getBinaryTypeDeclarationSQL(array('length' => 8001)));
 
         self::assertSame('BINARY(255)', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true)));
         self::assertSame('BINARY(255)', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true, 'length' => 0)));
         self::assertSame('BINARY(8000)', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true, 'length' => 8000)));
-        self::assertSame('VARBINARY(MAX)', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true, 'length' => 8001)));
+    }
+
+    /**
+     * @group legacy
+     * @expectedDeprecation Binary field length 8001 is greater than supported by the platform (8000)
+     */
+    public function testReturnsBinaryTypeLongerThanMaxDeclarationSQL()
+    {
+        self::assertSame('VARBINARY(MAX)', $this->_platform->getBinaryTypeDeclarationSQL(['length' => 8001]));
+        self::assertSame('VARBINARY(MAX)', $this->_platform->getBinaryTypeDeclarationSQL(['fixed' => true, 'length' => 8001]));
     }
 
     /**

tests/Doctrine/Tests/DBAL/Platforms/DB2PlatformTest.php

@@ -422,10 +422,18 @@ class DB2PlatformTest extends AbstractPlatformTestCase
         self::assertSame('VARCHAR(1) FOR BIT DATA', $this->_platform->getBinaryTypeDeclarationSQL([]));
         self::assertSame('VARCHAR(255) FOR BIT DATA', $this->_platform->getBinaryTypeDeclarationSQL(['length' => 0]));
         self::assertSame('VARCHAR(32704) FOR BIT DATA', $this->_platform->getBinaryTypeDeclarationSQL(['length' => 32704]));
-        self::assertSame('BLOB(1M)', $this->_platform->getBinaryTypeDeclarationSQL(['length' => 32705]));
 
         self::assertSame('CHAR(1) FOR BIT DATA', $this->_platform->getBinaryTypeDeclarationSQL(['fixed' => true]));
         self::assertSame('CHAR(254) FOR BIT DATA', $this->_platform->getBinaryTypeDeclarationSQL(['fixed' => true, 'length' => 0]));
+    }
+
+    /**
+     * @group legacy
+     * @expectedDeprecation Binary field length 32705 is greater than supported by the platform (32704)
+     */
+    public function testReturnsBinaryTypeLongerThanMaxDeclarationSQL()
+    {
+        self::assertSame('BLOB(1M)', $this->_platform->getBinaryTypeDeclarationSQL(['length' => 32705]));
         self::assertSame('BLOB(1M)', $this->_platform->getBinaryTypeDeclarationSQL(['fixed' => true, 'length' => 32705]));
     }
 

tests/Doctrine/Tests/DBAL/Platforms/OraclePlatformTest.php

@@ -446,12 +446,20 @@ class OraclePlatformTest extends AbstractPlatformTestCase
         self::assertSame('RAW(255)', $this->_platform->getBinaryTypeDeclarationSQL(array()));
         self::assertSame('RAW(2000)', $this->_platform->getBinaryTypeDeclarationSQL(array('length' => 0)));
         self::assertSame('RAW(2000)', $this->_platform->getBinaryTypeDeclarationSQL(array('length' => 2000)));
-        self::assertSame('BLOB', $this->_platform->getBinaryTypeDeclarationSQL(array('length' => 2001)));
 
         self::assertSame('RAW(255)', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true)));
         self::assertSame('RAW(2000)', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true, 'length' => 0)));
         self::assertSame('RAW(2000)', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true, 'length' => 2000)));
-        self::assertSame('BLOB', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true, 'length' => 2001)));
+    }
+
+    /**
+     * @group legacy
+     * @expectedDeprecation Binary field length 2001 is greater than supported by the platform (2000)
+     */
+    public function testReturnsBinaryTypeLongerThanMaxDeclarationSQL()
+    {
+        self::assertSame('BLOB', $this->_platform->getBinaryTypeDeclarationSQL(['length' => 2001]));
+        self::assertSame('BLOB', $this->_platform->getBinaryTypeDeclarationSQL(['fixed' => true, 'length' => 2001]));
     }
 
     public function testDoesNotPropagateUnnecessaryTableAlterationOnBinaryType()

tests/Doctrine/Tests/DBAL/Platforms/SQLAnywherePlatformTest.php

@@ -791,12 +791,20 @@ class SQLAnywherePlatformTest extends AbstractPlatformTestCase
         self::assertSame('VARBINARY(1)', $this->_platform->getBinaryTypeDeclarationSQL(array()));
         self::assertSame('VARBINARY(1)', $this->_platform->getBinaryTypeDeclarationSQL(array('length' => 0)));
         self::assertSame('VARBINARY(32767)', $this->_platform->getBinaryTypeDeclarationSQL(array('length' => 32767)));
-        self::assertSame('LONG BINARY', $this->_platform->getBinaryTypeDeclarationSQL(array('length' => 32768)));
 
         self::assertSame('BINARY(1)', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true)));
         self::assertSame('BINARY(1)', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true, 'length' => 0)));
         self::assertSame('BINARY(32767)', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true, 'length' => 32767)));
-        self::assertSame('LONG BINARY', $this->_platform->getBinaryTypeDeclarationSQL(array('fixed' => true, 'length' => 32768)));
+    }
+
+    /**
+     * @group legacy
+     * @expectedDeprecation Binary field length 32768 is greater than supported by the platform (32767)
+     */
+    public function testReturnsBinaryTypeLongerThanMaxDeclarationSQL()
+    {
+        self::assertSame('LONG BINARY', $this->_platform->getBinaryTypeDeclarationSQL(['length' => 32768]));
+        self::assertSame('LONG BINARY', $this->_platform->getBinaryTypeDeclarationSQL(['fixed' => true, 'length' => 32768]));
     }
 
     /**