doctrine · morozov · Sep 18, 2020 · Sep 14, 2020
diff --git a/docs/en/reference/types.rst b/docs/en/reference/types.rst
@@ -157,6 +157,13 @@ or ``null`` if no data is present.
     This can lead to type inconsistencies when reverse engineering the
     type from the database.
 
+ascii_string
+++++++++++++
+
+Similar to the ``string`` type but for binding non-unicode data. This type
+should be used with database vendors where a binding type mismatch
+can trigger an implicit cast and lead to performance problems.
+
 text
 ++++
 
@@ -607,6 +614,9 @@ Please also notice the mapping specific footnotes for additional information.
 |                   |               |                          |         +----------------------------------------------------------+
 |                   |               |                          |         | ``NCHAR(n)`` [4]_                                        |
 +-------------------+---------------+--------------------------+---------+----------------------------------------------------------+
+| **ascii_string**  | ``string``    | **SQL Server**           |         | ``VARCHAR(n)``                                           |
+|                   |               |                          |         | ``CHAR(n)``                                              |
++-------------------+---------------+--------------------------+---------+----------------------------------------------------------+
 | **text**          | ``string``    | **MySQL**                | *all*   | ``TINYTEXT`` [17]_                                       |
 |                   |               |                          |         +----------------------------------------------------------+
 |                   |               |                          |         | ``TEXT`` [18]_                                           |

diff --git a/lib/Doctrine/DBAL/Driver/Mysqli/MysqliStatement.php b/lib/Doctrine/DBAL/Driver/Mysqli/MysqliStatement.php
@@ -38,6 +38,7 @@ class MysqliStatement implements IteratorAggregate, StatementInterface, Result
 {
     /** @var string[] */
     protected static $_paramTypeMap = [
+        ParameterType::ASCII        => 's',
         ParameterType::STRING       => 's',
         ParameterType::BINARY       => 's',
         ParameterType::BOOLEAN      => 'i',

diff --git a/lib/Doctrine/DBAL/Driver/PDOSqlsrv/Statement.php b/lib/Doctrine/DBAL/Driver/PDOSqlsrv/Statement.php
@@ -17,11 +17,20 @@ class Statement extends PDO\Statement
      */
     public function bindParam($param, &$variable, $type = ParameterType::STRING, $length = null, $driverOptions = null)
     {
-        if (
-            ($type === ParameterType::LARGE_OBJECT || $type === ParameterType::BINARY)
-            && $driverOptions === null
-        ) {
-            $driverOptions = \PDO::SQLSRV_ENCODING_BINARY;
+        switch ($type) {
+            case ParameterType::LARGE_OBJECT:
+            case ParameterType::BINARY:
+                if ($driverOptions === null) {
+                    $driverOptions = \PDO::SQLSRV_ENCODING_BINARY;
+                }
+
+                break;
+
+            case ParameterType::ASCII:
+                $type          = ParameterType::STRING;
+                $length        = 0;
+                $driverOptions = \PDO::SQLSRV_ENCODING_SYSTEM;
+                break;
         }
 
         return parent::bindParam($param, $variable, $type, $length, $driverOptions);

diff --git a/lib/Doctrine/DBAL/Driver/PDOStatement.php b/lib/Doctrine/DBAL/Driver/PDOStatement.php
@@ -30,6 +30,7 @@ class PDOStatement extends \PDOStatement implements StatementInterface, Result
         ParameterType::NULL         => PDO::PARAM_NULL,
         ParameterType::INTEGER      => PDO::PARAM_INT,
         ParameterType::STRING       => PDO::PARAM_STR,
+        ParameterType::ASCII        => PDO::PARAM_STR,
         ParameterType::BINARY       => PDO::PARAM_LOB,
         ParameterType::LARGE_OBJECT => PDO::PARAM_LOB,
         ParameterType::BOOLEAN      => PDO::PARAM_BOOL,

diff --git a/lib/Doctrine/DBAL/Driver/SQLSrv/SQLSrvStatement.php b/lib/Doctrine/DBAL/Driver/SQLSrv/SQLSrvStatement.php
@@ -34,6 +34,7 @@
 use function stripos;
 
 use const SQLSRV_ENC_BINARY;
+use const SQLSRV_ENC_CHAR;
 use const SQLSRV_ERR_ERRORS;
 use const SQLSRV_FETCH_ASSOC;
 use const SQLSRV_FETCH_BOTH;
@@ -306,6 +307,14 @@ private function prepare()
                     ];
                     break;
 
+                case ParameterType::ASCII:
+                    $params[$column - 1] = [
+                        &$variable,
+                        SQLSRV_PARAM_IN,
+                        SQLSRV_PHPTYPE_STRING(SQLSRV_ENC_CHAR),
+                    ];
+                    break;
+
                 default:
                     $params[$column - 1] =& $variable;
                     break;

diff --git a/lib/Doctrine/DBAL/ParameterType.php b/lib/Doctrine/DBAL/ParameterType.php
@@ -49,6 +49,11 @@ final class ParameterType
      */
     public const BINARY = 16;
 
+    /**
+     * Represents an ASCII string data type
+     */
+    public const ASCII = 17;
+
     /**
      * This class cannot be instantiated.
      *

diff --git a/lib/Doctrine/DBAL/Platforms/AbstractPlatform.php b/lib/Doctrine/DBAL/Platforms/AbstractPlatform.php
@@ -245,6 +245,17 @@ private function initializeAllDoctrineTypeMappings()
         }
     }
 
+    /**
+     * Returns the SQL snippet used to declare a column that can
+     * store characters in the ASCII character set
+     *
+     * @param mixed[] $column
+     */
+    public function getAsciiStringTypeDeclarationSQL(array $column): string
+    {
+        return $this->getVarcharTypeDeclarationSQL($column);
+    }
+
     /**
      * Returns the SQL snippet used to declare a VARCHAR column type.
      *

diff --git a/lib/Doctrine/DBAL/Platforms/SQLServerPlatform.php b/lib/Doctrine/DBAL/Platforms/SQLServerPlatform.php
@@ -1191,6 +1191,20 @@ public function getGuidTypeDeclarationSQL(array $column)
         return 'UNIQUEIDENTIFIER';
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    public function getAsciiStringTypeDeclarationSQL(array $column): string
+    {
+        $length = $column['length'] ?? null;
+
+        if (! isset($column['fixed'])) {
+            return sprintf('VARCHAR(%d)', $length);
+        }
+
+        return sprintf('CHAR(%d)', $length);
+    }
+
     /**
      * {@inheritDoc}
      */

diff --git a/lib/Doctrine/DBAL/Types/AsciiStringType.php b/lib/Doctrine/DBAL/Types/AsciiStringType.php
@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Types;
+
+use Doctrine\DBAL\ParameterType;
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+
+final class AsciiStringType extends StringType
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getSQLDeclaration(array $column, AbstractPlatform $platform)
+    {
+        return $platform->getAsciiStringTypeDeclarationSQL($column);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getBindingType()
+    {
+        return ParameterType::ASCII;
+    }
+
+    public function getName(): string
+    {
+        return Types::ASCII_STRING;
+    }
+}
diff --git a/lib/Doctrine/DBAL/Types/Type.php b/lib/Doctrine/DBAL/Types/Type.php
@@ -99,6 +99,7 @@ abstract class Type
      */
     private const BUILTIN_TYPES_MAP = [
         Types::ARRAY                => ArrayType::class,
+        Types::ASCII_STRING         => AsciiStringType::class,
         Types::BIGINT               => BigIntType::class,
         Types::BINARY               => BinaryType::class,
         Types::BLOB                 => BlobType::class,

diff --git a/lib/Doctrine/DBAL/Types/Types.php b/lib/Doctrine/DBAL/Types/Types.php
@@ -10,6 +10,7 @@
 final class Types
 {
     public const ARRAY                = 'array';
+    public const ASCII_STRING         = 'ascii_string';
     public const BIGINT               = 'bigint';
     public const BINARY               = 'binary';
     public const BLOB                 = 'blob';

diff --git a/tests/Doctrine/Tests/DBAL/Functional/ParameterTypes/AsciiTest.php b/tests/Doctrine/Tests/DBAL/Functional/ParameterTypes/AsciiTest.php
@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Tests\DBAL\Functional\ParameterTypes;
+
+use Doctrine\DBAL\Driver\AbstractSQLServerDriver;
+use Doctrine\DBAL\ParameterType;
+use Doctrine\Tests\DbalFunctionalTestCase;
+
+class AsciiTest extends DbalFunctionalTestCase
+{
+    public function testAsciiBinding(): void
+    {
+        if (! $this->connection->getDriver() instanceof AbstractSQLServerDriver) {
+            self::markTestSkipped('Driver does not support ascii string binding');
+        }
+
+        $statement = $this->connection->prepare('SELECT sql_variant_property(?, \'BaseType\')');
+
+        $statement->bindValue(1, 'test', ParameterType::ASCII);
+        $statement->execute();
+
+        $results = $statement->fetchOne();
+
+        self::assertEquals('varchar', $results);
+    }
+}
diff --git a/tests/Doctrine/Tests/DBAL/Functional/Types/AsciiStringTest.php b/tests/Doctrine/Tests/DBAL/Functional/Types/AsciiStringTest.php
@@ -0,0 +1,70 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Tests\DBAL\Functional\Types;
+
+use Doctrine\DBAL\ParameterType;
+use Doctrine\DBAL\Schema\Table;
+use Doctrine\Tests\DbalFunctionalTestCase;
+
+class AsciiStringTest extends DbalFunctionalTestCase
+{
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $table = new Table('ascii_table');
+        $table->addColumn('id', 'ascii_string', [
+            'length' => 3,
+            'fixed' => true,
+        ]);
+
+        $table->addColumn('val', 'ascii_string', ['length' => 4]);
+        $table->setPrimaryKey(['id']);
+
+        $sm = $this->connection->getSchemaManager();
+        $sm->dropAndCreateTable($table);
+    }
+
+    public function testInsertAndSelect(): void
+    {
+        $id1 = 'id1';
+        $id2 = 'id2';
+
+        $value1 = 'val1';
+        $value2 = 'val2';
+
+        $this->insert($id1, $value1);
+        $this->insert($id2, $value2);
+
+        self::assertSame($value1, $this->select($id1));
+        self::assertSame($value2, $this->select($id2));
+    }
+
+    private function insert(string $id, string $value): void
+    {
+        $result = $this->connection->insert('ascii_table', [
+            'id'  => $id,
+            'val' => $value,
+        ], [
+            ParameterType::ASCII,
+            ParameterType::ASCII,
+        ]);
+
+        self::assertSame(1, $result);
+    }
+
+    private function select(string $id): string
+    {
+        $value = $this->connection->fetchOne(
+            'SELECT val FROM ascii_table WHERE id = ?',
+            [$id],
+            [ParameterType::ASCII]
+        );
+
+        self::assertIsString($value);
+
+        return $value;
+    }
+}
diff --git a/tests/Doctrine/Tests/DBAL/Platforms/AbstractPlatformTestCase.php b/tests/Doctrine/Tests/DBAL/Platforms/AbstractPlatformTestCase.php
@@ -1443,6 +1443,28 @@ public function testZeroOffsetWithoutLimitIsIgnored(): void
             $this->platform->modifyLimitQuery($query, null, 0)
         );
     }
+
+    /**
+     * @param array<string, mixed> $column
+     *
+     * @dataProvider asciiStringSqlDeclarationDataProvider
+     */
+    public function testAsciiSQLDeclaration(string $expectedSql, array $column): void
+    {
+        $declarationSql = $this->platform->getAsciiStringTypeDeclarationSQL($column);
+        self::assertEquals($expectedSql, $declarationSql);
+    }
+
+    /**
+     * @return array<int, array{string, array<string, mixed>}>
+     */
+    public function asciiStringSqlDeclarationDataProvider(): array
+    {
+        return [
+            ['VARCHAR(12)', ['length' => 12]],
+            ['CHAR(12)', ['length' => 12, 'fixed' => true]],
+        ];
+    }
 }
 
 interface GetCreateTableSqlDispatchEventListener

diff --git a/tests/Doctrine/Tests/DBAL/Platforms/OraclePlatformTest.php b/tests/Doctrine/Tests/DBAL/Platforms/OraclePlatformTest.php
@@ -976,4 +976,15 @@ public function testQuotesDatabaseNameInListTableColumnsSQL(): void
             $this->platform->getListTableColumnsSQL('foo_table', "Foo'Bar\\")
         );
     }
+
+    /**
+     * @return array<int, array{string, array<string, mixed>}>
+     */
+    public function asciiStringSqlDeclarationDataProvider(): array
+    {
+        return [
+            ['VARCHAR2(12)', ['length' => 12]],
+            ['CHAR(12)', ['length' => 12, 'fixed' => true]],
+        ];
+    }
 }
diff --git a/tests/Doctrine/Tests/DBAL/Types/AsciiStringTest.php b/tests/Doctrine/Tests/DBAL/Types/AsciiStringTest.php
@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\Tests\DBAL\Types;
+
+use Doctrine\DBAL\ParameterType;
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+use Doctrine\DBAL\Types\AsciiStringType;
+use PHPUnit\Framework\TestCase;
+
+class AsciiStringTest extends TestCase
+{
+    /** @var AsciiStringType */
+    private $type;
+
+    protected function setUp(): void
+    {
+        $this->type = new AsciiStringType();
+    }
+
+    public function testReturnCorrectBindingType(): void
+    {
+        self::assertEquals($this->type->getBindingType(), ParameterType::ASCII);
+    }
+
+    public function testDelegateToPlatformForSqlDeclaration(): void
+    {
+        $columnDefinitions = [
+            [['length' => 12, 'fixed' => true]],
+            [['length' => 14]],
+        ];
+
+        foreach ($columnDefinitions as $column) {
+            $platform = $this->createMock(AbstractPlatform::class);
+            $platform->expects(self::once())
+                ->method('getAsciiStringTypeDeclarationSQL')
+                ->with($column);
+
+            $this->type->getSQLDeclaration($column, $platform);
+        }
+    }
+}