Route the Adapter throw sites through named constructors and remove VunerablePlatformQuoteException

analyzer-baseline.toml

@@ -441,7 +441,7 @@ count = 1
 [[issues]]
 file = "src/Adapter/Driver/Pdo/AbstractPdoConnection.php"
 code = "mixed-argument"
-message = "Invalid argument type for argument #1 of `Exception::__construct`: expected `string`, but found `mixed`."
+message = 'Invalid argument type for argument #1 of `PhpDb\Adapter\Exception\InvalidQueryException::forDriverError`: expected `string`, but found `mixed`.'
 count = 1
 
 [[issues]]
@@ -1125,7 +1125,7 @@ count = 2
 [[issues]]
 file = "src/Adapter/Platform/AbstractPlatform.php"
 code = "unhandled-thrown-type"
-message = 'Potentially unhandled exception `PhpDb\Adapter\Exception\VunerablePlatformQuoteException` in `PhpDb\Adapter\Platform\AbstractPlatform::quoteValue`.'
+message = 'Potentially unhandled exception `PhpDb\Adapter\Exception\RuntimeException` in `PhpDb\Adapter\Platform\AbstractPlatform::quoteValue`.'
 count = 1
 
 [[issues]]
@@ -1155,7 +1155,7 @@ count = 1
 [[issues]]
 file = "src/Adapter/Platform/Sql92.php"
 code = "unhandled-thrown-type"
-message = 'Potentially unhandled exception `PhpDb\Adapter\Exception\VunerablePlatformQuoteException` in `PhpDb\Adapter\Platform\Sql92::quoteValue`.'
+message = 'Potentially unhandled exception `PhpDb\Adapter\Exception\RuntimeException` in `PhpDb\Adapter\Platform\Sql92::quoteValue`.'
 count = 1
 
 [[issues]]

lint-baseline.toml

@@ -8363,6 +8363,7 @@ file = "test/unit/TableGateway/TableGatewayTest.php"
 code = "strict-assertions"
 message = "Use strict assertions in PHPUnit tests."
 count = 2
+
 [[issues]]
 file = "src/TableGateway/AbstractTableGateway.php"
 code = "halstead"
@@ -8380,3 +8381,9 @@ file = "src/Sql/Ddl/Column/AbstractPrecisionColumn.php"
 code = "halstead"
 message = "Method has a high halstead difficulty"
 count = 1
+
+[[issues]]
+file = "src/Adapter/Driver/Pdo/Statement.php"
+code = "halstead"
+message = "Method has a high halstead difficulty"
+count = 1

mago.toml

@@ -16,7 +16,7 @@ baseline = "lint-baseline.toml"
 # condition, per the convention in docs/book/exceptions.md. The method count tracks the
 # number of distinct failures a component can report, so the maintainability signal does
 # not apply. "test/" repeats the phpdb-qa-tools default, which this key replaces.
-too-many-methods = { exclude = ["test/", "src/Sql/Exception/", "src/TableGateway/Exception/"] }
+too-many-methods = { exclude = ["test/", "src/Sql/Exception/", "src/TableGateway/Exception/", "src/Adapter/Exception/"] }
 
 [analyzer]
 baseline = "analyzer-baseline.toml"

src/Adapter/Adapter.php

@@ -63,7 +63,7 @@ public function executeQuery(Driver\StatementInterface|string $sql): Driver\Resu
             : $this->driver->getConnection()->execute($sql);
 
         if (! $result instanceof Driver\ResultInterface) {
-            throw new Exception\RuntimeException('Query execution did not produce a result');
+            throw Exception\RuntimeException::forMissingQueryResult();
         }
 
         return $result;
@@ -171,9 +171,7 @@ public function query(
             $parametersOrQueryMode instanceof ParameterContainer,
             is_array($parametersOrQueryMode),
                 => $this->prepareQuery($sql, $parametersOrQueryMode),
-            default => throw new Exception\InvalidArgumentException(
-                'Flag incorrectly set',
-            ),
+            default => throw Exception\InvalidArgumentException::forIncorrectFlag(),
         };
 
         $result = $this->executeQuery($sql);
@@ -199,7 +197,7 @@ public function __get(string $name): Driver\DriverInterface|Platform\PlatformInt
         return match (strtolower($name)) {
             'driver'   => $this->driver,
             'platform' => $this->platform,
-            default    => throw new Exception\InvalidArgumentException('Invalid magic property on adapter'),
+            default    => throw Exception\InvalidArgumentException::forInvalidMagicProperty(),
         };
     }
 }

src/Adapter/Driver/Feature/DriverFeatureProviderTrait.php

@@ -8,8 +8,6 @@
 use PhpDb\Adapter\Driver\DriverInterface;
 use PhpDb\Adapter\Exception\RuntimeException;
 
-use function sprintf;
-
 /**
  * Trait implementation of DriverFeatureProviderInterface.
  *
@@ -27,11 +25,7 @@ trait DriverFeatureProviderTrait
     public function addFeature(DriverFeatureInterface $feature): DriverFeatureProviderInterface
     {
         if (! $this instanceof DriverInterface) {
-            throw new RuntimeException(sprintf(
-                '%s can only be composed into %s',
-                __TRAIT__,
-                DriverInterface::class,
-            ));
+            throw RuntimeException::forUncomposableTrait(__TRAIT__, DriverInterface::class);
         }
 
         $feature->setDriver($this);

src/Adapter/Driver/Pdo/AbstractPdo.php

@@ -23,7 +23,6 @@
 use function is_string;
 use function ltrim;
 use function preg_match;
-use function sprintf;
 
 abstract class AbstractPdo implements PdoDriverInterface, ProfilerAwareInterface
 {
@@ -44,9 +43,7 @@ public function checkEnvironment(): bool
     {
         if (! extension_loaded('PDO')) {
             // @codeCoverageIgnoreStart
-            throw new Exception\RuntimeException(
-                'The PDO extension is required for this adapter but the extension is not loaded',
-            );
+            throw Exception\RuntimeException::forMissingPdoExtension();
 
             // @codeCoverageIgnoreEnd
         }
@@ -94,12 +91,7 @@ public function formatParameterName(string|int $name, ?string $type = null): str
             $name = ltrim($name, ':');
             // @see https://bugs.php.net/bug.php?id=43130
             if (preg_match('/[^a-zA-Z0-9_]/', $name)) {
-                throw new Exception\RuntimeException(sprintf(
-                    'The PDO param %s contains invalid characters.'
-                        . ' Only alphabetic characters, digits, and underscores (_)'
-                        . ' are allowed.',
-                    $name,
-                ));
+                throw Exception\RuntimeException::forInvalidPdoParam($name);
             }
             return ":{$name}";
         }

src/Adapter/Driver/Pdo/AbstractPdoConnection.php

@@ -91,7 +91,7 @@ public function execute($sql): ?ResultInterface
 
         if (false === $resultResource) {
             $errorInfo = $this->resource->errorInfo();
-            throw new Exception\InvalidQueryException($errorInfo[2]);
+            throw Exception\InvalidQueryException::forDriverError($errorInfo[2]);
         }
 
         /** @phpstan-ignore arguments.count */
@@ -107,9 +107,7 @@ public function execute($sql): ?ResultInterface
     final public function getDsn(): string
     {
         if (! $this->dsn) {
-            throw new Exception\RuntimeException(
-                'The DSN has not been set or constructed from parameters in connect() for this Connection',
-            );
+            throw Exception\RuntimeException::forMissingDsn();
         }
 
         return $this->dsn;
@@ -141,11 +139,11 @@ public function prepare(?string $sql = null): StatementInterface
     public function rollback(): ConnectionInterface
     {
         if (! $this->isConnected()) {
-            throw new Exception\RuntimeException('Must be connected before you can rollback');
+            throw Exception\RuntimeException::forDisconnectedRollback();
         }
 
         if (! $this->inTransaction()) {
-            throw new Exception\RuntimeException('Must call beginTransaction() before you can rollback');
+            throw Exception\RuntimeException::forRollbackWithoutTransaction();
         }
 
         $this->resource->rollBack();

src/Adapter/Driver/Pdo/Result.php

@@ -167,10 +167,7 @@ public function getGeneratedValue(): string|int|false|null
     public function getQueryResult(?ResultSetInterface $resultPrototype = null): ResultSetInterface
     {
         if (! $this->isQueryResult()) {
-            throw new Exception\RuntimeException(
-                'Cannot produce a query result set from a result that is not a query result;'
-                    . ' check isQueryResult() first',
-            );
+            throw Exception\RuntimeException::forNonQueryResult();
         }
 
         $resultPrototype ??= new ResultSet();
@@ -265,9 +262,7 @@ public function next()
     public function rewind()
     {
         if (self::STATEMENT_MODE_FORWARD === $this->statementMode && $this->position > 0) {
-            throw new Exception\RuntimeException(
-                'This result is a forward only result set, calling rewind() after moving forward is not supported',
-            );
+            throw Exception\RuntimeException::forForwardOnlyRewind();
         }
         if (! $this->currentComplete) {
             $this->currentData     = $this->resource->fetch($this->fetchMode);
@@ -282,9 +277,7 @@ public function rewind()
     public function setFetchMode(int $fetchMode): void
     {
         if (! in_array($fetchMode, self::VALID_FETCH_MODES, true)) {
-            throw new Exception\InvalidArgumentException(
-                'The fetch mode must be one of the PDO::FETCH_* constants.',
-            );
+            throw Exception\InvalidArgumentException::forInvalidFetchMode();
         }
 
         $this->fetchMode = (int) $fetchMode;
@@ -293,9 +286,7 @@ public function setFetchMode(int $fetchMode): void
     public function setStatementMode(string $statementMode = self::STATEMENT_MODE_FORWARD): void
     {
         if (! in_array($statementMode, [self::STATEMENT_MODE_SCROLLABLE, self::STATEMENT_MODE_FORWARD], true)) {
-            throw new Exception\InvalidArgumentException(
-                'The statement mode must be one of the defined constants.',
-            );
+            throw Exception\InvalidArgumentException::forInvalidStatementMode();
         }
 
         $this->statementMode = $statementMode;

src/Adapter/Driver/Pdo/Statement.php

@@ -23,7 +23,6 @@
 use function is_int;
 use function ltrim;
 use function preg_match;
-use function sprintf;
 
 class Statement implements StatementInterface, PdoDriverAwareInterface, ProfilerAwareInterface
 {
@@ -83,8 +82,8 @@ public function execute(array|ParameterContainer|null $parameters = null): ?Resu
                 $code = 0;
             }
 
-            throw new Exception\InvalidQueryException(
-                'Statement could not be executed (' . implode(' - ', $this->resource->errorInfo()) . ')',
+            throw Exception\InvalidQueryException::forFailedStatement(
+                implode(' - ', $this->resource->errorInfo()),
                 $code,
                 $e,
             );
@@ -138,7 +137,7 @@ public function isPrepared(): bool
     public function prepare(?string $sql = null): StatementInterface
     {
         if ($this->isPrepared) {
-            throw new Exception\RuntimeException('This statement has been prepared already');
+            throw Exception\RuntimeException::forAlreadyPrepared();
         }
 
         if (null === $sql) {
@@ -149,7 +148,7 @@ public function prepare(?string $sql = null): StatementInterface
 
         if (false === $this->resource) {
             $error = $this->pdo->errorInfo();
-            throw new Exception\RuntimeException($error[2]);
+            throw Exception\RuntimeException::forDriverError($error[2]);
         }
 
         $this->isPrepared = true;
@@ -224,11 +223,7 @@ protected function bindParametersFromContainer(): void
                 $parameter = $name + 1;
             } else {
                 if (! preg_match('/^:?[a-zA-Z0-9_]+$/', $name)) {
-                    throw new Exception\RuntimeException(sprintf(
-                        'The PDO param "%s" contains invalid characters.'
-                            . ' Only alphabetic characters, digits, and underscores (_) are allowed.',
-                        $name,
-                    ));
+                    throw Exception\RuntimeException::forInvalidPdoParam($name);
                 }
                 $parameter = ':' . ltrim($name, ':');
             }

src/Adapter/Exception/InvalidArgumentException.php

@@ -1,7 +1,52 @@
 <?php
 
+declare(strict_types=1);
+
 namespace PhpDb\Adapter\Exception;
 
 use PhpDb\Exception;
 
-class InvalidArgumentException extends Exception\InvalidArgumentException {}
+class InvalidArgumentException extends Exception\InvalidArgumentException
+{
+    final public const string INCORRECT_FLAG = 'Flag incorrectly set';
+
+    final public const string INVALID_FETCH_MODE = 'The fetch mode must be one of the PDO::FETCH_* constants.';
+
+    final public const string INVALID_KEY_TYPE = 'Keys must be string, integer or null';
+
+    final public const string INVALID_MAGIC_PROPERTY = 'Invalid magic property on adapter';
+
+    final public const string INVALID_STATEMENT_MODE = 'The statement mode must be one of the defined constants.';
+
+    final public const string MISSING_DATA = 'Data does not exist for this name/position';
+
+    public static function forIncorrectFlag(): self
+    {
+        return new self(self::INCORRECT_FLAG);
+    }
+
+    public static function forInvalidFetchMode(): self
+    {
+        return new self(self::INVALID_FETCH_MODE);
+    }
+
+    public static function forInvalidKeyType(): self
+    {
+        return new self(self::INVALID_KEY_TYPE);
+    }
+
+    public static function forInvalidMagicProperty(): self
+    {
+        return new self(self::INVALID_MAGIC_PROPERTY);
+    }
+
+    public static function forInvalidStatementMode(): self
+    {
+        return new self(self::INVALID_STATEMENT_MODE);
+    }
+
+    public static function forMissingData(): self
+    {
+        return new self(self::MISSING_DATA);
+    }
+}

src/Adapter/Exception/InvalidQueryException.php

@@ -4,4 +4,24 @@
 
 namespace PhpDb\Adapter\Exception;
 
-class InvalidQueryException extends UnexpectedValueException {}
+use Throwable;
+
+use function sprintf;
+
+class InvalidQueryException extends UnexpectedValueException
+{
+    /** The driver's own error text, passed through verbatim. */
+    final public const string DRIVER_ERROR = '%s';
+
+    final public const string FAILED_STATEMENT = 'Statement could not be executed (%s)';
+
+    public static function forDriverError(string $error): self
+    {
+        return new self(sprintf(self::DRIVER_ERROR, $error));
+    }
+
+    public static function forFailedStatement(string $errorInfo, int $code, Throwable $previous): self
+    {
+        return new self(sprintf(self::FAILED_STATEMENT, $errorInfo), $code, $previous);
+    }
+}