Resolve PHPStan level 6 findings

composer.json

@@ -26,7 +26,8 @@
   },
   "require-dev": {
     "phpunit/phpunit": "^11",
-    "square/pjson": "^0.5.0"
+    "square/pjson": "^0.5.0",
+    "phpstan/phpstan": "^1.12"
   },
   "autoload": {
     "psr-4": {

composer.lock

@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "f3351c794dd1261ee4bf18380f58463d",
+    "content-hash": "7f9c6e825e6f0968b2dedefec770f558",
     "packages": [
         {
             "name": "bit-badger/inspired-by-fsharp",
@@ -340,6 +340,64 @@
             },
             "time": "2022-02-21T01:04:05+00:00"
         },
+        {
+            "name": "phpstan/phpstan",
+            "version": "1.12.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/phpstan/phpstan.git",
+                "reference": "384af967d35b2162f69526c7276acadce534d0e1"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/phpstan/phpstan/zipball/384af967d35b2162f69526c7276acadce534d0e1",
+                "reference": "384af967d35b2162f69526c7276acadce534d0e1",
+                "shasum": ""
+            },
+            "require": {
+                "php": "^7.2|^8.0"
+            },
+            "conflict": {
+                "phpstan/phpstan-shim": "*"
+            },
+            "bin": [
+                "phpstan",
+                "phpstan.phar"
+            ],
+            "type": "library",
+            "autoload": {
+                "files": [
+                    "bootstrap.php"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "description": "PHPStan - PHP Static Analysis Tool",
+            "keywords": [
+                "dev",
+                "static analysis"
+            ],
+            "support": {
+                "docs": "https://phpstan.org/user-guide/getting-started",
+                "forum": "https://github.com/phpstan/phpstan/discussions",
+                "issues": "https://github.com/phpstan/phpstan/issues",
+                "security": "https://github.com/phpstan/phpstan/security/policy",
+                "source": "https://github.com/phpstan/phpstan-src"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/ondrejmirtes",
+                    "type": "github"
+                },
+                {
+                    "url": "https://github.com/phpstan",
+                    "type": "github"
+                }
+            ],
+            "time": "2024-08-27T09:18:05+00:00"
+        },
         {
             "name": "phpunit/php-code-coverage",
             "version": "11.0.5",

src/Configuration.php

@@ -34,7 +34,7 @@ class Configuration
     /** @var string|null The password to use to establish a data connection (use env PDO_DOC_PASSWORD if possible) */
     public static ?string $password = null;
 
-    /** @var array|null Options to use for connections (driver-specific) */
+    /** @var mixed[]|null Options to use for connections (driver-specific) */
     public static ?array $options = null;
 
     /** @var Option<Mode> The mode in which the library is operating */

src/Count.php

@@ -31,7 +31,7 @@ class Count
      * Count matching documents using a comparison on JSON fields
      *
      * @param string $tableName The name of the table in which documents should be counted
-     * @param array|Field[] $fields The field comparison to match
+     * @param Field[] $fields The field comparison to match
      * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
      * @return int The count of documents matching the field comparison
      * @throws DocumentException If one is encountered
@@ -47,7 +47,7 @@ class Count
      * Count matching documents using a JSON containment query (`@>`; PostgreSQL only)
      *
      * @param string $tableName The name of the table in which documents should be counted
-     * @param array|object $criteria The criteria for the JSON containment query
+     * @param mixed[]|object $criteria The criteria for the JSON containment query
      * @return int The number of documents matching the JSON containment query
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
      */

src/Custom.php

@@ -23,7 +23,7 @@ class Custom
      * Prepare a query for execution and run it
      *
      * @param string $query The query to be run
-     * @param array $parameters The parameters for the query
+     * @param array<string, mixed> $parameters The parameters for the query
      * @return PDOStatement The result of executing the query
      * @throws DocumentException If the query execution is unsuccessful
      */
@@ -67,7 +67,7 @@ class Custom
      *
      * @template TDoc The domain type of the document to retrieve
      * @param string $query The query to be executed
-     * @param array $parameters Parameters to use in executing the query
+     * @param array<string, mixed> $parameters Parameters to use in executing the query
      * @param Mapper<TDoc> $mapper Mapper to deserialize the result
      * @return DocumentList<TDoc> The items matching the query
      * @throws DocumentException If any is encountered
@@ -82,7 +82,7 @@ class Custom
      *
      * @template TDoc The domain type of the document to retrieve
      * @param string $query The query to be executed
-     * @param array $parameters Parameters to use in executing the query
+     * @param array<string, mixed> $parameters Parameters to use in executing the query
      * @param Mapper<TDoc> $mapper Mapper to deserialize the result
      * @return TDoc[] The items matching the query
      * @throws DocumentException If any is encountered
@@ -97,7 +97,7 @@ class Custom
      *
      * @template TDoc The domain type of the document to retrieve
      * @param string $query The query to be executed (will have "LIMIT 1" appended)
-     * @param array $parameters Parameters to use in executing the query
+     * @param array<string, mixed> $parameters Parameters to use in executing the query
      * @param Mapper<TDoc> $mapper Mapper to deserialize the result
      * @return Option<TDoc> A `Some` instance if the item is found, `None` otherwise
      * @throws DocumentException If any is encountered
@@ -116,7 +116,7 @@ class Custom
      * Execute a query that does not return a value
      *
      * @param string $query The query to execute
-     * @param array $parameters Parameters to use in executing the query
+     * @param array<string, mixed> $parameters Parameters to use in executing the query
      * @throws DocumentException If any is encountered
      */
     public static function nonQuery(string $query, array $parameters): void
@@ -133,7 +133,7 @@ class Custom
      *
      * @template T The scalar type to return
      * @param string $query The query to retrieve the value
-     * @param array $parameters Parameters to use in executing the query
+     * @param array<string, mixed> $parameters Parameters to use in executing the query
      * @param Mapper<T> $mapper The mapper to obtain the result
      * @return mixed|false|T The scalar value if found, false if not
      * @throws DocumentException If any is encountered

src/Definition.php

@@ -30,7 +30,7 @@ class Definition
      *
      * @param string $tableName The name of the table which should be indexed
      * @param string $indexName The name of the index
-     * @param array $fields Fields which should be a part of this index
+     * @param string[] $fields Fields which should be a part of this index
      * @throws DocumentException If any is encountered
      */
     public static function ensureFieldIndex(string $tableName, string $indexName, array $fields): void

src/Delete.php

@@ -29,7 +29,7 @@ class Delete
      * Delete documents by matching a comparison on JSON fields
      *
      * @param string $tableName The table from which documents should be deleted
-     * @param array|Field[] $fields The field comparison to match
+     * @param Field[] $fields The field comparison to match
      * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
      * @throws DocumentException If any is encountered
      */
@@ -44,7 +44,7 @@ class Delete
      * Delete documents matching a JSON containment query (`@>`; PostgreSQL only)
      *
      * @param string $tableName The table from which documents should be deleted
-     * @param array|object $criteria The JSON containment query values
+     * @param mixed[]|object $criteria The JSON containment query values
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
      */
     public static function byContains(string $tableName, array|object $criteria): void

src/Document.php

@@ -17,7 +17,7 @@ class Document
      * Insert a new document
      *
      * @param string $tableName The name of the table into which the document should be inserted
-     * @param array|object $document The document to be inserted
+     * @param mixed[]|object $document The document to be inserted
      * @throws DocumentException If any is encountered
      */
     public static function insert(string $tableName, array|object $document): void
@@ -47,7 +47,7 @@ class Document
      * Save a document, inserting it if it does not exist and updating it if it does (AKA "upsert")
      *
      * @param string $tableName The name of the table to which the document should be saved
-     * @param array|object $document The document to be saved
+     * @param mixed[]|object $document The document to be saved
      * @throws DocumentException If any is encountered
      */
     public static function save(string $tableName, array|object $document): void
@@ -60,7 +60,7 @@ class Document
      *
      * @param string $tableName The table in which the document should be updated
      * @param mixed $docId The ID of the document to be updated
-     * @param array|object $document The document to be updated
+     * @param mixed[]|object $document The document to be updated
      * @throws DocumentException If any is encountered
      */
     public static function update(string $tableName, mixed $docId, array|object $document): void

src/DocumentList.php

@@ -133,14 +133,14 @@ class DocumentList
      * Construct a new document list
      *
      * @param string $query The query to run to retrieve results
-     * @param array $parameters An associative array of parameters for the query
+     * @param array<string, mixed> $parameters An associative array of parameters for the query
      * @param Mapper<TDoc> $mapper A mapper to deserialize JSON documents
-     * @return static The document list instance
+     * @return self<TDoc> The document list instance
      * @throws DocumentException If any is encountered
      */
-    public static function create(string $query, array $parameters, Mapper $mapper): static
+    public static function create(string $query, array $parameters, Mapper $mapper): self
     {
         $stmt = &Custom::runQuery($query, $parameters);
-        return new static($stmt, $mapper);
+        return new self($stmt, $mapper);
     }
 }

src/Exists.php

@@ -48,7 +48,7 @@ class Exists
      * Determine if documents exist by a JSON containment query (`@>`; PostgreSQL only)
      *
      * @param string $tableName The name of the table in which document existence should be determined
-     * @param array|object $criteria The criteria for the JSON containment query
+     * @param mixed[]|object $criteria The criteria for the JSON containment query
      * @return bool True if any documents match the JSON containment query, false if not
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
      */

src/Field.php

@@ -33,8 +33,8 @@ class Field
     /**
      * Append the parameter name and value to the given associative array
      *
-     * @param array $existing The existing parameters
+     * @param array<string, mixed> $existing The existing parameters
-     * @return array The given parameter array with this field's name and value appended
+     * @return array<string, mixed> The given parameter array with this field's name and value(s) appended
      */
     public function appendParameter(array $existing): array
     {
@@ -88,11 +88,11 @@ class Field
      * @param string $fieldName The name of the field against which the value will be compared
      * @param mixed $value The value for which equality will be checked
      * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function EQ(string $fieldName, mixed $value, string $paramName = ''): static
+    public static function EQ(string $fieldName, mixed $value, string $paramName = ''): self
     {
-        return new static($fieldName, Op::EQ, $value, $paramName);
+        return new self($fieldName, Op::EQ, $value, $paramName);
     }
 
     /**
@@ -101,11 +101,11 @@ class Field
      * @param string $fieldName The name of the field against which the value will be compared
      * @param mixed $value The value for the greater than comparison
      * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function GT(string $fieldName, mixed $value, string $paramName = ''): static
+    public static function GT(string $fieldName, mixed $value, string $paramName = ''): self
     {
-        return new static($fieldName, Op::GT, $value, $paramName);
+        return new self($fieldName, Op::GT, $value, $paramName);
     }
 
     /**
@@ -114,11 +114,11 @@ class Field
      * @param string $fieldName The name of the field against which the value will be compared
      * @param mixed $value The value for the greater than or equal to comparison
      * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function GE(string $fieldName, mixed $value, string $paramName = ''): static
+    public static function GE(string $fieldName, mixed $value, string $paramName = ''): self
     {
-        return new static($fieldName, Op::GE, $value, $paramName);
+        return new self($fieldName, Op::GE, $value, $paramName);
     }
 
     /**
@@ -127,11 +127,11 @@ class Field
      * @param string $fieldName The name of the field against which the value will be compared
      * @param mixed $value The value for the less than comparison
      * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function LT(string $fieldName, mixed $value, string $paramName = ''): static
+    public static function LT(string $fieldName, mixed $value, string $paramName = ''): self
     {
-        return new static($fieldName, Op::LT, $value, $paramName);
+        return new self($fieldName, Op::LT, $value, $paramName);
     }
 
     /**
@@ -140,11 +140,11 @@ class Field
      * @param string $fieldName The name of the field against which the value will be compared
      * @param mixed $value The value for the less than or equal to comparison
      * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function LE(string $fieldName, mixed $value, string $paramName = ''): static
+    public static function LE(string $fieldName, mixed $value, string $paramName = ''): self
     {
-        return new static($fieldName, Op::LE, $value, $paramName);
+        return new self($fieldName, Op::LE, $value, $paramName);
     }
 
     /**
@@ -153,11 +153,11 @@ class Field
      * @param string $fieldName The name of the field against which the value will be compared
      * @param mixed $value The value for the not equals comparison
      * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function NE(string $fieldName, mixed $value, string $paramName = ''): static
+    public static function NE(string $fieldName, mixed $value, string $paramName = ''): self
     {
-        return new static($fieldName, Op::NE, $value, $paramName);
+        return new self($fieldName, Op::NE, $value, $paramName);
     }
 
     /**
@@ -167,32 +167,32 @@ class Field
      * @param mixed $minValue The lower value for range
      * @param mixed $maxValue The upper value for the range
      * @param string $paramName The name of the parameter to which this should be bound (optional; generated if blank)
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function BT(string $fieldName, mixed $minValue, mixed $maxValue, string $paramName = ''): static
+    public static function BT(string $fieldName, mixed $minValue, mixed $maxValue, string $paramName = ''): self
     {
-        return new static($fieldName, Op::BT, [$minValue, $maxValue], $paramName);
+        return new self($fieldName, Op::BT, [$minValue, $maxValue], $paramName);
     }
 
     /**
      * Create an exists (IS NOT NULL) field criterion
      *
      * @param string $fieldName The name of the field for which existence will be checked
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function EX(string $fieldName): static
+    public static function EX(string $fieldName): self
     {
-        return new static($fieldName, Op::EX, '', '');
+        return new self($fieldName, Op::EX, '', '');
     }
 
     /**
      * Create a not exists (IS NULL) field criterion
      *
      * @param string $fieldName The name of the field for which non-existence will be checked
-     * @return static The field with the requested criterion
+     * @return self The field with the requested criterion
      */
-    public static function NEX(string $fieldName): static
+    public static function NEX(string $fieldName): self
     {
-        return new static($fieldName, Op::NEX, '', '');
+        return new self($fieldName, Op::NEX, '', '');
     }
 }

src/Find.php

@@ -51,7 +51,7 @@ class Find
      *
      * @template TDoc The type of document to be retrieved
      * @param string $tableName The table from which documents should be retrieved
-     * @param array|Field[] $fields The field comparison to match
+     * @param Field[] $fields The field comparison to match
      * @param class-string<TDoc> $className The name of the class to be retrieved
      * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
      * @return DocumentList<TDoc> A list of documents matching the given field comparison
@@ -70,7 +70,7 @@ class Find
      *
      * @template TDoc The type of document to be retrieved
      * @param string $tableName The name of the table from which documents should be retrieved
-     * @param array|object $criteria The criteria for the JSON containment query
+     * @param mixed[]|object $criteria The criteria for the JSON containment query
      * @param class-string<TDoc> $className The name of the class to be retrieved
      * @return DocumentList<TDoc> A list of documents matching the JSON containment query
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
@@ -101,7 +101,7 @@ class Find
      *
      * @template TDoc The type of document to be retrieved
      * @param string $tableName The table from which the document should be retrieved
-     * @param array|Field[] $fields The field comparison to match
+     * @param Field[] $fields The field comparison to match
      * @param class-string<TDoc> $className The name of the class to be retrieved
      * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
      * @return Option<TDoc> A `Some` instance with the first document if any matches are found, `None` otherwise
@@ -120,7 +120,7 @@ class Find
      *
      * @template TDoc The type of document to be retrieved
      * @param string $tableName The name of the table from which documents should be retrieved
-     * @param array|object $criteria The criteria for the JSON containment query
+     * @param mixed[]|object $criteria The criteria for the JSON containment query
      * @param class-string<TDoc> $className The name of the class to be retrieved
      * @return Option<TDoc> A `Some` instance with the first document if any matches are found, `None` otherwise
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs

src/Mapper/ArrayMapper.php

@@ -10,10 +10,15 @@ namespace BitBadger\PDODocument\Mapper;
 
 /**
  * A mapper that returns the associative array from the database
+ *
+ * @implements Mapper<array<string|int, mixed>>
  */
 class ArrayMapper implements Mapper
 {
-    /** @inheritDoc */
+    /**
+     * @inheritDoc
+     * @return array<string|int, mixed> The array given as the parameter
+     */
     public function map(array $result): array
     {
         return $result;

src/Mapper/CountMapper.php

@@ -10,6 +10,8 @@ namespace BitBadger\PDODocument\Mapper;
 
 /**
  * A mapper that returns the integer value of the first item in the results
+ *
+ * @implements Mapper<int>
  */
 class CountMapper implements Mapper
 {

src/Mapper/DocumentMapper.php

@@ -31,7 +31,7 @@ class DocumentMapper implements Mapper
     /**
      * Map a result to a domain class instance
      *
-     * @param array $result An associative array representing a single database result
+     * @param array<string|int, mixed> $result An associative array representing a single database result
      * @return TDoc The document, deserialized from its JSON representation
      * @throws DocumentException If the JSON cannot be deserialized
      */

src/Mapper/ExistsMapper.php

@@ -13,6 +13,8 @@ use Exception;
 
 /**
  * Map an EXISTS result to a boolean value
+ *
+ * @implements Mapper<bool>
  */
 class ExistsMapper implements Mapper
 {

src/Mapper/Mapper.php

@@ -18,7 +18,7 @@ interface Mapper
     /**
      * Map a result to the specified type
      *
-     * @param array $result An associative array representing a single database result
+     * @param array<string|int, mixed> $result An associative array representing a single database result
      * @return T The item mapped from the given result
      */
     public function map(array $result): mixed;

src/Parameters.php

@@ -19,19 +19,19 @@ class Parameters
      * Create an ID parameter (name ":id", key will be treated as a string)
      *
      * @param mixed $key The key representing the ID of the document
-     * @return array|string[] An associative array with an "@id" parameter/value pair
+     * @return array<string, mixed> An associative array with an "@id" parameter/value pair
      */
     public static function id(mixed $key): array
     {
-        return [':id' => is_int($key) || is_string($key) ? $key : "$key"];
+        return [':id' => ((is_int($key) || is_string($key)) ? $key : "$key")];
     }
 
     /**
      * Create a parameter with a JSON value
      *
      * @param string $name The name of the JSON parameter
-     * @param object|array $document The value that should be passed as a JSON string
+     * @param mixed[]|object $document The value that should be passed as a JSON string
-     * @return array An associative array with the named parameter/value pair
+     * @return array<string, string> An associative array with the named parameter/value pair
      */
     public static function json(string $name, object|array $document): array
     {
@@ -74,8 +74,8 @@ class Parameters
      * Add field parameters to the given set of parameters
      *
      * @param Field[] $fields The fields being compared in the query
-     * @param array $parameters An associative array of parameters to which the fields should be added
+     * @param array<string, mixed> $parameters An associative array of parameters to which the fields should be added
-     * @return array An associative array of parameter names and values with the fields added
+     * @return array<string, mixed> An associative array of parameter names and values with the fields added
      */
     public static function addFields(array $fields, array $parameters): array
     {
@@ -87,7 +87,7 @@ class Parameters
      *
      * @param string $paramName The name of the parameter for the field names
      * @param string[] $fieldNames The names of the fields for the parameter
-     * @return array An associative array of parameter/value pairs for the field names
+     * @return array<string, string> An associative array of parameter/value pairs for the field names
      * @throws Exception If the database mode has not been set
      */
     public static function fieldNames(string $paramName, array $fieldNames): array

src/Patch.php

@@ -18,7 +18,7 @@ class Patch
      *
      * @param string $tableName The table in which the document should be patched
      * @param mixed $docId The ID of the document to be patched
-     * @param array|object $patch The object with which the document should be patched (will be JSON-encoded)
+     * @param mixed[]|object $patch The object with which the document should be patched (will be JSON-encoded)
      * @throws DocumentException If any is encountered (database mode must be set)
      */
     public static function byId(string $tableName, mixed $docId, array|object $patch): void
@@ -31,8 +31,8 @@ class Patch
      * Patch documents using a comparison on JSON fields
      *
      * @param string $tableName The table in which documents should be patched
-     * @param array|Field[] $fields The field comparison to match
+     * @param Field[] $fields The field comparison to match
-     * @param array|object $patch The object with which the documents should be patched (will be JSON-encoded)
+     * @param mixed[]|object $patch The object with which the documents should be patched (will be JSON-encoded)
      * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
      * @throws DocumentException If any is encountered
      */
@@ -48,8 +48,8 @@ class Patch
      * Patch documents using a JSON containment query (`@>`; PostgreSQL only)
      *
      * @param string $tableName The table in which documents should be patched
-     * @param array|object $criteria The JSON containment query values to match
+     * @param mixed[]|object $criteria The JSON containment query values to match
-     * @param array|object $patch The object with which the documents should be patched (will be JSON-encoded)
+     * @param mixed[]|object $patch The object with which the documents should be patched (will be JSON-encoded)
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
      */
     public static function byContains(string $tableName, array|object $criteria, array|object $patch): void
@@ -63,7 +63,7 @@ class Patch
      *
      * @param string $tableName The table in which documents should be patched
      * @param string $path The JSON Path match string
-     * @param array|object $patch The object with which the documents should be patched (will be JSON-encoded)
+     * @param mixed[]|object $patch The object with which the documents should be patched (will be JSON-encoded)
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
      */
     public static function byJsonPath(string $tableName, string $path, array|object $patch): void

src/Query/Definition.php

@@ -49,7 +49,7 @@ class Definition
      *
      * @param string $tableName The name of the table which should be indexed
      * @param string $indexName The name of the index to create
-     * @param array $fields An array of fields to be indexed; may contain direction (ex. 'salary DESC')
+     * @param string[] $fields An array of fields to be indexed; may contain direction (ex. 'salary DESC')
      * @return string The CREATE INDEX statement to ensure the index exists
      */
     public static function ensureIndexOn(string $tableName, string $indexName, array $fields): string

src/Query/RemoveFields.php

@@ -24,7 +24,7 @@ class RemoveFields
      * Create an UPDATE statement to remove fields from a JSON document
      *
      * @param string $tableName The name of the table in which documents should be manipulated
-     * @param array $parameters The parameter list for the query
+     * @param array<string, mixed> $parameters The parameter list for the query
      * @param string $whereClause The body of the WHERE clause for the update
      * @return string The UPDATE statement to remove fields from a JSON document
      * @throws Exception If the database mode has not been set
@@ -43,7 +43,7 @@ class RemoveFields
      * Query to remove fields from a document by the document's ID
      *
      * @param string $tableName The name of the table in which the document should be manipulated
-     * @param array $parameters The parameter list for the query
+     * @param array<string, mixed> $parameters The parameter list for the query
      * @param mixed $docId The ID of the document from which fields should be removed (optional; string ID assumed)
      * @return string The UPDATE statement to remove fields from a document by its ID
      * @throws DocumentException If the database mode has not been set
@@ -57,8 +57,8 @@ class RemoveFields
      * Query to remove fields from documents via a comparison on JSON fields within the document
      *
      * @param string $tableName The name of the table in which documents should be manipulated
-     * @param array|Field[] $fields The field comparison to match
+     * @param Field[] $fields The field comparison to match
-     * @param array $parameters The parameter list for the query
+     * @param array<string, mixed> $parameters The parameter list for the query
      * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
      * @return string The UPDATE statement to remove fields from documents via field comparison
      * @throws DocumentException If the database mode has not been set
@@ -73,7 +73,7 @@ class RemoveFields
      * Query to remove fields from documents via a JSON containment query (PostgreSQL only)
      *
      * @param string $tableName The name of the table in which documents should be manipulated
-     * @param array $parameters The parameter list for the query
+     * @param array<string, mixed> $parameters The parameter list for the query
      * @return string The UPDATE statement to remove fields from documents via a JSON containment query
      * @throws DocumentException If the database mode is not PostgreSQL
      */
@@ -86,7 +86,7 @@ class RemoveFields
      * Query to remove fields from documents via a JSON Path match query (PostgreSQL only)
      *
      * @param string $tableName The name of the table in which documents should be manipulated
-     * @param array $parameters The parameter list for the query
+     * @param array<string, mixed> $parameters The parameter list for the query
      * @return string The UPDATE statement to remove fields from documents via a JSON Path match
      * @throws DocumentException
      */

src/RemoveFields.php

@@ -18,7 +18,7 @@ class RemoveFields
      *
      * @param string $tableName The table in which the document should have fields removed
      * @param mixed $docId The ID of the document from which fields should be removed
-     * @param array|string[] $fieldNames The names of the fields to be removed
+     * @param string[] $fieldNames The names of the fields to be removed
      * @throws DocumentException If any is encountered
      */
     public static function byId(string $tableName, mixed $docId, array $fieldNames): void
@@ -32,8 +32,8 @@ class RemoveFields
      * Remove fields from documents via a comparison on a JSON field in the document
      *
      * @param string $tableName The table in which documents should have fields removed
-     * @param array|Field[] $fields The field comparison to match
+     * @param Field[] $fields The field comparison to match
-     * @param array|string[] $fieldNames The names of the fields to be removed
+     * @param string[] $fieldNames The names of the fields to be removed
      * @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
      * @throws DocumentException If any is encountered
      */
@@ -50,8 +50,8 @@ class RemoveFields
      * Remove fields from documents via a JSON containment query (`@>`; PostgreSQL only)
      *
      * @param string $tableName The table in which documents should have fields removed
-     * @param array|object $criteria The JSON containment query values
+     * @param mixed[]|object $criteria The JSON containment query values
-     * @param array|string[] $fieldNames The names of the fields to be removed
+     * @param string[] $fieldNames The names of the fields to be removed
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
      */
     public static function byContains(string $tableName, array|object $criteria, array $fieldNames): void
@@ -66,7 +66,7 @@ class RemoveFields
      *
      * @param string $tableName The table in which documents should have fields removed
      * @param string $path The JSON Path match string
-     * @param array|string[] $fieldNames The names of the fields to be removed
+     * @param string[] $fieldNames The names of the fields to be removed
      * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
      */
     public static function byJsonPath(string $tableName, string $path, array $fieldNames): void

tests/PjsonId.php

@@ -13,7 +13,7 @@ use Square\Pjson\JsonDataSerializable;
 /**
  * A serializable ID wrapper class
  */
-class PjsonId implements JsonDataSerializable
+final class PjsonId implements JsonDataSerializable
 {
     public function __construct(protected string $value) { }
 
@@ -22,6 +22,11 @@ class PjsonId implements JsonDataSerializable
         return $this->value;
     }
 
+    /**
+     * @param mixed $jd JSON data
+     * @param mixed[]|string $path path segments
+     * @return static
+     */
     public static function fromJsonData($jd, array|string $path = []): static
     {
         return new static($jd);

tests/integration/postgresql/CustomTest.php

@@ -34,7 +34,7 @@ class CustomTest extends TestCase
         ThrowawayDb::destroy($this->dbName);
     }
 
-    public function testRunQuerySucceedsWithAValidQuery()
+    public function testRunQuerySucceedsWithAValidQuery(): void
     {
         $stmt = &Custom::runQuery('SELECT data FROM ' . ThrowawayDb::TABLE . ' LIMIT 1', []);
         try {
@@ -44,7 +44,7 @@ class CustomTest extends TestCase
         }
     }
 
-    public function testRunQueryFailsWithAnInvalidQuery()
+    public function testRunQueryFailsWithAnInvalidQuery(): void
     {
         $this->expectException(DocumentException::class);
         $stmt = &Custom::runQuery('GRAB stuff FROM over_there UNTIL done', []);
@@ -55,7 +55,7 @@ class CustomTest extends TestCase
         }
     }
 
-    public function testListSucceedsWhenDataIsFound()
+    public function testListSucceedsWhenDataIsFound(): void
     {
         $list = Custom::list(Query::selectFromTable(ThrowawayDb::TABLE), [], new DocumentMapper(TestDocument::class));
         $this->assertNotNull($list, 'The document list should not be null');
@@ -64,7 +64,7 @@ class CustomTest extends TestCase
         $this->assertEquals(5, $count, 'There should have been 5 documents in the list');
     }
 
-    public function testListSucceedsWhenNoDataIsFound()
+    public function testListSucceedsWhenNoDataIsFound(): void
     {
         $list = Custom::list(
             Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE (data->>'num_value')::numeric > :value",
@@ -73,7 +73,7 @@ class CustomTest extends TestCase
         $this->assertFalse($list->hasItems(), 'There should have been no documents in the list');
     }
 
-    public function testArraySucceedsWhenDataIsFound()
+    public function testArraySucceedsWhenDataIsFound(): void
     {
         $array = Custom::array(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'sub' IS NOT NULL", [],
             new DocumentMapper(TestDocument::class));
@@ -81,7 +81,7 @@ class CustomTest extends TestCase
         $this->assertCount(2, $array, 'There should have been 2 documents in the array');
     }
 
-    public function testArraySucceedsWhenNoDataIsFound()
+    public function testArraySucceedsWhenNoDataIsFound(): void
     {
         $array = Custom::array(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'value' = :value",
             [':value' => 'not there'], new DocumentMapper(TestDocument::class));
@@ -104,14 +104,14 @@ class CustomTest extends TestCase
         $this->assertTrue($doc->isNone(), 'There should not have been a document returned');
     }
 
-    public function testNonQuerySucceedsWhenOperatingOnData()
+    public function testNonQuerySucceedsWhenOperatingOnData(): void
     {
         Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
         $remaining = Count::all(ThrowawayDb::TABLE);
         $this->assertEquals(0, $remaining, 'There should be no documents remaining in the table');
     }
 
-    public function testNonQuerySucceedsWhenNoDataMatchesWhereClause()
+    public function testNonQuerySucceedsWhenNoDataMatchesWhereClause(): void
     {
         Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE . " WHERE (data->>'num_value')::numeric > :value",
             [':value' => 100]);
@@ -119,7 +119,7 @@ class CustomTest extends TestCase
         $this->assertEquals(5, $remaining, 'There should be 5 documents remaining in the table');
     }
 
-    public function testScalarSucceeds()
+    public function testScalarSucceeds(): void
     {
         $value = Custom::scalar("SELECT 5 AS it", [], new CountMapper());
         $this->assertEquals(5, $value, 'The scalar value was not returned correctly');

tests/integration/sqlite/CustomTest.php

@@ -34,7 +34,7 @@ class CustomTest extends TestCase
         ThrowawayDb::destroy($this->dbName);
     }
 
-    public function testRunQuerySucceedsWithAValidQuery()
+    public function testRunQuerySucceedsWithAValidQuery(): void
     {
         $stmt = &Custom::runQuery('SELECT data FROM ' . ThrowawayDb::TABLE . ' LIMIT 1', []);
         try {
@@ -44,7 +44,7 @@ class CustomTest extends TestCase
         }
     }
 
-    public function testRunQueryFailsWithAnInvalidQuery()
+    public function testRunQueryFailsWithAnInvalidQuery(): void
     {
         $this->expectException(DocumentException::class);
         $stmt = &Custom::runQuery('GRAB stuff FROM over_there UNTIL done', []);
@@ -55,7 +55,7 @@ class CustomTest extends TestCase
         }
     }
 
-    public function testListSucceedsWhenDataIsFound()
+    public function testListSucceedsWhenDataIsFound(): void
     {
         $list = Custom::list(Query::selectFromTable(ThrowawayDb::TABLE), [], new DocumentMapper(TestDocument::class));
         $this->assertNotNull($list, 'The document list should not be null');
@@ -64,7 +64,7 @@ class CustomTest extends TestCase
         $this->assertEquals(5, $count, 'There should have been 5 documents in the list');
     }
 
-    public function testListSucceedsWhenNoDataIsFound()
+    public function testListSucceedsWhenNoDataIsFound(): void
     {
         $list = Custom::list(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'num_value' > :value",
             [':value' => 100], new DocumentMapper(TestDocument::class));
@@ -72,7 +72,7 @@ class CustomTest extends TestCase
         $this->assertFalse($list->hasItems(), 'There should have been no documents in the list');
     }
 
-    public function testArraySucceedsWhenDataIsFound()
+    public function testArraySucceedsWhenDataIsFound(): void
     {
         $array = Custom::array(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'sub' IS NOT NULL", [],
             new DocumentMapper(TestDocument::class));
@@ -80,7 +80,7 @@ class CustomTest extends TestCase
         $this->assertCount(2, $array, 'There should have been 2 documents in the array');
     }
 
-    public function testArraySucceedsWhenNoDataIsFound()
+    public function testArraySucceedsWhenNoDataIsFound(): void
     {
         $array = Custom::array(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'value' = :value",
             [':value' => 'not there'], new DocumentMapper(TestDocument::class));
@@ -103,21 +103,21 @@ class CustomTest extends TestCase
         $this->assertTrue($doc->isNone(), 'There should not have been a document returned');
     }
 
-    public function testNonQuerySucceedsWhenOperatingOnData()
+    public function testNonQuerySucceedsWhenOperatingOnData(): void
     {
         Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []);
         $remaining = Count::all(ThrowawayDb::TABLE);
         $this->assertEquals(0, $remaining, 'There should be no documents remaining in the table');
     }
 
-    public function testNonQuerySucceedsWhenNoDataMatchesWhereClause()
+    public function testNonQuerySucceedsWhenNoDataMatchesWhereClause(): void
     {
         Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE . " WHERE data->>'num_value' > :value", [':value' => 100]);
         $remaining = Count::all(ThrowawayDb::TABLE);
         $this->assertEquals(5, $remaining, 'There should be 5 documents remaining in the table');
     }
 
-    public function testScalarSucceeds()
+    public function testScalarSucceeds(): void
     {
         $value = Custom::scalar("SELECT 5 AS it", [], new CountMapper());
         $this->assertEquals(5, $value, 'The scalar value was not returned correctly');

tests/unit/ConfigurationTest.php

@@ -25,7 +25,7 @@ class ConfigurationTest extends TestCase
     }
 
     #[TestDox('ID field change succeeds')]
-    public function testIdFieldChangeSucceeds()
+    public function testIdFieldChangeSucceeds(): void
     {
         try {
             Configuration::$idField = 'EyeDee';

tests/unit/Mapper/StringMapperTest.php

@@ -18,21 +18,21 @@ use PHPUnit\Framework\TestCase;
 #[TestDox('String Mapper (Unit tests)')]
 class StringMapperTest extends TestCase
 {
-    public function testMapSucceedsWhenFieldIsPresentAndString()
+    public function testMapSucceedsWhenFieldIsPresentAndString(): void
     {
         $result = ['test_field' => 'test_value'];
         $mapper = new StringMapper('test_field');
         $this->assertEquals('test_value', $mapper->map($result), 'String value not returned correctly');
     }
 
-    public function testMapSucceedsWhenFieldIsPresentAndNotString()
+    public function testMapSucceedsWhenFieldIsPresentAndNotString(): void
     {
         $result = ['a_number' => 6.7];
         $mapper = new StringMapper('a_number');
         $this->assertEquals('6.7', $mapper->map($result), 'Number value not returned correctly');
     }
 
-    public function testMapSucceedsWhenFieldIsNotPresent()
+    public function testMapSucceedsWhenFieldIsNotPresent(): void
     {
         $mapper = new StringMapper('something_else');
         $this->assertNull($mapper->map([]), 'Missing value not returned correctly');

tests/unit/Query/RemoveFieldsTest.php

@@ -48,7 +48,7 @@ class RemoveFieldsTest extends TestCase
     }
 
     #[TestDox('By ID succeeds for PostgreSQL')]
-    public function testByIdSucceedsForPostgreSQL()
+    public function testByIdSucceedsForPostgreSQL(): void
     {
         Configuration::overrideMode(Mode::PgSQL);
         $this->assertEquals("UPDATE churro SET data = data - :bite::text[] WHERE data->>'id' = :id",
@@ -56,7 +56,7 @@ class RemoveFieldsTest extends TestCase
     }
 
     #[TestDox('By ID succeeds for SQLite')]
-    public function testByIdSucceedsForSQLite()
+    public function testByIdSucceedsForSQLite(): void
     {
         Configuration::overrideMode(Mode::SQLite);
         $this->assertEquals("UPDATE quesadilla SET data = json_remove(data, :bite0) WHERE data->>'id' = :id",
@@ -72,7 +72,7 @@ class RemoveFieldsTest extends TestCase
     }
 
     #[TestDox('By fields succeeds for PostgreSQL')]
-    public function testByFieldsSucceedsForPostgreSQL()
+    public function testByFieldsSucceedsForPostgreSQL(): void
     {
         Configuration::overrideMode(Mode::PgSQL);
         $this->assertEquals("UPDATE enchilada SET data = data - :sauce::text[] WHERE data->>'cheese' = :queso",
@@ -82,7 +82,7 @@ class RemoveFieldsTest extends TestCase
     }
 
     #[TestDox('By fields succeeds for SQLite')]
-    public function testByFieldsSucceedsForSQLite()
+    public function testByFieldsSucceedsForSQLite(): void
     {
         Configuration::overrideMode(Mode::SQLite);
         $this->assertEquals(

tests/unit/QueryTest.php

@@ -207,7 +207,7 @@ class QueryTest extends TestCase
             Query::save('test_tbl'), 'INSERT ON CONFLICT statement not constructed correctly');
     }
 
-    public function testUpdateSucceeds()
+    public function testUpdateSucceeds(): void
     {
         $this->assertEquals("UPDATE testing SET data = :data WHERE data->>'id' = :id", Query::update('testing'),
             'UPDATE statement not constructed correctly');