Bring src/Adapter to Mago compliance

lint-baseline.toml

@@ -1,209 +1,11 @@
 variant = "loose"
 
-[[issues]]
-file = "src/Adapter/Adapter.php"
-code = "prefer-first-class-callable"
-message = "Use first-class callable syntax `...` instead of a closure."
-count = 2
-
-[[issues]]
-file = "src/Adapter/AdapterAwareInterface.php"
-code = "strict-types"
-message = "Missing `declare(strict_types=1);` statement at the beginning of the file."
-count = 1
-
-[[issues]]
-file = "src/Adapter/AdapterAwareTrait.php"
-code = "strict-types"
-message = "Missing `declare(strict_types=1);` statement at the beginning of the file."
-count = 1
-
-[[issues]]
-file = "src/Adapter/Driver/ConnectionInterface.php"
-code = "too-many-methods"
-message = "Interface has too many methods."
-count = 1
-
-[[issues]]
-file = "src/Adapter/Driver/Pdo/AbstractPdo.php"
-code = "literal-named-argument"
-message = "Literal argument `':'` should be passed as a named argument for clarity."
-count = 1
-
-[[issues]]
-file = "src/Adapter/Driver/Pdo/AbstractPdo.php"
-code = "no-else-clause"
-message = "Avoid `else` clauses."
-count = 1
-
-[[issues]]
-file = "src/Adapter/Driver/Pdo/AbstractPdo.php"
-code = "tagged-todo"
-message = "TODO should be tagged with (@username) or (#issue)."
-count = 1
-
-[[issues]]
-file = "src/Adapter/Driver/Pdo/Result.php"
-code = "halstead"
-message = "Method has a high halstead difficulty"
-count = 1
-
-[[issues]]
-file = "src/Adapter/Driver/Pdo/Result.php"
-code = "literal-named-argument"
-message = "Literal argument `true` should be passed as a named argument for clarity."
-count = 2
-
-[[issues]]
-file = "src/Adapter/Driver/Pdo/Result.php"
-code = "no-else-clause"
-message = "Avoid `else` clauses."
-count = 1
-
-[[issues]]
-file = "src/Adapter/Driver/Pdo/Result.php"
-code = "too-many-methods"
-message = "Class has too many methods."
-count = 1
-
-[[issues]]
-file = "src/Adapter/Driver/Pdo/Statement.php"
-code = "literal-named-argument"
-message = "Literal argument `':'` should be passed as a named argument for clarity."
-count = 1
-
-[[issues]]
-file = "src/Adapter/Driver/Pdo/Statement.php"
-code = "no-else-clause"
-message = "Avoid `else` clauses."
-count = 2
-
-[[issues]]
-file = "src/Adapter/Driver/Pdo/Statement.php"
-code = "no-isset"
-message = "Use of the `isset` construct."
-count = 1
-
 [[issues]]
 file = "src/Adapter/ParameterContainer.php"
 code = "cyclomatic-complexity"
 message = "Class has high complexity."
 count = 1
 
-[[issues]]
-file = "src/Adapter/ParameterContainer.php"
-code = "halstead"
-message = "Method has a high halstead difficulty"
-count = 1
-
-[[issues]]
-file = "src/Adapter/ParameterContainer.php"
-code = "kan-defect"
-message = "Class has a high kan defect score."
-count = 1
-
-[[issues]]
-file = "src/Adapter/ParameterContainer.php"
-code = "literal-named-argument"
-message = "Literal argument `':'` should be passed as a named argument for clarity."
-count = 1
-
-[[issues]]
-file = "src/Adapter/ParameterContainer.php"
-code = "literal-named-argument"
-message = "Literal argument `1` should be passed as a named argument for clarity."
-count = 2
-
-[[issues]]
-file = "src/Adapter/ParameterContainer.php"
-code = "no-else-clause"
-message = "Avoid `else` clauses."
-count = 2
-
-[[issues]]
-file = "src/Adapter/ParameterContainer.php"
-code = "no-else-clause"
-message = "Avoid `elseif` clauses."
-count = 3
-
-[[issues]]
-file = "src/Adapter/ParameterContainer.php"
-code = "no-isset"
-message = "Use of the `isset` construct."
-count = 11
-
-[[issues]]
-file = "src/Adapter/ParameterContainer.php"
-code = "too-many-methods"
-message = "Class has too many methods."
-count = 1
-
-[[issues]]
-file = "src/Adapter/Platform/AbstractPlatform.php"
-code = "literal-named-argument"
-message = '''Literal argument `"\x00\n\r\\'\"\x1a"` should be passed as a named argument for clarity.'''
-count = 2
-
-[[issues]]
-file = "src/Adapter/Platform/AbstractPlatform.php"
-code = "literal-named-argument"
-message = '''Literal argument `'\\"'` should be passed as a named argument for clarity.'''
-count = 1
-
-[[issues]]
-file = "src/Adapter/Platform/AbstractPlatform.php"
-code = "no-else-clause"
-message = "Avoid `else` clauses."
-count = 1
-
-[[issues]]
-file = "src/Adapter/Platform/AbstractPlatform.php"
-code = "no-isset"
-message = "Use of the `isset` construct."
-count = 2
-
-[[issues]]
-file = "src/Adapter/Platform/PlatformInterface.php"
-code = "too-many-methods"
-message = "Interface has too many methods."
-count = 1
-
-[[issues]]
-file = "src/Adapter/Platform/Sql92.php"
-code = "literal-named-argument"
-message = '''Literal argument `"\x00\n\r\\'\"\x1a"` should be passed as a named argument for clarity.'''
-count = 1
-
-[[issues]]
-file = "src/Adapter/Platform/Sql92.php"
-code = "no-isset"
-message = "Use of the `isset` construct."
-count = 1
-
-[[issues]]
-file = "src/Adapter/Profiler/Profiler.php"
-code = "no-else-clause"
-message = "Avoid `else` clauses."
-count = 1
-
-[[issues]]
-file = "src/Adapter/Profiler/Profiler.php"
-code = "no-isset"
-message = "Use of the `isset` construct."
-count = 1
-
-[[issues]]
-file = "src/Adapter/SchemaAwareInterface.php"
-code = "tagged-todo"
-message = "TODO should be tagged with (@username) or (#issue)."
-count = 1
-
-[[issues]]
-file = "src/Adapter/StatementContainer.php"
-code = "strict-types"
-message = "Missing `declare(strict_types=1);` statement at the beginning of the file."
-count = 1
-
 [[issues]]
 file = "src/Container/AbstractAdapterInterfaceFactory.php"
 code = "no-empty"

mago.toml

@@ -18,9 +18,18 @@ baseline = "lint-baseline.toml"
 # not apply. Predicate, AlterTable, CreateTable, Select, Insert and Update are fluent builders:
 # one public method per clause they can emit, so their method count is the size of their
 # public API. AbstractSql is their base and carries one protected hook per clause it renders.
+# ConnectionInterface and PlatformInterface are the contracts every driver and platform package
+# implements, so their method count is the size of that contract. Pdo\Result implements Iterator,
+# Countable and ResultInterface, and ParameterContainer implements Iterator, ArrayAccess and
+# Countable beside its errata and max-length accessors: in both, the count is fixed by the
+# interfaces and the public API.
 # "test/" repeats the phpdb-qa-tools default, which this key replaces.
 too-many-methods = { exclude = [
     "test/",
+    "src/Adapter/Driver/ConnectionInterface.php",
+    "src/Adapter/Driver/Pdo/Result.php",
+    "src/Adapter/ParameterContainer.php",
+    "src/Adapter/Platform/PlatformInterface.php",
     "src/Sql/Exception/",
     "src/Sql/Predicate/Exception/",
     "src/TableGateway/Exception/",
@@ -62,6 +71,8 @@ ignore = [
     { code = "invalid-enum-case-value", in = ["src/Sql/ArgumentType.php"] },
 ]
 class-initializers = [
+    "PhpDb\\Adapter\\Driver\\Pdo\\Statement::initialize",
+    "PhpDb\\Adapter\\Driver\\Pdo\\Statement::setDriver",
     "PhpDb\\ResultSet\\AbstractResultSet::initialize",
     "PhpDb\\TableGateway\\Feature\\AbstractFeature::setTableGateway",
     "PhpDb\\RowGateway\\Feature\\AbstractFeature::setRowGateway",

src/Adapter/Adapter.php

@@ -12,6 +12,9 @@
 use function is_array;
 use function strtolower;
 
+/**
+ * @api
+ */
 class Adapter implements AdapterInterface, Profiler\ProfilerAwareInterface, SchemaAwareInterface
 {
     /**
@@ -30,6 +33,8 @@ public function __construct(
 
     /**
      * Create statement
+     *
+     * @param ParameterContainer|array<array-key, mixed> $initialParameters
      */
     #[Override]
     public function createStatement(
@@ -83,24 +88,31 @@ public function getDriver(): Driver\DriverInterface
 
     /**
      * {@inheritDoc}
+     *
+     * Each argument names a helper, and the match is strict, so an argument that is not one of
+     * the FUNCTION_* names, whatever its type, adds no helper.
+     *
+     * Every helper names its parameter $value so callers can pass it by name, which is why
+     * quoteIdentifier(), whose own parameter is $identifier, sits behind a forwarding closure.
+     *
+     * @mago-expect analysis:mixed-assignment
+     * @mago-expect lint:prefer-first-class-callable
      */
     #[Override]
     public function getHelpers()
     {
         $functions = [];
         $platform  = $this->platform;
         foreach (func_get_args() as $arg) {
-            switch ($arg) {
-                case self::FUNCTION_QUOTE_IDENTIFIER:
-                    $functions[] = static function ($value) use ($platform) {
-                        return $platform->quoteIdentifier($value);
-                    };
-                    break;
-                case self::FUNCTION_QUOTE_VALUE:
-                    $functions[] = static function ($value) use ($platform) {
-                        return $platform->quoteValue($value);
-                    };
-                    break;
+            $function = match ($arg) {
+                self::FUNCTION_QUOTE_IDENTIFIER => static fn(string $value): string => $platform->quoteIdentifier(
+                    $value,
+                ),
+                self::FUNCTION_QUOTE_VALUE => $platform->quoteValue(...),
+                default => null,
+            };
+            if (null !== $function) {
+                $functions[] = $function;
             }
         }
         return $functions;
@@ -129,6 +141,8 @@ public function getQueryResultSetPrototype(): ResultSet\ResultSetInterface
      *
      * Always prepares the statement; never executes it. Use executeQuery()
      * to run the returned statement.
+     *
+     * @param ParameterContainer|array<array-key, mixed> $parameters
      */
     #[Override]
     public function prepareQuery(
@@ -152,6 +166,8 @@ public function prepareQuery(
      *
      * @deprecated Use prepareQuery() and executeQuery() instead. query() will be removed in a future version.
      *
+     * @param ParameterContainer|array<array-key, mixed>|string $parametersOrQueryMode
+     *
      * @throws Exception\InvalidArgumentException
      * @throws Exception\RuntimeException When execution did not produce a result.
      * @throws PhpException

src/Adapter/AdapterAwareInterface.php

@@ -1,7 +1,12 @@
 <?php
 
+declare(strict_types=1);
+
 namespace PhpDb\Adapter;
 
+/**
+ * @api
+ */
 interface AdapterAwareInterface
 {
     /** Set db adapter */

src/Adapter/AdapterAwareTrait.php

@@ -1,7 +1,12 @@
 <?php
 
+declare(strict_types=1);
+
 namespace PhpDb\Adapter;
 
+/**
+ * @api
+ */
 trait AdapterAwareTrait
 {
     protected AdapterInterface $adapter;