Merge commit '3b8c8f9f6' into 3.0.x

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
 ++++
 
@@ -583,6 +590,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`` [16]_ |
 | | | | +----------------------------------------------------------+
 | | | | | ``TEXT`` [17]_ |

src/Driver/Mysqli/Statement.php

@@ -28,6 +28,7 @@ final class Statement implements StatementInterface
 {
  /** @var string[] */
  protected static $_paramTypeMap = [
+ ParameterType::ASCII => '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:
+ $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 => 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:
+ $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 = 17;
+
  /**
  * This class cannot be instantiated.
  *

src/Platforms/AbstractPlatform.php

@@ -186,6 +186,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.
  *

src/Platforms/SQLServer2012Platform.php

@@ -1235,6 +1235,20 @@ public function getDateTimeTzTypeDeclarationSQL(array $column)
  return 'DATETIMEOFFSET(6)';
  }
 
+ /**
+ * {@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}
  */

src/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;
+ }
+}

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/ParameterTypes/AsciiTest.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Tests\Functional\ParameterTypes;
+
+use Doctrine\DBAL\Driver\AbstractSQLServerDriver;
+use Doctrine\DBAL\ParameterType;
+use Doctrine\DBAL\Tests\FunctionalTestCase;
+
+class AsciiTest extends FunctionalTestCase
+{
+ 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);
+ $results = $statement->execute()->fetchOne();
+
+ self::assertEquals('varchar', $results);
+ }
+}

tests/Functional/Types/AsciiStringTest.php

@@ -0,0 +1,70 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Tests\Functional\Types;
+
+use Doctrine\DBAL\ParameterType;
+use Doctrine\DBAL\Schema\Table;
+use Doctrine\DBAL\Tests\FunctionalTestCase;
+
+class AsciiStringTest extends FunctionalTestCase
+{
+ 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;
+ }
+}

tests/Platforms/AbstractPlatformTestCase.php

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

tests/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]],
+ ];
+ }
 }

tests/Types/AsciiStringTest.php

@@ -0,0 +1,43 @@
+<?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\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);
+ }
+ }
+}