Support VARCHAR binding #4263

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
++++++
+
+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
 ++++
 
@@ -583,6 +590,9 @@ Please also notice the mapping specific footnotes for additional information.
 |                   |               |                          |         +----------------------------------------------------------+
 |                   |               |                          |         | ``NCHAR(n)`` [4]_                                        |
 +-------------------+---------------+--------------------------+---------+----------------------------------------------------------+
+| **ascii**         | ``string``    | **SQL Server**           |         | ``VARCHAR(n)``                                           |
+|                   |               |                          |         | ``CHAR(n)``                                              |
++-------------------+---------------+--------------------------+---------+----------------------------------------------------------+
 | **text**          | ``string``    | **MySQL**                | *all*   | ``TINYTEXT`` [16]_                                       |
 |                   |               |                          |         +----------------------------------------------------------+
 |                   |               |                          |         | ``TEXT`` [17]_                                           |

src/Driver/Mysqli/Statement.php

@@ -28,6 +28,7 @@ final class Statement implements StatementInterface
 {
     /** @var string[] */
     protected static $_paramTypeMap = [
+        ParameterType::ASCII_STRING => 's',
         ParameterType::STRING => 's',
         ParameterType::BINARY => 's',
         ParameterType::BOOLEAN => 'i',

src/Driver/PDO/SQLSrv/Statement.php

@@ -28,11 +28,20 @@ public function __construct(PDOStatement $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_STRING:
+                $type          = PDO::PARAM_STR;
+                $length        = 0;
+                $driverOptions = PDO::SQLSRV_ENCODING_SYSTEM;
+                break;
         }
 
         return $this->statement->bindParam($param, $variable, $type, $length, $driverOptions);

src/Driver/PDO/Statement.php

@@ -20,6 +20,7 @@ final class Statement implements StatementInterface
         ParameterType::NULL => PDO::PARAM_NULL,
         ParameterType::INTEGER => PDO::PARAM_INT,
         ParameterType::STRING => PDO::PARAM_STR,
+        ParameterType::ASCII_STRING => PDO::PARAM_STR,
         ParameterType::BINARY => PDO::PARAM_LOB,
         ParameterType::LARGE_OBJECT => PDO::PARAM_LOB,
         ParameterType::BOOLEAN => PDO::PARAM_BOOL,

src/Driver/SQLSrv/Statement.php

@@ -182,6 +182,14 @@ private function prepare()
                     ];
                     break;
 
+                case ParameterType::ASCII_STRING:
+                    $params[$column - 1] = [
+                        &$variable,
+                        SQLSRV_PARAM_IN,
+                        SQLSRV_PHPTYPE_STRING(SQLSRV_ENC_CHAR),
+                    ];
+                    break;
+
                 default:
                     $params[$column - 1] =& $variable;
                     break;

src/ParameterType.php

@@ -41,6 +41,11 @@ final class ParameterType
      */
     public const BINARY = 16;
 
+    /**
+     * Represents an ascii string data type
+     */
+    public const ASCII_STRING = 17;
+
     /**
      * This class cannot be instantiated.
      *

src/Types/AsciiStringType.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Types;
+
+use Doctrine\DBAL\ParameterType;
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+
+use function sprintf;
+
+class AsciiStringType extends StringType
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getSQLDeclaration(array $column, AbstractPlatform $platform)
+    {
+        $length = $column['length'] ?? null;
+
+        if (! isset($column['fixed'])) {
+            return sprintf('VARCHAR(%d)', $length);
+        }
+
+        return sprintf('CHAR(%d)', $length);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function getBindingType()
+    {
+        return ParameterType::ASCII_STRING;
+    }
+
+    public function getName(): string
+    {
+        return Types::ASCII_STRING;
+    }
+}

src/Types/Type.php

@@ -21,6 +21,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,

src/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';

tests/Functional/Types/StringBindingTest.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Tests\Functional\Types;
+
+use Doctrine\DBAL\Driver\SQLSrv\Driver;
+use Doctrine\DBAL\ParameterType;
+use Doctrine\DBAL\Tests\FunctionalTestCase;
+
+class StringBindingTest extends FunctionalTestCase
+{
+    public function testAsciiStringBinding(): void
+    {
+        if (! $this->driverSupportsAsciiBinding()) {
+            self::markTestSkipped('Driver does not support ascii string binding');
+        }
+
+        $statement = $this->connection->prepare('SELECT sql_variant_property(?, \'BaseType\')');
+
+        $statement->bindValue(1, 'test', ParameterType::ASCII_STRING);
+        $results = $statement->execute()->fetchOne();
+
+        self::assertEquals('varchar', $results);
+    }
+
+    private function driverSupportsAsciiBinding(): bool
+    {
+        return $this->connection->getDriver() instanceof Driver
+            || $this->connection->getDriver() instanceof \Doctrine\DBAL\Driver\PDO\SQLSrv\Driver;
+    }
+}

tests/Types/AsciiStringTest.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Tests\Types;
+
+use Doctrine\DBAL\ParameterType;
+use Doctrine\DBAL\Platforms\AbstractPlatform;
+use Doctrine\DBAL\Types\AsciiStringType;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+
+class AsciiStringTest extends TestCase
+{
+    /** @var AbstractPlatform|MockObject */
+    private $platform;
+
+    /** @var AsciiStringType */
+    private $type;
+
+    protected function setUp(): void
+    {
+        $this->platform = $this->createMock(AbstractPlatform::class);
+        $this->type     = new AsciiStringType();
+    }
+
+    public function testReturnsBindingType(): void
+    {
+        self::assertEquals($this->type->getBindingType(), ParameterType::ASCII_STRING);
+    }
+
+    /**
+     * @param array<string, mixed> $column
+     *
+     * @dataProvider sqlDeclarationDataProvider
+     */
+    public function testReturnsSQLDeclaration(string $expectedSql, array $column): void
+    {
+        $declarationSql = $this->type->getSQLDeclaration($column, $this->platform);
+        self::assertEquals($expectedSql, $declarationSql);
+    }
+
+    /**
+     * @return array<int, array{string, array<string, mixed>}>
+     */
+    public static function sqlDeclarationDataProvider(): array
+    {
+        return [
+            ['VARCHAR(12)', ['length' => 12]],
+            ['CHAR(12)', ['length' => 12, 'fixed' => true]],
+        ];
+    }
+}