Made the OCI8Statement class final

UPGRADE.md

@@ -1,5 +1,13 @@
 # Upgrade to 3.0
 
+## BC BREAK: `OCI8Statement::convertPositionalToNamedPlaceholders()` is removed.
+
+The `OCI8Statement::convertPositionalToNamedPlaceholders()` method has been extracted to an internal utility class.
+
+## BC BREAK: Dropped handling of one-based numeric arrays of parameters in `Statement::execute()`
+
+The statement implementations no longer detect whether `$params` is a zero- or one-based array. A zero-based numeric array is expected.
+
 ## BC BREAK: `ServerInfoAwareConnection::requiresQueryForServerVersion()` is removed.
 
 The `ServerInfoAwareConnection::requiresQueryForServerVersion()` method has been removed as an implementation detail which is the same for almost all supported drivers.
@@ -52,9 +60,10 @@ Table columns are no longer indexed by column name. Use the `name` attribute of
 - Class `Doctrine\DBAL\Sharding\SQLAzure\SQLAzureFederationsSynchronizer` was made final.
 - Class `Doctrine\DBAL\Sharding\PoolingShardManager` was made final.
 - Class `Doctrine\DBAL\Id\TableGeneratorSchemaVisitor` was made final.
-- Class `Doctrine\DBAL\Driver\OCI8\Driver` was made final.
 - Class `Doctrine\DBAL\Driver\Mysqli\Driver` was made final.
 - Class `Doctrine\DBAL\Driver\Mysqli\MysqliStatement` was made final.
+- Class `Doctrine\DBAL\Driver\OCI8\Driver` was made final.
+- Class `Doctrine\DBAL\Driver\OCI8\OCI8Statement` was made final.
 - Class `Doctrine\DBAL\Driver\PDOSqlsrv\Driver` was made final.
 - Class `Doctrine\DBAL\Driver\PDOSqlsrv\Statement` was made final.
 - Class `Doctrine\DBAL\Driver\PDOMySql\Driver` was made final.

lib/Doctrine/DBAL/Driver/OCI8/ConvertPositionalToNamedPlaceholders.php

@@ -0,0 +1,159 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Driver\OCI8;
+
+use const PREG_OFFSET_CAPTURE;
+use function count;
+use function implode;
+use function preg_match;
+use function preg_quote;
+use function substr;
+
+/**
+ * Converts positional (?) into named placeholders (:param<num>).
+ *
+ * Oracle does not support positional parameters, hence this method converts all
+ * positional parameters into artificially named parameters. Note that this conversion
+ * is not perfect. All question marks (?) in the original statement are treated as
+ * placeholders and converted to a named parameter.
+ *
+ * @internal This class is not covered by the backward compatibility promise
+ */
+final class ConvertPositionalToNamedPlaceholders
+{
+    /**
+     * @param string $statement The SQL statement to convert.
+     *
+     * @return mixed[] [0] => the statement value (string), [1] => the paramMap value (array).
+     *
+     * @throws OCI8Exception
+     */
+    public function __invoke(string $statement) : array
+    {
+        $fragmentOffset          = $tokenOffset = 0;
+        $fragments               = $paramMap = [];
+        $currentLiteralDelimiter = null;
+
+        do {
+            if ($currentLiteralDelimiter === null) {
+                $result = $this->findPlaceholderOrOpeningQuote(
+                    $statement,
+                    $tokenOffset,
+                    $fragmentOffset,
+                    $fragments,
+                    $currentLiteralDelimiter,
+                    $paramMap
+                );
+            } else {
+                $result = $this->findClosingQuote($statement, $tokenOffset, $currentLiteralDelimiter);
+            }
+        } while ($result);
+
+        if ($currentLiteralDelimiter) {
+            throw NonTerminatedStringLiteral::new($tokenOffset - 1);
+        }
+
+        $fragments[] = substr($statement, $fragmentOffset);
+        $statement   = implode('', $fragments);
+
+        return [$statement, $paramMap];
+    }
+
+    /**
+     * Finds next placeholder or opening quote.
+     *
+     * @param string      $statement               The SQL statement to parse
+     * @param int         $tokenOffset             The offset to start searching from
+     * @param int         $fragmentOffset          The offset to build the next fragment from
+     * @param string[]    $fragments               Fragments of the original statement not containing placeholders
+     * @param string|null $currentLiteralDelimiter The delimiter of the current string literal
+     *                                             or NULL if not currently in a literal
+     * @param string[]    $paramMap                Mapping of the original parameter positions to their named replacements
+     *
+     * @return bool Whether the token was found
+     */
+    private function findPlaceholderOrOpeningQuote(
+        string $statement,
+        int &$tokenOffset,
+        int &$fragmentOffset,
+        array &$fragments,
+        ?string &$currentLiteralDelimiter,
+        array &$paramMap
+    ) : bool {
+        $token = $this->findToken($statement, $tokenOffset, '/[?\'"]/');
+
+        if (! $token) {
+            return false;
+        }
+
+        if ($token === '?') {
+            $position            = count($paramMap) + 1;
+            $param               = ':param' . $position;
+            $fragments[]         = substr($statement, $fragmentOffset, $tokenOffset - $fragmentOffset);
+            $fragments[]         = $param;
+            $paramMap[$position] = $param;
+            $tokenOffset        += 1;
+            $fragmentOffset      = $tokenOffset;
+
+            return true;
+        }
+
+        $currentLiteralDelimiter = $token;
+        ++$tokenOffset;
+
+        return true;
+    }
+
+    /**
+     * Finds closing quote
+     *
+     * @param string $statement               The SQL statement to parse
+     * @param int    $tokenOffset             The offset to start searching from
+     * @param string $currentLiteralDelimiter The delimiter of the current string literal
+     *
+     * @return bool Whether the token was found
+     */
+    private function findClosingQuote(
+        string $statement,
+        int &$tokenOffset,
+        string &$currentLiteralDelimiter
+    ) : bool {
+        $token = $this->findToken(
+            $statement,
+            $tokenOffset,
+            '/' . preg_quote($currentLiteralDelimiter, '/') . '/'
+        );
+
+        if (! $token) {
+            return false;
+        }
+
+        $currentLiteralDelimiter = null;
+        ++$tokenOffset;
+
+        return true;
+    }
+
+    /**
+     * Finds the token described by regex starting from the given offset. Updates the offset with the position
+     * where the token was found.
+     *
+     * @param string $statement The SQL statement to parse
+     * @param int    $offset    The offset to start searching from
+     * @param string $regex     The regex containing token pattern
+     *
+     * @return string|null Token or NULL if not found
+     */
+    private function findToken(string $statement, int &$offset, string $regex) : ?string
+    {
+        if (preg_match($regex, $statement, $matches, PREG_OFFSET_CAPTURE, $offset)) {
+            $offset = $matches[0][1];
+
+            return $matches[0][0];
+        }
+
+        return null;
+    }
+}

lib/Doctrine/DBAL/Driver/OCI8/NonTerminatedStringLiteral.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Doctrine\DBAL\Driver\OCI8;
+
+use function sprintf;
+
+final class NonTerminatedStringLiteral extends OCI8Exception
+{
+    public static function new(int $offset) : self
+    {
+        return new self(
+            sprintf(
+                'The statement contains non-terminated string literal starting at offset %d.',
+                $offset
+            )
+        );
+    }
+}