composer.json

@@ -1,7 +1,8 @@
 {
   "name": "bit-badger/pdo-document",
   "require": {
-    "netresearch/jsonmapper": "^4"
+    "netresearch/jsonmapper": "^4",
+    "ext-pdo": "*"
   },
   "require-dev": {
     "phpunit/phpunit": "^11"

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": "38b71eefd32cb528da22dd5908fb8d02",
+    "content-hash": "eada4b7eb6f976e0aaf0b54b92e2ca32",
     "packages": [
         {
             "name": "netresearch/jsonmapper",
@@ -1696,7 +1696,9 @@
     "stability-flags": [],
     "prefer-stable": false,
     "prefer-lowest": false,
-    "platform": [],
+    "platform": {
+        "ext-pdo": "*"
+    },
     "platform-dev": [],
     "plugin-api-version": "2.6.0"
 }

src/Document.php

@@ -34,4 +34,19 @@ class Document
     {
         Custom::nonQuery(Query::save($tableName), Parameters::json('@data', $document), $pdo);
     }
+
+    /**
+     * Update (replace) an entire document by its ID
+     *
+     * @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 PDO|null $pdo The database connection to use (optional; will obtain one if not provided)
+     * @throws DocumentException If any is encountered
+     */
+    public static function update(string $tableName, mixed $docId, array|object $document, ?PDO $pdo = null): void
+    {
+        Custom::nonQuery(Query::update($tableName),
+            array_merge(Parameters::id($docId), Parameters::json('@data', $document)), $pdo);
+    }
 }

src/Exists.php

@@ -0,0 +1,44 @@
+<?php declare(strict_types=1);
+
+namespace BitBadger\PDODocument;
+
+use BitBadger\PDODocument\Mapper\ExistsMapper;
+use PDO;
+
+/**
+ * Functions to determine if documents exist
+ */
+class Exists
+{
+    /**
+     * Determine if a document exists for the given ID
+     *
+     * @param string $tableName The name of the table in which document existence should be determined
+     * @param mixed $docId The ID of the document whose existence should be determined
+     * @param PDO|null $pdo The database connection to use (optional; will obtain one if not provided)
+     * @return bool True if the document exists, false if not
+     * @throws DocumentException If any is encountered
+     */
+    public static function byId(string $tableName, mixed $docId, ?PDO $pdo = null): bool
+    {
+        return Custom::scalar(Query\Exists::byId($tableName), Parameters::id($docId), new ExistsMapper(), $pdo);
+    }
+
+    /**
+     * Determine if a document exists using a comparison on JSON fields
+     *
+     * @param string $tableName The name of the table in which document existence should be determined
+     * @param Field[] $fields The field comparison to match
+     * @param PDO|null $pdo The database connection to use (optional; will obtain one if not provided)
+     * @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
+     * @return bool True if any documents match the field comparison, false if not
+     * @throws DocumentException If any is encountered
+     */
+    public static function byFields(string $tableName, array $fields, ?PDO $pdo = null,
+                                    string $conjunction = 'AND'): bool
+    {
+        $namedFields = Parameters::nameFields($fields);
+        return Custom::scalar(Query\Exists::byFields($tableName, $namedFields, $conjunction),
+            Parameters::addFields($namedFields, []), new ExistsMapper(), $pdo);
+    }
+}

src/Find.php

@@ -0,0 +1,78 @@
+<?php declare(strict_types=1);
+
+namespace BitBadger\PDODocument;
+
+use BitBadger\PDODocument\Mapper\DocumentMapper;
+
+/**
+ * Functions to find documents
+ */
+class Find
+{
+    /**
+     * Retrieve all documents in the given table
+     *
+     * @template TDoc The type of document to be retrieved
+     * @param string $tableName The table from which documents should be retrieved
+     * @param class-string<TDoc> $className The name of the class to be retrieved
+     * @return DocumentList<TDoc> A list of all documents from the table
+     * @throws DocumentException If any is encountered
+     */
+    public static function all(string $tableName, string $className): DocumentList
+    {
+        return Custom::list(Query::selectFromTable($tableName), [], new DocumentMapper($className));
+    }
+
+    /**
+     * Retrieve a document by its ID (returns false if not found)
+     *
+     * @template TDoc The type of document to be retrieved
+     * @param string $tableName The table from which the document should be retrieved
+     * @param mixed $docId The ID of the document to retrieve
+     * @param class-string<TDoc> $className The name of the class to be retrieved
+     * @return false|TDoc The document if it exists, false if not
+     * @throws DocumentException If any is encountered
+     */
+    public static function byId(string $tableName, mixed $docId, string $className): mixed
+    {
+        return Custom::single(Query\Find::byId($tableName), Parameters::id($docId), new DocumentMapper($className));
+    }
+
+    /**
+     * Retrieve documents via a comparison on JSON fields
+     *
+     * @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 class-string<TDoc> $className The name of the class to be retrieved
+     * @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
+     * @return DocumentList<TDoc> A list of documents matching the given field comparison
+     * @throws DocumentException If any is encountered
+     */
+    public static function byFields(string $tableName, array $fields, string $className,
+                                    string $conjunction = 'AND'): DocumentList
+    {
+        $namedFields = Parameters::nameFields($fields);
+        return Custom::list(Query\Find::byFields($tableName, $namedFields, $conjunction),
+            Parameters::addFields($namedFields, []), new DocumentMapper($className));
+    }
+
+    /**
+     * Retrieve documents via a comparison on JSON fields, returning only the first result
+     *
+     * @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 class-string<TDoc> $className The name of the class to be retrieved
+     * @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
+     * @return false|TDoc The first document if any matches are found, false otherwise
+     * @throws DocumentException If any is encountered
+     */
+    public static function firstByFields(string $tableName, array $fields, string $className,
+                                         string $conjunction = 'AND'): mixed
+    {
+        $namedFields = Parameters::nameFields($fields);
+        return Custom::single(Query\Find::byFields($tableName, $namedFields, $conjunction),
+            Parameters::addFields($namedFields, []), new DocumentMapper($className));
+    }
+}

src/Mapper/DocumentMapper.php

@@ -3,6 +3,7 @@
 namespace BitBadger\PDODocument\Mapper;
 
 use BitBadger\PDODocument\DocumentException;
+use JsonMapper;
 use JsonMapper_Exception;
 
 /**
@@ -11,7 +12,7 @@ use JsonMapper_Exception;
  * @template TDoc The type of document returned by this mapper
  * @implements Mapper<TDoc> Provide a mapping from JSON
  */
-class JsonMapper implements Mapper
+class DocumentMapper implements Mapper
 {
     /**
      * Constructor
@@ -35,7 +36,7 @@ class JsonMapper implements Mapper
             if (is_null($json)) {
                 throw new DocumentException("Could not map document for $this->className: " . json_last_error_msg());
             }
-            return (new \JsonMapper())->map($json, $this->className);
+            return (new JsonMapper())->map($json, $this->className);
         } catch (JsonMapper_Exception $ex) {
             throw new DocumentException("Could not map document for $this->className", previous: $ex);
         }

src/Patch.php

@@ -0,0 +1,44 @@
+<?php declare(strict_types=1);
+
+namespace BitBadger\PDODocument;
+
+use PDO;
+
+/**
+ * Functions to patch (partially update) documents
+ */
+class Patch
+{
+    /**
+     * Patch a document by its ID
+     *
+     * @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 PDO|null $pdo The database connection to use (optional; will obtain one if not provided)
+     * @throws DocumentException If any is encountered (database mode must be set)
+     */
+    public static function byId(string $tableName, mixed $docId, array|object $patch, ?PDO $pdo = null): void
+    {
+        Custom::nonQuery(Query\Patch::byId($tableName),
+            array_merge(Parameters::id($docId), Parameters::json('@data', $patch)), $pdo);
+    }
+
+    /**
+     * 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 array|object $patch The object with which the documents should be patched (will be JSON-encoded)
+     * @param PDO|null $pdo The database connection to use (optional; will obtain one if not provided)
+     * @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
+     * @throws DocumentException If any is encountered
+     */
+    public static function byFields(string $tableName, array $fields, array|object $patch, ?PDO $pdo = null,
+                                    string $conjunction = 'AND'): void
+    {
+        $namedFields = Parameters::nameFields($fields);
+        Custom::nonQuery(Query\Patch::byFields($tableName, $namedFields, $conjunction),
+            Parameters::addFields($namedFields, Parameters::json('@data', $patch)), $pdo);
+    }
+}

src/Query/RemoveFields.php

@@ -0,0 +1,70 @@
+<?php declare(strict_types=1);
+
+namespace BitBadger\PDODocument\Query;
+
+use BitBadger\PDODocument\Configuration;
+use BitBadger\PDODocument\DocumentException;
+use BitBadger\PDODocument\Field;
+use BitBadger\PDODocument\Mode;
+use BitBadger\PDODocument\Query;
+
+/**
+ * Queries to remove fields from documents
+ *
+ * _NOTE: When using these queries to build custom functions, be aware that different databases use significantly
+ *        different syntax. The `$parameters` passed to these functions should be run through `Parameters::fieldNames`
+ *        function to generate them appropriately for the database currently being targeted._
+ */
+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 string $whereClause The body of the WHERE clause for the update
+     * @return string The UPDATE statement to remove fields from a JSON document
+     * @throws DocumentException If the database mode has not been set
+     */
+    public static function update(string $tableName, array $parameters, string $whereClause): string
+    {
+        switch (Configuration::$mode) {
+            case Mode::PgSQL:
+                return "UPDATE $tableName SET data = data - " . array_keys($parameters)[0] . " WHERE $whereClause";
+            case Mode::SQLite:
+                $paramNames = implode(', ', array_keys($parameters));
+                return "UPDATE $tableName SET data = json_remove(data, $paramNames) WHERE $whereClause";
+            default:
+                throw new DocumentException('Database mode not set; cannot generate field removal query');
+        }
+    }
+
+    /**
+     * 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
+     * @return string The UPDATE statement to remove fields from a document by its ID
+     * @throws DocumentException If the database mode has not been set
+     */
+    public static function byId(string $tableName, array $parameters): string
+    {
+        return self::update($tableName, $parameters, Query::whereById());
+    }
+
+    /**
+     * 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 array $parameters The parameter list for the query
+     * @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
+     * @return string The UPDATE statement to remove fields from documents via field comparison
+     * @throws DocumentException If the database mode has not been set
+     */
+    public static function byFields(string $tableName, array $fields, array $parameters,
+                                    string $conjunction = 'AND'): string
+    {
+        return self::update($tableName, $parameters, Query::whereByFields($fields, $conjunction));
+    }
+}

src/RemoveFields.php

@@ -0,0 +1,46 @@
+<?php declare(strict_types=1);
+
+namespace BitBadger\PDODocument;
+
+use PDO;
+
+/**
+ * Functions to remove fields from documents
+ */
+class RemoveFields
+{
+    /**
+     * Remove fields from a document by the document's ID
+     *
+     * @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 PDO|null $pdo The database connection to use (optional; will obtain one if not provided)
+     * @throws DocumentException If any is encountered
+     */
+    public static function byId(string $tableName, mixed $docId, array $fieldNames, ?PDO $pdo = null): void
+    {
+        $nameParams = Parameters::fieldNames('@name', $fieldNames);
+        Custom::nonQuery(Query\RemoveFields::byId($tableName, $nameParams),
+            array_merge(Parameters::id($docId), $nameParams), $pdo);
+    }
+
+    /**
+     * 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 array|string[] $fieldNames The names of the fields to be removed
+     * @param PDO|null $pdo The database connection to use (optional; will obtain one if not provided)
+     * @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
+     * @throws DocumentException If any is encountered
+     */
+    public static function byFields(string $tableName, array $fields, array $fieldNames, ?PDO $pdo = null,
+                                    string $conjunction = 'AND'): void
+    {
+        $nameParams  = Parameters::fieldNames('@name', $fieldNames);
+        $namedFields = Parameters::nameFields($fields);
+        Custom::nonQuery(Query\RemoveFields::byFields($tableName, $namedFields, $nameParams, $conjunction),
+            Parameters::addFields($namedFields, $nameParams), $pdo);
+    }
+}

tests/unit/Mapper/DocumentMapperTest.php

@@ -4,7 +4,7 @@ namespace Test\Unit\Mapper;
 
 use BitBadger\PDODocument\DocumentException;
 use BitBadger\PDODocument\Field;
-use BitBadger\PDODocument\Mapper\JsonMapper;
+use BitBadger\PDODocument\Mapper\DocumentMapper;
 use PHPUnit\Framework\Attributes\TestDox;
 use PHPUnit\Framework\TestCase;
 
@@ -21,26 +21,26 @@ class TestDocument
 }
 
 /**
- * Unit tests for the JsonMapper class
+ * Unit tests for the DocumentMapper class
  */
-class JsonMapperTest extends TestCase
+class DocumentMapperTest extends TestCase
 {
     public function testConstructorSucceedsWithDefaultField(): void
     {
-        $mapper = new JsonMapper(Field::class);
+        $mapper = new DocumentMapper(Field::class);
         $this->assertEquals('data', $mapper->fieldName, 'Default field name should have been "data"');
     }
 
     public function testConstructorSucceedsWithSpecifiedField(): void
     {
-        $mapper = new JsonMapper(Field::class, 'json');
+        $mapper = new DocumentMapper(Field::class, 'json');
         $this->assertEquals('json', $mapper->fieldName, 'Field name not recorded correctly');
     }
 
     #[TestDox('Map succeeds with valid JSON')]
     public function testMapSucceedsWithValidJSON(): void
     {
-        $doc = (new JsonMapper(TestDocument::class))->map(['data' => '{"id":7,"subDoc":{"id":22,"name":"tester"}}']);
+        $doc = (new DocumentMapper(TestDocument::class))->map(['data' => '{"id":7,"subDoc":{"id":22,"name":"tester"}}']);
         $this->assertNotNull($doc, 'The document should not have been null');
         $this->assertEquals(7, $doc->id, 'ID not filled correctly');
         $this->assertNotNull($doc->subDoc, 'The sub-document should not have been null');
@@ -52,6 +52,6 @@ class JsonMapperTest extends TestCase
     public function testMapFailsWithInvalidJSON(): void
     {
         $this->expectException(DocumentException::class);
-        (new JsonMapper(TestDocument::class))->map(['data' => 'this is not valid']);
+        (new DocumentMapper(TestDocument::class))->map(['data' => 'this is not valid']);
     }
 }