Merge pull request #232 from simon-mundy/qa/mago-sql-dml

Bring the Sql DML classes to Mago compliance

Author: simon-mundy

analyzer-baseline.toml

@@ -342,24 +342,12 @@ code = "excessive-parameter-list"
 message = "Parameter list is too long."
 count = 1
 
-[[issues]]
-file = "src/Sql/AbstractSql.php"
-code = "halstead"
-message = "Method has a high halstead difficulty"
-count = 1
-
 [[issues]]
 file = "src/Sql/AbstractSql.php"
 code = "kan-defect"
 message = "Class has a high kan defect score."
 count = 1
 
-[[issues]]
-file = "src/Sql/AbstractSql.php"
-code = "too-many-methods"
-message = "Class has too many methods."
-count = 1
-
 [[issues]]
 file = "src/Sql/Combine.php"
 code = "cyclomatic-complexity"
@@ -372,24 +360,12 @@ code = "kan-defect"
 message = "Class has a high kan defect score."
 count = 1
 
-[[issues]]
-file = "src/Sql/Combine.php"
-code = "no-array-accumulation-in-loop"
-message = "Array spread in reassignment inside a loop causes O(n²) array copying."
-count = 1
-
 [[issues]]
 file = "src/Sql/Insert.php"
 code = "cyclomatic-complexity"
 message = "Class has high complexity."
 count = 1
 
-[[issues]]
-file = "src/Sql/Insert.php"
-code = "too-many-methods"
-message = "Class has too many methods."
-count = 1
-
 [[issues]]
 file = "src/Sql/Select.php"
 code = "cyclomatic-complexity"
@@ -400,44 +376,20 @@ count = 1
 file = "src/Sql/Select.php"
 code = "halstead"
 message = "Method has a high halstead difficulty"
-count = 2
+count = 1
 
 [[issues]]
 file = "src/Sql/Select.php"
 code = "kan-defect"
 message = "Class has a high kan defect score."
 count = 1
 
-[[issues]]
-file = "src/Sql/Select.php"
-code = "too-many-methods"
-message = "Class has too many methods."
-count = 1
-
-[[issues]]
-file = "src/Sql/Select.php"
-code = "too-many-properties"
-message = "Class has too many properties."
-count = 1
-
 [[issues]]
 file = "src/Sql/Update.php"
 code = "cyclomatic-complexity"
 message = "Class has high complexity."
 count = 1
 
-[[issues]]
-file = "src/Sql/Update.php"
-code = "halstead"
-message = "Method has a high halstead difficulty"
-count = 1
-
-[[issues]]
-file = "src/Sql/Update.php"
-code = "too-many-methods"
-message = "Class has too many methods."
-count = 1
-
 [[issues]]
 file = "src/TableGateway/AbstractTableGateway.php"
 code = "cyclomatic-complexity"

lint-baseline.toml

@@ -15,9 +15,10 @@ baseline = "lint-baseline.toml"
 # Exception classes are message catalogues: one template and one named constructor per
 # 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. Predicate, AlterTable and CreateTable are fluent builders: one public method per
-# clause they can emit, so their method count is the size of their public API. "test/"
-# repeats the phpdb-qa-tools default, which this key replaces.
+# 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.
+# "test/" repeats the phpdb-qa-tools default, which this key replaces.
 too-many-methods = { exclude = [
     "test/",
     "src/Sql/Exception/",
@@ -27,8 +28,15 @@ too-many-methods = { exclude = [
     "src/Sql/Predicate/Predicate.php",
     "src/Sql/Ddl/AlterTable.php",
     "src/Sql/Ddl/CreateTable.php",
+    "src/Sql/AbstractSql.php",
+    "src/Sql/Select.php",
+    "src/Sql/Insert.php",
+    "src/Sql/Update.php",
 ] }
 
+# Select holds one property per clause of a SELECT statement.
+too-many-properties = { exclude = ["src/Sql/Select.php"] }
+
 # These constructors take one argument per part of the SQL definition they model
 # (a foreign key's name, columns, reference table, reference columns and two rules; a
 # column's name, digits, scale, nullability, default and options). They are public API, so
@@ -48,6 +56,11 @@ prefer-self-return-type = { exclude = [
 
 [analyzer]
 baseline = "analyzer-baseline.toml"
+# ArgumentType is string-backed and each case's value is a ::class constant, which PHP accepts
+# as a string. The analyzer reports the class-string type as not being a string.
+ignore = [
+    { code = "invalid-enum-case-value", in = ["src/Sql/ArgumentType.php"] },
+]
 class-initializers = [
     "PhpDb\\ResultSet\\AbstractResultSet::initialize",
     "PhpDb\\TableGateway\\Feature\\AbstractFeature::setTableGateway",

mago.toml

@@ -6,6 +6,7 @@
 
 use ArrayObject;
 use Laminas\Hydrator\ArraySerializableHydrator;
+use Laminas\Hydrator\Exception\RuntimeException as HydratorRuntimeException;
 use Laminas\Hydrator\HydratorInterface;
 use Override;
 use PhpDb\ResultSet\Exception\RuntimeException;
@@ -119,7 +120,7 @@ public function toArray(): array
      * Hydrate one row onto a clone of the prototype.
      *
      * @throws Exception\UnexpectedValueException If the row is not row data.
-     * @throws \Laminas\Hydrator\Exception\RuntimeException If the hydrator cannot fill the prototype.
+     * @throws HydratorRuntimeException If the hydrator cannot fill the prototype.
      */
     #[Override]
     protected function mapRow(mixed $row): object

src/ResultSet/HydratingResultSet.php

@@ -4,6 +4,9 @@
 
 namespace PhpDb\Sql;
 
+/**
+ * @api
+ */
 abstract class AbstractExpression implements ExpressionInterface
 {
     protected ?string $specification = null;

src/Sql/AbstractExpression.php

@@ -12,8 +12,14 @@
 use function array_values;
 use function is_array;
 
+/**
+ * @api
+ */
 abstract class AbstractPreparableSql extends AbstractSql implements PreparableSqlInterface
 {
+    /**
+     * @throws Exception\RuntimeException
+     */
     #[Override]
     public function prepareStatement(
         AdapterInterface $adapter,