From 65fd46835cca8c3649911d9d1728a4d5b413d3bf Mon Sep 17 00:00:00 2001 From: "Daniel J. Summers" Date: Wed, 12 Jun 2024 15:21:53 -0400 Subject: [PATCH 1/4] Add PostgreSQL version of SQLite integ tests - Add PostgreSQL throwaway database - Add optional length parameter for random string - Fix syntax for PostgreSQL in several areas - Add optional ID for whereById type determination --- .gitignore | 1 + README.md | 2 +- composer.json | 1 + composer.lock | 12 +- src/AutoId.php | 5 +- src/Delete.php | 2 +- src/Exists.php | 2 +- src/Field.php | 26 +- src/Find.php | 3 +- src/Parameters.php | 2 +- src/Patch.php | 2 +- src/Query.php | 15 +- src/Query/Delete.php | 5 +- src/Query/Exists.php | 5 +- src/Query/Find.php | 5 +- src/Query/Patch.php | 5 +- src/Query/RemoveFields.php | 8 +- src/RemoveFields.php | 2 +- tests/integration/postgresql/CountTest.php | 47 +++ tests/integration/postgresql/CustomTest.php | 121 +++++++ .../integration/postgresql/DefinitionTest.php | 60 ++++ tests/integration/postgresql/DeleteTest.php | 59 ++++ .../postgresql/DocumentListTest.php | 74 +++++ tests/integration/postgresql/DocumentTest.php | 302 ++++++++++++++++++ tests/integration/postgresql/ExistsTest.php | 54 ++++ tests/integration/postgresql/FindTest.php | 108 +++++++ tests/integration/postgresql/PatchTest.php | 59 ++++ .../postgresql/RemoveFieldsTest.php | 74 +++++ tests/integration/postgresql/ThrowawayDb.php | 75 +++++ tests/integration/sqlite/FindTest.php | 2 - tests/integration/sqlite/PatchTest.php | 1 - tests/integration/sqlite/ThrowawayDb.php | 30 +- tests/unit/FieldTest.php | 4 +- tests/unit/ParametersTest.php | 2 +- tests/unit/Query/PatchTest.php | 2 +- tests/unit/Query/RemoveFieldsTest.php | 8 +- tests/unit/QueryTest.php | 10 +- 37 files changed, 1111 insertions(+), 84 deletions(-) create mode 100644 tests/integration/postgresql/CountTest.php create mode 100644 tests/integration/postgresql/CustomTest.php create mode 100644 tests/integration/postgresql/DefinitionTest.php create mode 100644 tests/integration/postgresql/DeleteTest.php create mode 100644 tests/integration/postgresql/DocumentListTest.php create mode 100644 tests/integration/postgresql/DocumentTest.php create mode 100644 tests/integration/postgresql/ExistsTest.php create mode 100644 tests/integration/postgresql/FindTest.php create mode 100644 tests/integration/postgresql/PatchTest.php create mode 100644 tests/integration/postgresql/RemoveFieldsTest.php create mode 100644 tests/integration/postgresql/ThrowawayDb.php diff --git a/.gitignore b/.gitignore index 3ce5adb..f28efc4 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ .idea vendor +*-tests.txt diff --git a/README.md b/README.md index 2692701..eba1cf7 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This library allows SQLite (and, by v1.0.0-beta1, PostgreSQL) to be treated as a ## Add via Composer -![Packagist Version](https://img.shields.io/packagist/v/bit-badger/pdo-document) +[![Packagist Version](https://img.shields.io/packagist/v/bit-badger/pdo-document)](https://packagist.org/packages/bit-badger/pdo-document) `composer require bit-badger/pdo-document` diff --git a/composer.json b/composer.json index 7adb8c7..7c2fddd 100644 --- a/composer.json +++ b/composer.json @@ -35,6 +35,7 @@ "psr-4": { "Test\\Unit\\": "./tests/unit", "Test\\Integration\\": "./tests/integration", + "Test\\Integration\\PostgreSQL\\": "./tests/integration/postgresql", "Test\\Integration\\SQLite\\": "./tests/integration/sqlite" } }, diff --git a/composer.lock b/composer.lock index 6d32386..2727155 100644 --- a/composer.lock +++ b/composer.lock @@ -619,16 +619,16 @@ }, { "name": "phpunit/phpunit", - "version": "11.2.0", + "version": "11.2.1", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/phpunit.git", - "reference": "705eba0190afe04bc057f565ad843267717cf109" + "reference": "1b8775732e9c401bda32df3ffbdf90dec7533ceb" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/705eba0190afe04bc057f565ad843267717cf109", - "reference": "705eba0190afe04bc057f565ad843267717cf109", + "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/1b8775732e9c401bda32df3ffbdf90dec7533ceb", + "reference": "1b8775732e9c401bda32df3ffbdf90dec7533ceb", "shasum": "" }, "require": { @@ -699,7 +699,7 @@ "support": { "issues": "https://github.com/sebastianbergmann/phpunit/issues", "security": "https://github.com/sebastianbergmann/phpunit/security/policy", - "source": "https://github.com/sebastianbergmann/phpunit/tree/11.2.0" + "source": "https://github.com/sebastianbergmann/phpunit/tree/11.2.1" }, "funding": [ { @@ -715,7 +715,7 @@ "type": "tidelift" } ], - "time": "2024-06-07T04:48:50+00:00" + "time": "2024-06-11T07:30:35+00:00" }, { "name": "sebastian/cli-parser", diff --git a/src/AutoId.php b/src/AutoId.php index 222ca69..60ddcba 100644 --- a/src/AutoId.php +++ b/src/AutoId.php @@ -41,11 +41,12 @@ enum AutoId /** * Generate a random string ID * + * @param int|null $length The length of string to generate (optional; defaults to configured ID string length) * @return string A string filled with the hexadecimal representation of random bytes * @throws RandomException If an appropriate source of randomness cannot be found */ - public static function generateRandom(): string + public static function generateRandom(?int $length = null): string { - return bin2hex(random_bytes(Configuration::$idStringLength / 2)); + return bin2hex(random_bytes(($length ?? Configuration::$idStringLength) / 2)); } } diff --git a/src/Delete.php b/src/Delete.php index ee4fcb8..22b84c8 100644 --- a/src/Delete.php +++ b/src/Delete.php @@ -16,7 +16,7 @@ class Delete */ public static function byId(string $tableName, mixed $docId): void { - Custom::nonQuery(Query\Delete::byId($tableName), Parameters::id($docId)); + Custom::nonQuery(Query\Delete::byId($tableName, $docId), Parameters::id($docId)); } /** diff --git a/src/Exists.php b/src/Exists.php index bc9e1a5..c668107 100644 --- a/src/Exists.php +++ b/src/Exists.php @@ -19,7 +19,7 @@ class Exists */ public static function byId(string $tableName, mixed $docId): bool { - return Custom::scalar(Query\Exists::byId($tableName), Parameters::id($docId), new ExistsMapper()); + return Custom::scalar(Query\Exists::byId($tableName, $docId), Parameters::id($docId), new ExistsMapper()); } /** diff --git a/src/Field.php b/src/Field.php index 04c4f68..745c1aa 100644 --- a/src/Field.php +++ b/src/Field.php @@ -52,23 +52,25 @@ class Field */ public function toWhere(): string { + $fieldName = ($this->qualifier == '' ? '' : "$this->qualifier.") . 'data' . match (true) { + !str_contains($this->fieldName, '.') => "->>'$this->fieldName'", + Configuration::$mode == Mode::PgSQL => "#>>'{" . implode(',', explode('.', $this->fieldName)) . "}'", + Configuration::$mode == Mode::SQLite => "->>'" . implode("'->>'", explode('.', $this->fieldName)) . "'", + default => throw new DocumentException('Database mode not set; cannot make field WHERE clause') + }; + $fieldPath = match (Configuration::$mode) { + Mode::PgSQL => match (true) { + $this->op == Op::BT => is_numeric($this->value[0]) ? "($fieldName)::numeric" : $fieldName, + is_numeric($this->value) => "($fieldName)::numeric", + default => $fieldName + }, + default => $fieldName + }; $criteria = match ($this->op) { Op::EX, Op::NEX => '', Op::BT => " {$this->paramName}min AND {$this->paramName}max", default => " $this->paramName" }; - $prefix = $this->qualifier == '' ? '' : "$this->qualifier."; - $fieldPath = match (Configuration::$mode) { - Mode::SQLite => "{$prefix}data->>'" - . (str_contains($this->fieldName, '.') - ? implode("'->>'", explode('.', $this->fieldName)) - : $this->fieldName) - . "'", - Mode::PgSQL => $this->op == Op::BT && is_numeric($this->value[0]) - ? "({$prefix}data->>'$this->fieldName')::numeric" - : "{$prefix}data->>'$this->fieldName'", - default => throw new DocumentException('Database mode not set; cannot make field WHERE clause') - }; return $fieldPath . ' ' . $this->op->toString() . $criteria; } diff --git a/src/Find.php b/src/Find.php index aae5b35..d6022f1 100644 --- a/src/Find.php +++ b/src/Find.php @@ -35,7 +35,8 @@ class Find */ public static function byId(string $tableName, mixed $docId, string $className): mixed { - return Custom::single(Query\Find::byId($tableName), Parameters::id($docId), new DocumentMapper($className)); + return Custom::single(Query\Find::byId($tableName, $docId), Parameters::id($docId), + new DocumentMapper($className)); } /** diff --git a/src/Parameters.php b/src/Parameters.php index e6dffad..7b63715 100644 --- a/src/Parameters.php +++ b/src/Parameters.php @@ -68,7 +68,7 @@ class Parameters { switch (Configuration::$mode) { case Mode::PgSQL: - return [$paramName => "ARRAY['" . implode("','", $fieldNames) . "']"]; + return [$paramName => "{" . implode(",", $fieldNames) . "}"]; case Mode::SQLite: $it = []; $idx = 0; diff --git a/src/Patch.php b/src/Patch.php index 75c7983..038d9cd 100644 --- a/src/Patch.php +++ b/src/Patch.php @@ -17,7 +17,7 @@ class Patch */ public static function byId(string $tableName, mixed $docId, array|object $patch): void { - Custom::nonQuery(Query\Patch::byId($tableName), + Custom::nonQuery(Query\Patch::byId($tableName, $docId), array_merge(Parameters::id($docId), Parameters::json(':data', $patch))); } diff --git a/src/Query.php b/src/Query.php index 66f10c1..1bcbc08 100644 --- a/src/Query.php +++ b/src/Query.php @@ -38,12 +38,14 @@ class Query * Create a WHERE clause fragment to implement an ID-based query * * @param string $paramName The parameter name where the value of the ID will be provided (optional; default @id) + * @param mixed $docId The ID of the document to be retrieved; used to determine type for potential JSON field + * casts (optional; string ID assumed if no value is provided) * @return string The WHERE clause fragment to match by ID * @throws DocumentException If the database mode has not been set */ - public static function whereById(string $paramName = ':id'): string + public static function whereById(string $paramName = ':id', mixed $docId = null): string { - return self::whereByFields([Field::EQ(Configuration::$idField, 0, $paramName)]); + return self::whereByFields([Field::EQ(Configuration::$idField, $docId ?? '', $paramName)]); } /** @@ -68,10 +70,11 @@ class Query }, Mode::PgSQL => match ($autoId ?? AutoId::None) { AutoId::None => ':data', - AutoId::Number => ":data || ('{\"$id\":' || " - . "(SELECT COALESCE(MAX(data->>'$id'), 0) + 1 FROM $tableName) || '}')", - AutoId::UUID => ":data || '{\"$id\":\"" . AutoId::generateUUID() . "\"}'", - AutoId::RandomString => ":data || '{\"$id\":\"" . AutoId::generateRandom() . "\"}'", + AutoId::Number => ":data::jsonb || ('{\"$id\":' || " + . "(SELECT COALESCE(MAX((data->>'$id')::numeric), 0) + 1 " + . "FROM $tableName) || '}')::jsonb", + AutoId::UUID => ":data::jsonb || '{\"$id\":\"" . AutoId::generateUUID() . "\"}'", + AutoId::RandomString => ":data::jsonb || '{\"$id\":\"" . AutoId::generateRandom() . "\"}'", }, default => throw new DocumentException('Database mode not set; cannot generate auto-ID INSERT statement'), diff --git a/src/Query/Delete.php b/src/Query/Delete.php index a8303ab..576378e 100644 --- a/src/Query/Delete.php +++ b/src/Query/Delete.php @@ -13,12 +13,13 @@ class Delete * Query to delete a document by its ID * * @param string $tableName The name of the table from which a document should be deleted + * @param mixed $docId The ID of the document to be deleted (optional; string ID assumed) * @return string The DELETE statement to delete a document by its ID * @throws DocumentException If the database mode has not been set */ - public static function byId(string $tableName): string + public static function byId(string $tableName, mixed $docId = null): string { - return "DELETE FROM $tableName WHERE " . Query::whereById(); + return "DELETE FROM $tableName WHERE " . Query::whereById(docId: $docId); } /** diff --git a/src/Query/Exists.php b/src/Query/Exists.php index 6ff86f4..f2d07ee 100644 --- a/src/Query/Exists.php +++ b/src/Query/Exists.php @@ -25,12 +25,13 @@ class Exists * Query to determine if a document exists for the given ID * * @param string $tableName The name of the table in which document existence should be checked + * @param mixed $docId The ID of the document whose existence should be checked (optional; string ID assumed) * @return string The query to determine document existence by ID * @throws DocumentException If the database mode has not been set */ - public static function byId(string $tableName): string + public static function byId(string $tableName, mixed $docId = null): string { - return self::query($tableName, Query::whereById()); + return self::query($tableName, Query::whereById(docId: $docId)); } /** diff --git a/src/Query/Find.php b/src/Query/Find.php index 824e8f3..68e004b 100644 --- a/src/Query/Find.php +++ b/src/Query/Find.php @@ -13,12 +13,13 @@ class Find * Query to retrieve a document by its ID * * @param string $tableName The name of the table from which a document should be retrieved + * @param mixed $docId The ID of the document to be retrieved (optional; string ID assumed) * @return string The SELECT statement to retrieve a document by its ID * @throws DocumentException If the database mode has not been set */ - public static function byId(string $tableName): string + public static function byId(string $tableName, mixed $docId = null): string { - return Query::selectFromTable($tableName) . ' WHERE ' . Query::whereById(); + return Query::selectFromTable($tableName) . ' WHERE ' . Query::whereById(docId: $docId); } /** diff --git a/src/Query/Patch.php b/src/Query/Patch.php index 50a696b..2cfd059 100644 --- a/src/Query/Patch.php +++ b/src/Query/Patch.php @@ -31,12 +31,13 @@ class Patch * Query to patch (partially update) a document by its ID * * @param string $tableName The name of the table in which a document should be patched + * @param mixed $docId The ID of the document to be patched (optional; string ID assumed) * @return string The query to patch a document by its ID * @throws DocumentException If the database mode has not been set */ - public static function byId(string $tableName): string + public static function byId(string $tableName, mixed $docId = null): string { - return self::update($tableName, Query::whereById()); + return self::update($tableName, Query::whereById(docId: $docId)); } /** diff --git a/src/Query/RemoveFields.php b/src/Query/RemoveFields.php index c668abf..766395c 100644 --- a/src/Query/RemoveFields.php +++ b/src/Query/RemoveFields.php @@ -26,7 +26,8 @@ class RemoveFields { switch (Configuration::$mode) { case Mode::PgSQL: - return "UPDATE $tableName SET data = data - " . array_keys($parameters)[0] . " WHERE $whereClause"; + return "UPDATE $tableName SET data = data - " . array_keys($parameters)[0] + . "::text[] WHERE $whereClause"; case Mode::SQLite: $paramNames = implode(', ', array_keys($parameters)); return "UPDATE $tableName SET data = json_remove(data, $paramNames) WHERE $whereClause"; @@ -40,12 +41,13 @@ class RemoveFields * * @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 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 */ - public static function byId(string $tableName, array $parameters): string + public static function byId(string $tableName, array $parameters, mixed $docId = null): string { - return self::update($tableName, $parameters, Query::whereById()); + return self::update($tableName, $parameters, Query::whereById(docId: $docId)); } /** diff --git a/src/RemoveFields.php b/src/RemoveFields.php index 3933e7d..792468b 100644 --- a/src/RemoveFields.php +++ b/src/RemoveFields.php @@ -18,7 +18,7 @@ class RemoveFields public static function byId(string $tableName, mixed $docId, array $fieldNames): void { $nameParams = Parameters::fieldNames(':name', $fieldNames); - Custom::nonQuery(Query\RemoveFields::byId($tableName, $nameParams), + Custom::nonQuery(Query\RemoveFields::byId($tableName, $nameParams, $docId), array_merge(Parameters::id($docId), $nameParams)); } diff --git a/tests/integration/postgresql/CountTest.php b/tests/integration/postgresql/CountTest.php new file mode 100644 index 0000000..7403013 --- /dev/null +++ b/tests/integration/postgresql/CountTest.php @@ -0,0 +1,47 @@ +dbName = ThrowawayDb::create(); + } + + protected function tearDown(): void + { + ThrowawayDb::destroy($this->dbName); + parent::tearDown(); + } + + public function testAllSucceeds(): void + { + $count = Count::all(ThrowawayDb::TABLE); + $this->assertEquals(5, $count, 'There should have been 5 matching documents'); + } + + public function testByFieldsSucceedsForANumericRange(): void + { + $count = Count::byFields(ThrowawayDb::TABLE, [Field::BT('num_value', 10, 20)]); + $this->assertEquals(3, $count, 'There should have been 3 matching documents'); + } + + public function testByFieldsSucceedsForANonNumericRange(): void + { + $count = Count::byFields(ThrowawayDb::TABLE, [Field::BT('value', 'aardvark', 'apple')]); + $this->assertEquals(1, $count, 'There should have been 1 matching document'); + } +} diff --git a/tests/integration/postgresql/CustomTest.php b/tests/integration/postgresql/CustomTest.php new file mode 100644 index 0000000..4366b53 --- /dev/null +++ b/tests/integration/postgresql/CustomTest.php @@ -0,0 +1,121 @@ +dbName = ThrowawayDb::create(); + } + + public function tearDown(): void + { + ThrowawayDb::destroy($this->dbName); + } + + public function testRunQuerySucceedsWithAValidQuery() + { + $stmt = &Custom::runQuery('SELECT data FROM ' . ThrowawayDb::TABLE . ' LIMIT 1', []); + try { + $this->assertNotNull($stmt, 'The statement should not have been null'); + } finally { + $stmt = null; + } + } + + public function testRunQueryFailsWithAnInvalidQuery() + { + $this->expectException(DocumentException::class); + $stmt = &Custom::runQuery('GRAB stuff FROM over_there UNTIL done', []); + try { + $this->assertTrue(false, 'This code should not be reached'); + } finally { + $stmt = null; + } + } + + public function testListSucceedsWhenDataIsFound() + { + $list = Custom::list(Query::selectFromTable(ThrowawayDb::TABLE), [], new DocumentMapper(TestDocument::class)); + $this->assertNotNull($list, 'The document list should not be null'); + $count = 0; + foreach ($list->items() as $ignored) $count++; + $this->assertEquals(5, $count, 'There should have been 5 documents in the list'); + } + + public function testListSucceedsWhenNoDataIsFound() + { + $list = Custom::list( + Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE (data->>'num_value')::numeric > :value", + [':value' => 100], new DocumentMapper(TestDocument::class)); + $this->assertNotNull($list, 'The document list should not be null'); + $this->assertFalse($list->hasItems(), 'There should have been no documents in the list'); + } + + public function testArraySucceedsWhenDataIsFound() + { + $array = Custom::array(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'sub' IS NOT NULL", [], + new DocumentMapper(TestDocument::class)); + $this->assertNotNull($array, 'The document array should not be null'); + $this->assertCount(2, $array, 'There should have been 2 documents in the array'); + } + + public function testArraySucceedsWhenNoDataIsFound() + { + $array = Custom::array(Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE data->>'value' = :value", + [':value' => 'not there'], new DocumentMapper(TestDocument::class)); + $this->assertNotNull($array, 'The document array should not be null'); + $this->assertCount(0, $array, 'There should have been no documents in the array'); + } + + public function testSingleSucceedsWhenARowIsFound(): void + { + $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE data->>'id' = :id", [':id' => 'one'], + new DocumentMapper(TestDocument::class)); + $this->assertNotNull($doc, 'There should have been a document returned'); + $this->assertEquals('one', $doc->id, 'The incorrect document was returned'); + } + + public function testSingleSucceedsWhenARowIsNotFound(): void + { + $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE data->>'id' = :id", + [':id' => 'eighty'], new DocumentMapper(TestDocument::class)); + $this->assertFalse($doc, 'There should not have been a document returned'); + } + + public function testNonQuerySucceedsWhenOperatingOnData() + { + 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() + { + Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE . " WHERE (data->>'num_value')::numeric > :value", + [':value' => 100]); + $remaining = Count::all(ThrowawayDb::TABLE); + $this->assertEquals(5, $remaining, 'There should be 5 documents remaining in the table'); + } + + public function testScalarSucceeds() + { + $value = Custom::scalar("SELECT 5 AS it", [], new CountMapper()); + $this->assertEquals(5, $value, 'The scalar value was not returned correctly'); + } +} diff --git a/tests/integration/postgresql/DefinitionTest.php b/tests/integration/postgresql/DefinitionTest.php new file mode 100644 index 0000000..ff3d5c8 --- /dev/null +++ b/tests/integration/postgresql/DefinitionTest.php @@ -0,0 +1,60 @@ +dbName = ThrowawayDb::create(withData: false); + } + + protected function tearDown(): void + { + ThrowawayDb::destroy($this->dbName); + parent::tearDown(); + } + + /** + * Does the given named object exist in the database? + * + * @param string $name The name of the object whose existence should be verified + * @return bool True if the object exists, false if not + * @throws DocumentException If any is encountered + */ + private function itExists(string $name): bool + { + return Custom::scalar('SELECT EXISTS (SELECT 1 FROM pg_class WHERE relname = :name)', + [':name' => $name], new ExistsMapper()); + } + + public function testEnsureTableSucceeds() + { + $this->assertFalse($this->itExists('ensured'), 'The table should not exist already'); + $this->assertFalse($this->itExists('idx_ensured_key'), 'The key index should not exist already'); + Definition::ensureTable('ensured'); + $this->assertTrue($this->itExists('ensured'), 'The table should now exist'); + $this->assertTrue($this->itExists('idx_ensured_key'), 'The key index should now exist'); + } + + public function testEnsureFieldIndexSucceeds() + { + $this->assertFalse($this->itExists('idx_ensured_test'), 'The index should not exist already'); + Definition::ensureTable('ensured'); + Definition::ensureFieldIndex('ensured', 'test', ['name', 'age']); + $this->assertTrue($this->itExists('idx_ensured_test'), 'The index should now exist'); + } +} diff --git a/tests/integration/postgresql/DeleteTest.php b/tests/integration/postgresql/DeleteTest.php new file mode 100644 index 0000000..2c85011 --- /dev/null +++ b/tests/integration/postgresql/DeleteTest.php @@ -0,0 +1,59 @@ +dbName = ThrowawayDb::create(); + } + + protected function tearDown(): void + { + ThrowawayDb::destroy($this->dbName); + parent::tearDown(); + } + + #[TestDox('By ID succeeds when a document is deleted')] + public function testByIdSucceedsWhenADocumentIsDeleted(): void + { + $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start'); + Delete::byId(ThrowawayDb::TABLE, 'four'); + $this->assertEquals(4, Count::all(ThrowawayDb::TABLE), 'There should have been 4 documents remaining'); + } + + #[TestDox('By ID succeeds when a document is not deleted')] + public function testByIdSucceedsWhenADocumentIsNotDeleted(): void + { + $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start'); + Delete::byId(ThrowawayDb::TABLE, 'negative four'); + $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents remaining'); + } + + public function testByFieldsSucceedsWhenDocumentsAreDeleted(): void + { + $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start'); + Delete::byFields(ThrowawayDb::TABLE, [Field::NE('value', 'purple')]); + $this->assertEquals(2, Count::all(ThrowawayDb::TABLE), 'There should have been 2 documents remaining'); + } + + public function testByFieldsSucceedsWhenDocumentsAreNotDeleted(): void + { + $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start'); + Delete::byFields(ThrowawayDb::TABLE, [Field::EQ('value', 'crimson')]); + $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents remaining'); + } +} diff --git a/tests/integration/postgresql/DocumentListTest.php b/tests/integration/postgresql/DocumentListTest.php new file mode 100644 index 0000000..7f6fd53 --- /dev/null +++ b/tests/integration/postgresql/DocumentListTest.php @@ -0,0 +1,74 @@ +dbName = ThrowawayDb::create(); + } + + protected function tearDown(): void + { + ThrowawayDb::destroy($this->dbName); + parent::tearDown(); + } + + public function testCreateSucceeds(): void + { + $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [], + new DocumentMapper(TestDocument::class)); + $this->assertNotNull($list, 'There should have been a document list created'); + $list = null; + } + + public function testItems(): void + { + $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [], + new DocumentMapper(TestDocument::class)); + $this->assertNotNull($list, 'There should have been a document list created'); + $count = 0; + foreach ($list->items() as $item) { + $this->assertContains($item->id, ['one', 'two', 'three', 'four', 'five'], + 'An unexpected document ID was returned'); + $count++; + } + $this->assertEquals(5, $count, 'There should have been 5 documents returned'); + } + + public function testHasItemsSucceedsWithEmptyResults(): void + { + $list = DocumentList::create( + Query::selectFromTable(ThrowawayDb::TABLE) . " WHERE (data->>'num_value')::numeric < 0", [], + new DocumentMapper(TestDocument::class)); + $this->assertNotNull($list, 'There should have been a document list created'); + $this->assertFalse($list->hasItems(), 'There should be no items in the list'); + } + + public function testHasItemsSucceedsWithNonEmptyResults(): void + { + $list = DocumentList::create(Query::selectFromTable(ThrowawayDb::TABLE), [], + new DocumentMapper(TestDocument::class)); + $this->assertNotNull($list, 'There should have been a document list created'); + $this->assertTrue($list->hasItems(), 'There should be items in the list'); + foreach ($list->items() as $ignored) { + $this->assertTrue($list->hasItems(), 'There should be items remaining in the list'); + } + $this->assertFalse($list->hasItems(), 'There should be no remaining items in the list'); + } +} diff --git a/tests/integration/postgresql/DocumentTest.php b/tests/integration/postgresql/DocumentTest.php new file mode 100644 index 0000000..786e572 --- /dev/null +++ b/tests/integration/postgresql/DocumentTest.php @@ -0,0 +1,302 @@ +dbName = ThrowawayDb::create(); + } + + protected function tearDown(): void + { + ThrowawayDb::destroy($this->dbName); + parent::tearDown(); + } + + #[TestDox('Insert succeeds for array no auto ID')] + public function testInsertSucceedsForArrayNoAutoId(): void + { + Document::insert(ThrowawayDb::TABLE, ['id' => 'turkey', 'sub' => ['foo' => 'gobble', 'bar' => 'gobble']]); + $doc = Find::byId(ThrowawayDb::TABLE, 'turkey', TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document inserted'); + $this->assertEquals('turkey', $doc->id, 'The ID was incorrect'); + $this->assertEquals('', $doc->value, 'The value was incorrect'); + $this->assertEquals(0, $doc->num_value, 'The numeric value was incorrect'); + $this->assertNotNull($doc->sub, 'The sub-document should not have been null'); + $this->assertEquals('gobble', $doc->sub->foo, 'The sub-document foo property was incorrect'); + $this->assertEquals('gobble', $doc->sub->bar, 'The sub-document bar property was incorrect'); + } + + #[TestDox('Insert succeeds for array with auto number ID not provided')] + public function testInsertSucceedsForArrayWithAutoNumberIdNotProvided(): void + { + Configuration::$autoId = AutoId::Number; + try { + Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []); + + Document::insert(ThrowawayDb::TABLE, ['id' => 0, 'value' => 'new', 'num_value' => 8]); + $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE, [], new ArrayMapper()); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $obj = json_decode($doc['data']); + $this->assertEquals(1, $obj->id, 'The ID 1 should have been auto-generated'); + + Document::insert(ThrowawayDb::TABLE, ['id' => 0, 'value' => 'again', 'num_value' => 7]); + $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE . " WHERE " . Query::whereById(docId: 2), + [':id' => 2], new ArrayMapper()); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $obj = json_decode($doc['data']); + $this->assertEquals(2, $obj->id, 'The ID 2 should have been auto-generated'); + } finally { + Configuration::$autoId = AutoId::None; + } + } + + #[TestDox('Insert succeeds for array with auto number ID with ID provided')] + public function testInsertSucceedsForArrayWithAutoNumberIdWithIdProvided(): void + { + Configuration::$autoId = AutoId::Number; + try { + Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []); + Document::insert(ThrowawayDb::TABLE, ['id' => 7, 'value' => 'new', 'num_value' => 8]); + $doc = Custom::single('SELECT data FROM ' . ThrowawayDb::TABLE, [], new ArrayMapper()); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $obj = json_decode($doc['data']); + $this->assertEquals(7, $obj->id, 'The ID 7 should have been stored'); + } finally { + Configuration::$autoId = AutoId::None; + } + } + + #[TestDox('Insert succeeds for array with auto UUID ID not provided')] + public function testInsertSucceedsForArrayWithAutoUuidIdNotProvided(): void + { + Configuration::$autoId = AutoId::UUID; + try { + Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []); + Document::insert(ThrowawayDb::TABLE, ['id' => '', 'num_value' => 5]); + $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 5)], TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertNotEmpty($doc->id, 'The ID should have been auto-generated'); + } finally { + Configuration::$autoId = AutoId::None; + } + } + + #[TestDox('Insert succeeds for array with auto UUID ID with ID provided')] + public function testInsertSucceedsForArrayWithAutoUuidIdWithIdProvided(): void + { + Configuration::$autoId = AutoId::UUID; + try { + Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []); + $uuid = AutoId::generateUUID(); + Document::insert(ThrowawayDb::TABLE, ['id' => $uuid, 'value' => 'uuid', 'num_value' => 12]); + $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 12)], TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals($uuid, $doc->id, 'The ID should not have been changed'); + } finally { + Configuration::$autoId = AutoId::None; + } + } + + #[TestDox('Insert succeeds for array with auto string ID not provided')] + public function testInsertSucceedsForArrayWithAutoStringIdNotProvided(): void + { + Configuration::$autoId = AutoId::RandomString; + Configuration::$idStringLength = 6; + try { + Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []); + Document::insert(ThrowawayDb::TABLE, ['id' => '', 'value' => 'new', 'num_value' => 8]); + $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 8)], TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals(6, strlen($doc->id), 'The ID should have been auto-generated and had 6 characters'); + } finally { + Configuration::$autoId = AutoId::None; + Configuration::$idStringLength = 16; + } + } + + #[TestDox('Insert succeeds for array with auto string ID with ID provided')] + public function testInsertSucceedsForArrayWithAutoStringIdWithIdProvided(): void + { + Configuration::$autoId = AutoId::RandomString; + try { + Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []); + Document::insert(ThrowawayDb::TABLE, ['id' => 'my-key', 'value' => 'old', 'num_value' => 3]); + $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 3)], TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals('my-key', $doc->id, 'The ID should not have been changed'); + } finally { + Configuration::$autoId = AutoId::None; + } + } + + #[TestDox('Insert succeeds for object no auto ID')] + public function testInsertSucceedsForObjectNoAutoId(): void + { + Document::insert(ThrowawayDb::TABLE, new TestDocument('turkey', sub: new SubDocument('gobble', 'gobble'))); + $doc = Find::byId(ThrowawayDb::TABLE, 'turkey', TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document inserted'); + $this->assertEquals('turkey', $doc->id, 'The ID was incorrect'); + $this->assertEquals('', $doc->value, 'The value was incorrect'); + $this->assertEquals(0, $doc->num_value, 'The numeric value was incorrect'); + $this->assertNotNull($doc->sub, 'The sub-document should not have been null'); + $this->assertEquals('gobble', $doc->sub->foo, 'The sub-document foo property was incorrect'); + $this->assertEquals('gobble', $doc->sub->bar, 'The sub-document bar property was incorrect'); + } + + #[TestDox('Insert succeeds for object with auto number ID not provided')] + public function testInsertSucceedsForObjectWithAutoNumberIdNotProvided(): void + { + Configuration::$autoId = AutoId::Number; + try { + Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []); + + Document::insert(ThrowawayDb::TABLE, new NumDocument(value: 'taco')); + $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'taco')], NumDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals(1, $doc->id, 'The ID 1 should have been auto-generated'); + + Document::insert(ThrowawayDb::TABLE, new NumDocument(value: 'burrito')); + $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'burrito')], NumDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals(2, $doc->id, 'The ID 2 should have been auto-generated'); + } finally { + Configuration::$autoId = AutoId::None; + } + } + + #[TestDox('Insert succeeds for object with auto number ID with ID provided')] + public function testInsertSucceedsForObjectWithAutoNumberIdWithIdProvided(): void + { + Configuration::$autoId = AutoId::Number; + try { + Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []); + Document::insert(ThrowawayDb::TABLE, new NumDocument(64, 'large')); + $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'large')], NumDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals(64, $doc->id, 'The ID 64 should have been stored'); + } finally { + Configuration::$autoId = AutoId::None; + } + } + + #[TestDox('Insert succeeds for object with auto UUID ID not provided')] + public function testInsertSucceedsForObjectWithAutoUuidIdNotProvided(): void + { + Configuration::$autoId = AutoId::UUID; + try { + Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []); + Document::insert(ThrowawayDb::TABLE, new TestDocument(value: 'something', num_value: 9)); + $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EX('value')], TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertNotEmpty($doc->id, 'The ID should have been auto-generated'); + } finally { + Configuration::$autoId = AutoId::None; + } + } + + #[TestDox('Insert succeeds for object with auto UUID ID with ID provided')] + public function testInsertSucceedsForObjectWithAutoUuidIdWithIdProvided(): void + { + Configuration::$autoId = AutoId::UUID; + try { + Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []); + $uuid = AutoId::generateUUID(); + Document::insert(ThrowawayDb::TABLE, new TestDocument($uuid, num_value: 14)); + $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 14)], TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals($uuid, $doc->id, 'The ID should not have been changed'); + } finally { + Configuration::$autoId = AutoId::None; + } + } + + #[TestDox('Insert succeeds for object with auto string ID not provided')] + public function testInsertSucceedsForObjectWithAutoStringIdNotProvided(): void + { + Configuration::$autoId = AutoId::RandomString; + Configuration::$idStringLength = 40; + try { + Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []); + Document::insert(ThrowawayDb::TABLE, new TestDocument(num_value: 55)); + $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 55)], TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals(40, strlen($doc->id), 'The ID should have been auto-generated and had 40 characters'); + } finally { + Configuration::$autoId = AutoId::None; + Configuration::$idStringLength = 16; + } + } + + #[TestDox('Insert succeeds for object with auto string ID with ID provided')] + public function testInsertSucceedsForObjectWithAutoStringIdWithIdProvided(): void + { + Configuration::$autoId = AutoId::RandomString; + try { + Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []); + Document::insert(ThrowawayDb::TABLE, new TestDocument('my-key', num_value: 3)); + $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 3)], TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals('my-key', $doc->id, 'The ID should not have been changed'); + } finally { + Configuration::$autoId = AutoId::None; + } + } + + public function testInsertFailsForDuplicateKey(): void + { + $this->expectException(DocumentException::class); + Document::insert(ThrowawayDb::TABLE, new TestDocument('one')); + } + + public function testSaveSucceedsWhenADocumentIsInserted(): void + { + Document::save(ThrowawayDb::TABLE, new TestDocument('test', sub: new SubDocument('a', 'b'))); + $doc = Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + } + + public function testSaveSucceedsWhenADocumentIsUpdated(): void + { + Document::save(ThrowawayDb::TABLE, new TestDocument('two', num_value: 44)); + $doc = Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals(44, $doc->num_value, 'The numeric value was not updated'); + $this->assertNull($doc->sub, 'The sub-document should have been null'); + } + + public function testUpdateSucceedsWhenReplacingADocument(): void + { + Document::update(ThrowawayDb::TABLE, 'one', new TestDocument('one', 'howdy', 8, new SubDocument('y', 'z'))); + $doc = Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals('howdy', $doc->value, 'The value was incorrect'); + $this->assertEquals(8, $doc->num_value, 'The numeric value was incorrect'); + $this->assertNotNull($doc->sub, 'The sub-document should not have been null'); + $this->assertEquals('y', $doc->sub->foo, 'The sub-document foo property was incorrect'); + $this->assertEquals('z', $doc->sub->bar, 'The sub-document bar property was incorrect'); + } + + public function testUpdateSucceedsWhenNoDocumentIsReplaced(): void + { + Document::update(ThrowawayDb::TABLE, 'two-hundred', new TestDocument('200')); + $doc = Find::byId(ThrowawayDb::TABLE, 'two-hundred', TestDocument::class); + $this->assertFalse($doc, 'There should not have been a document returned'); + } +} diff --git a/tests/integration/postgresql/ExistsTest.php b/tests/integration/postgresql/ExistsTest.php new file mode 100644 index 0000000..cc7509c --- /dev/null +++ b/tests/integration/postgresql/ExistsTest.php @@ -0,0 +1,54 @@ +dbName = ThrowawayDb::create(); + } + + protected function tearDown(): void + { + ThrowawayDb::destroy($this->dbName); + parent::tearDown(); + } + + #[TestDox('By ID succeeds when a document exists')] + public function testByIdSucceedsWhenADocumentExists(): void + { + $this->assertTrue(Exists::byId(ThrowawayDb::TABLE, 'three'), 'There should have been an existing document'); + } + + #[TestDox('By ID succeeds when a document does not exist')] + public function testByIdSucceedsWhenADocumentDoesNotExist(): void + { + $this->assertFalse(Exists::byId(ThrowawayDb::TABLE, 'seven'), + 'There should not have been an existing document'); + } + + public function testByFieldsSucceedsWhenDocumentsExist(): void + { + $this->assertTrue(Exists::byFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 10)]), + 'There should have been existing documents'); + } + + public function testByFieldsSucceedsWhenNoMatchingDocumentsExist(): void + { + $this->assertFalse(Exists::byFields(ThrowawayDb::TABLE, [Field::LT('nothing', 'none')]), + 'There should not have been any existing documents'); + } +} diff --git a/tests/integration/postgresql/FindTest.php b/tests/integration/postgresql/FindTest.php new file mode 100644 index 0000000..4649911 --- /dev/null +++ b/tests/integration/postgresql/FindTest.php @@ -0,0 +1,108 @@ +dbName = ThrowawayDb::create(); + } + + protected function tearDown(): void + { + ThrowawayDb::destroy($this->dbName); + parent::tearDown(); + } + + public function testAllSucceedsWhenThereIsData(): void + { + $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class); + $this->assertNotNull($docs, 'There should have been a document list returned'); + $count = 0; + foreach ($docs->items() as $ignored) $count++; + $this->assertEquals(5, $count, 'There should have been 5 documents in the list'); + } + + public function testAllSucceedsWhenThereIsNoData(): void + { + Custom::nonQuery('DELETE FROM ' . ThrowawayDb::TABLE, []); + $docs = Find::all(ThrowawayDb::TABLE, TestDocument::class); + $this->assertNotNull($docs, 'There should have been a document list returned'); + $this->assertFalse($docs->hasItems(), 'There should have been no documents in the list'); + } + + #[TestDox('By ID succeeds when a document is found')] + public function testByIdSucceedsWhenADocumentIsFound(): void + { + $doc = Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals('two', $doc->id, 'An incorrect document was returned'); + } + + #[TestDox('By ID succeeds when a document is found with numeric ID')] + public function testByIdSucceedsWhenADocumentIsFoundWithNumericId(): void + { + Delete::byFields(ThrowawayDb::TABLE, [Field::NEX('absent')]); + Document::insert(ThrowawayDb::TABLE, ['id' => 18, 'value' => 'howdy']); + $doc = Find::byId(ThrowawayDb::TABLE, 18, NumDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals(18, $doc->id, 'An incorrect document was returned'); + } + + #[TestDox('By ID succeeds when a document is not found')] + public function testByIdSucceedsWhenADocumentIsNotFound(): void + { + $doc = Find::byId(ThrowawayDb::TABLE, 'seventy-five', TestDocument::class); + $this->assertFalse($doc, 'There should not have been a document returned'); + } + + public function testByFieldsSucceedsWhenDocumentsAreFound(): void + { + $docs = Find::byFields(ThrowawayDb::TABLE, [Field::GT('num_value', 15)], TestDocument::class); + $this->assertNotNull($docs, 'There should have been a document list returned'); + $count = 0; + foreach ($docs->items() as $ignored) $count++; + $this->assertEquals(2, $count, 'There should have been 2 documents in the list'); + } + + public function testByFieldsSucceedsWhenNoDocumentsAreFound(): void + { + $docs = Find::byFields(ThrowawayDb::TABLE, [Field::GT('num_value', 100)], TestDocument::class); + $this->assertNotNull($docs, 'There should have been a document list returned'); + $this->assertFalse($docs->hasItems(), 'There should have been no documents in the list'); + } + + public function testFirstByFieldsSucceedsWhenADocumentIsFound(): void + { + $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'another')], TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals('two', $doc->id, 'The incorrect document was returned'); + } + + public function testFirstByFieldsSucceedsWhenMultipleDocumentsAreFound(): void + { + $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('sub.foo', 'green')], TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertContains($doc->id, ['two', 'four'], 'An incorrect document was returned'); + } + + public function testFirstByFieldsSucceedsWhenADocumentIsNotFound(): void + { + $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'absent')], TestDocument::class); + $this->assertFalse($doc, 'There should not have been a document returned'); + } +} diff --git a/tests/integration/postgresql/PatchTest.php b/tests/integration/postgresql/PatchTest.php new file mode 100644 index 0000000..1b58aa8 --- /dev/null +++ b/tests/integration/postgresql/PatchTest.php @@ -0,0 +1,59 @@ +dbName = ThrowawayDb::create(); + } + + protected function tearDown(): void + { + ThrowawayDb::destroy($this->dbName); + parent::tearDown(); + } + + #[TestDox('By ID succeeds when a document is updated')] + public function testByIdSucceedsWhenADocumentIsUpdated(): void + { + Patch::byId(ThrowawayDb::TABLE, 'one', ['num_value' => 44]); + $doc = Find::byId(ThrowawayDb::TABLE, 'one', TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals(44, $doc->num_value, 'The updated document is not correct'); + } + + #[TestDox('By ID succeeds when no document is updated')] + public function testByIdSucceedsWhenNoDocumentIsUpdated(): void + { + Patch::byId(ThrowawayDb::TABLE, 'forty-seven', ['foo' => 'green']); + $this->assertTrue(true, 'The above not throwing an exception is the test'); + } + + public function testByFieldsSucceedsWhenADocumentIsUpdated(): void + { + Patch::byFields(ThrowawayDb::TABLE, [Field::EQ('value', 'purple')], ['num_value' => 77]); + $after = Count::byFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 77)]); + $this->assertEquals(2, $after, 'There should have been 2 documents updated'); + } + + public function testByFieldsSucceedsWhenNoDocumentIsUpdated(): void + { + Patch::byFields(ThrowawayDb::TABLE, [Field::EQ('value', 'burgundy')], ['foo' => 'green']); + $this->assertTrue(true, 'The above not throwing an exception is the test'); + } +} diff --git a/tests/integration/postgresql/RemoveFieldsTest.php b/tests/integration/postgresql/RemoveFieldsTest.php new file mode 100644 index 0000000..37c27e2 --- /dev/null +++ b/tests/integration/postgresql/RemoveFieldsTest.php @@ -0,0 +1,74 @@ +dbName = ThrowawayDb::create(); + } + + protected function tearDown(): void + { + ThrowawayDb::destroy($this->dbName); + parent::tearDown(); + } + + #[TestDox('By ID succeeds when fields are removed')] + public function testByIdSucceedsWhenFieldsAreRemoved(): void + { + RemoveFields::byId(ThrowawayDb::TABLE, 'two', ['sub', 'value']); + $doc = Find::byId(ThrowawayDb::TABLE, 'two', TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals('', $doc->value, 'Value should have been blank (its default value)'); + $this->assertNull($doc->sub, 'Sub-document should have been null'); + } + + #[TestDox('By ID succeeds when a field is not removed')] + public function testByIdSucceedsWhenAFieldIsNotRemoved(): void + { + RemoveFields::byId(ThrowawayDb::TABLE, 'one', ['a_field_that_does_not_exist']); + $this->assertTrue(true, 'The above not throwing an exception is the test'); + } + + #[TestDox('By ID succeeds when no document is matched')] + public function testByIdSucceedsWhenNoDocumentIsMatched(): void + { + RemoveFields::byId(ThrowawayDb::TABLE, 'fifty', ['sub']); + $this->assertTrue(true, 'The above not throwing an exception is the test'); + } + + public function testByFieldsSucceedsWhenAFieldIsRemoved(): void + { + RemoveFields::byFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 17)], ['sub']); + $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 17)], TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertNull($doc->sub, 'Sub-document should have been null'); + } + + public function testByFieldsSucceedsWhenAFieldIsNotRemoved(): void + { + RemoveFields::byFields(ThrowawayDb::TABLE, [Field::EQ('num_value', 17)], ['nada']); + $this->assertTrue(true, 'The above not throwing an exception is the test'); + } + + public function testByFieldsSucceedsWhenNoDocumentIsMatched(): void + { + RemoveFields::byFields(ThrowawayDb::TABLE, [Field::NE('missing', 'nope')], ['value']); + $this->assertTrue(true, 'The above not throwing an exception is the test'); + } +} diff --git a/tests/integration/postgresql/ThrowawayDb.php b/tests/integration/postgresql/ThrowawayDb.php new file mode 100644 index 0000000..8f5c11e --- /dev/null +++ b/tests/integration/postgresql/ThrowawayDb.php @@ -0,0 +1,75 @@ +assertNotNull($docs, 'There should have been a document list returned'); - $count = 0; - foreach ($docs->items() as $ignored) $count++; $this->assertFalse($docs->hasItems(), 'There should have been no documents in the list'); } diff --git a/tests/integration/sqlite/PatchTest.php b/tests/integration/sqlite/PatchTest.php index ce64f24..b366425 100644 --- a/tests/integration/sqlite/PatchTest.php +++ b/tests/integration/sqlite/PatchTest.php @@ -44,7 +44,6 @@ class PatchTest extends TestCase $this->assertTrue(true, 'The above not throwing an exception is the test'); } - public function testByFieldsSucceedsWhenADocumentIsUpdated(): void { Patch::byFields(ThrowawayDb::TABLE, [Field::EQ('value', 'purple')], ['num_value' => 77]); diff --git a/tests/integration/sqlite/ThrowawayDb.php b/tests/integration/sqlite/ThrowawayDb.php index 5a3ab64..6b4f56a 100644 --- a/tests/integration/sqlite/ThrowawayDb.php +++ b/tests/integration/sqlite/ThrowawayDb.php @@ -2,13 +2,9 @@ namespace Test\Integration\SQLite; -use BitBadger\PDODocument\Configuration; -use BitBadger\PDODocument\Definition; -use BitBadger\PDODocument\Document; -use BitBadger\PDODocument\DocumentException; -use BitBadger\PDODocument\Mode; -use Test\Integration\SubDocument; -use Test\Integration\TestDocument; +use BitBadger\PDODocument\{AutoId, Configuration, Definition, Document, DocumentException, Mode}; +use Random\RandomException; +use Test\Integration\{SubDocument, TestDocument}; /** * Utilities to create and destroy a throwaway SQLite database to use for testing @@ -16,18 +12,18 @@ use Test\Integration\TestDocument; class ThrowawayDb { /** @var string The table used for document manipulation */ - public const string TABLE = "test_table"; + public const TABLE = "test_table"; /** * Create a throwaway SQLite database * * @param bool $withData Whether to initialize this database with data (optional; defaults to `true`) * @return string The name of the database (use to pass to `destroy` function at end of test) - * @throws DocumentException If any is encountered + * @throws DocumentException|RandomException If any is encountered */ public static function create(bool $withData = true): string { - $fileName = sprintf('throwaway-%s-%d.db', date('His'), rand(10, 99)); + $fileName = sprintf('throwaway-%s.db', AutoId::generateRandom(10)); Configuration::$pdoDSN = "sqlite:./$fileName"; Configuration::$mode = Mode::SQLite; Configuration::resetPDO(); @@ -54,18 +50,4 @@ class ThrowawayDb Configuration::resetPDO(); unlink("./$fileName"); } - - /** - * Destroy the given throwaway database and create another - * - * @param string $fileName The name of the database to be destroyed - * @param bool $withData Whether to initialize the database with data (optional; defaults to `true`) - * @return string The name of the new database - * @throws DocumentException If any is encountered - */ - public static function exchange(string $fileName, bool $withData = true): string - { - self::destroy($fileName); - return self::create($withData); - } } diff --git a/tests/unit/FieldTest.php b/tests/unit/FieldTest.php index 421d131..d2639c4 100644 --- a/tests/unit/FieldTest.php +++ b/tests/unit/FieldTest.php @@ -221,7 +221,7 @@ class FieldTest extends TestCase try { $field = Field::LE('le_field', 18, '@it'); $field->qualifier = 'q'; - $this->assertEquals("q.data->>'le_field' <= @it", $field->toWhere(), + $this->assertEquals("(q.data->>'le_field')::numeric <= @it", $field->toWhere(), 'WHERE fragment not generated correctly'); } finally { Configuration::$mode = null; @@ -248,7 +248,7 @@ class FieldTest extends TestCase Configuration::$mode = Mode::PgSQL; try { $field = Field::EQ('sub.foo.bar', 22, '@it'); - $this->assertEquals("data->>'sub.foo.bar' = @it", $field->toWhere(), + $this->assertEquals("(data#>>'{sub,foo,bar}')::numeric = @it", $field->toWhere(), 'WHERE fragment not generated correctly'); } finally { Configuration::$mode = null; diff --git a/tests/unit/ParametersTest.php b/tests/unit/ParametersTest.php index a633124..3d1595d 100644 --- a/tests/unit/ParametersTest.php +++ b/tests/unit/ParametersTest.php @@ -51,7 +51,7 @@ class ParametersTest extends TestCase { try { Configuration::$mode = Mode::PgSQL; - $this->assertEquals([':names' => "ARRAY['one','two','seven']"], + $this->assertEquals([':names' => "{one,two,seven}"], Parameters::fieldNames(':names', ['one', 'two', 'seven']), 'Field name parameters not correct'); } finally { Configuration::$mode = null; diff --git a/tests/unit/Query/PatchTest.php b/tests/unit/Query/PatchTest.php index 1be92a5..f4b1608 100644 --- a/tests/unit/Query/PatchTest.php +++ b/tests/unit/Query/PatchTest.php @@ -49,7 +49,7 @@ class PatchTest extends TestCase { try { Configuration::$mode = Mode::PgSQL; - $this->assertEquals("UPDATE that SET data = data || :data WHERE data->>'something' < :some", + $this->assertEquals("UPDATE that SET data = data || :data WHERE (data->>'something')::numeric < :some", Patch::byFields('that', [Field::LT('something', 17, ':some')]), 'Patch UPDATE statement is not correct'); } finally { diff --git a/tests/unit/Query/RemoveFieldsTest.php b/tests/unit/Query/RemoveFieldsTest.php index b4223e0..1933845 100644 --- a/tests/unit/Query/RemoveFieldsTest.php +++ b/tests/unit/Query/RemoveFieldsTest.php @@ -17,8 +17,8 @@ class RemoveFieldsTest extends TestCase { try { Configuration::$mode = Mode::PgSQL; - $this->assertEquals('UPDATE taco SET data = data - :names WHERE it = true', - RemoveFields::update('taco', [':names' => "ARRAY['one','two']"], 'it = true'), + $this->assertEquals('UPDATE taco SET data = data - :names::text[] WHERE it = true', + RemoveFields::update('taco', [':names' => "{one,two}"], 'it = true'), 'UPDATE statement not correct'); } finally { Configuration::$mode = null; @@ -50,7 +50,7 @@ class RemoveFieldsTest extends TestCase { try { Configuration::$mode = Mode::PgSQL; - $this->assertEquals("UPDATE churro SET data = data - :bite WHERE data->>'id' = :id", + $this->assertEquals("UPDATE churro SET data = data - :bite::text[] WHERE data->>'id' = :id", RemoveFields::byId('churro', Parameters::fieldNames(':bite', ['byte'])), 'UPDATE statement not correct'); } finally { @@ -84,7 +84,7 @@ class RemoveFieldsTest extends TestCase { try { Configuration::$mode = Mode::PgSQL; - $this->assertEquals("UPDATE enchilada SET data = data - :sauce WHERE data->>'cheese' = :queso", + $this->assertEquals("UPDATE enchilada SET data = data - :sauce::text[] WHERE data->>'cheese' = :queso", RemoveFields::byFields('enchilada', [Field::EQ('cheese', 'jack', ':queso')], Parameters::fieldNames(':sauce', ['white'])), 'UPDATE statement not correct'); diff --git a/tests/unit/QueryTest.php b/tests/unit/QueryTest.php index a816157..a3418fe 100644 --- a/tests/unit/QueryTest.php +++ b/tests/unit/QueryTest.php @@ -90,8 +90,8 @@ class QueryTest extends TestCase Configuration::$mode = Mode::PgSQL; try { $this->assertEquals( - "INSERT INTO test_tbl VALUES (:data || ('{\"id\":' " - . "|| (SELECT COALESCE(MAX(data->>'id'), 0) + 1 FROM test_tbl) || '}'))", + "INSERT INTO test_tbl VALUES (:data::jsonb || ('{\"id\":' " + . "|| (SELECT COALESCE(MAX((data->>'id')::numeric), 0) + 1 FROM test_tbl) || '}')::jsonb)", Query::insert('test_tbl', AutoId::Number), 'INSERT statement not constructed correctly'); } finally { Configuration::$mode = null; @@ -118,7 +118,7 @@ class QueryTest extends TestCase Configuration::$mode = Mode::PgSQL; try { $query = Query::insert('test_tbl', AutoId::UUID); - $this->assertStringStartsWith("INSERT INTO test_tbl VALUES (:data || '{\"id\":\"", $query, + $this->assertStringStartsWith("INSERT INTO test_tbl VALUES (:data::jsonb || '{\"id\":\"", $query, 'INSERT statement not constructed correctly'); $this->assertStringEndsWith("\"}')", $query, 'INSERT statement not constructed correctly'); } finally { @@ -147,10 +147,10 @@ class QueryTest extends TestCase Configuration::$idStringLength = 8; try { $query = Query::insert('test_tbl', AutoId::RandomString); - $this->assertStringStartsWith("INSERT INTO test_tbl VALUES (:data || '{\"id\":\"", $query, + $this->assertStringStartsWith("INSERT INTO test_tbl VALUES (:data::jsonb || '{\"id\":\"", $query, 'INSERT statement not constructed correctly'); $this->assertStringEndsWith("\"}')", $query, 'INSERT statement not constructed correctly'); - $id = str_replace(["INSERT INTO test_tbl VALUES (:data || '{\"id\":\"", "\"}')"], '', $query); + $id = str_replace(["INSERT INTO test_tbl VALUES (:data::jsonb || '{\"id\":\"", "\"}')"], '', $query); $this->assertEquals(8, strlen($id), "Generated ID [$id] should have been 8 characters long"); } finally { Configuration::$mode = null; -- 2.45.1 From 9ecabbe39f827135b356bfe01191292d5a751455 Mon Sep 17 00:00:00 2001 From: "Daniel J. Summers" Date: Wed, 12 Jun 2024 17:43:17 -0400 Subject: [PATCH 2/4] Add byContains and byJsonPath - Add document index functions --- src/Definition.php | 12 ++ src/DocumentIndex.php | 15 +++ src/Query.php | 30 +++++ src/Query/Count.php | 24 ++++ src/Query/Definition.php | 23 +++- src/Query/Delete.php | 24 ++++ src/Query/Exists.php | 24 ++++ src/Query/Find.php | 24 ++++ src/Query/Patch.php | 24 ++++ src/Query/RemoveFields.php | 26 ++++ .../integration/postgresql/DefinitionTest.php | 24 +++- tests/integration/sqlite/DefinitionTest.php | 12 +- tests/integration/sqlite/ThrowawayDb.php | 2 +- tests/unit/ConfigurationTest.php | 1 + tests/unit/DocumentExceptionTest.php | 2 + tests/unit/FieldMatchTest.php | 2 + tests/unit/FieldTest.php | 1 + tests/unit/Mapper/ArrayMapperTest.php | 2 + tests/unit/Mapper/CountMapperTest.php | 2 + tests/unit/Mapper/DocumentMapperTest.php | 1 + tests/unit/Mapper/ExistsMapperTest.php | 1 + tests/unit/Mapper/StringMapperTest.php | 5 + tests/unit/OpTest.php | 1 + tests/unit/ParametersTest.php | 1 + tests/unit/Query/CountTest.php | 52 ++++++-- tests/unit/Query/DefinitionTest.php | 53 +++++--- tests/unit/Query/DeleteTest.php | 40 +++++- tests/unit/Query/ExistsTest.php | 41 +++++- tests/unit/Query/FindTest.php | 40 +++++- tests/unit/Query/PatchTest.php | 82 +++++++----- tests/unit/Query/RemoveFieldsTest.php | 117 ++++++++++-------- tests/unit/QueryTest.php | 63 ++++++++++ 32 files changed, 632 insertions(+), 139 deletions(-) create mode 100644 src/DocumentIndex.php diff --git a/src/Definition.php b/src/Definition.php index be87c3a..60ab363 100644 --- a/src/Definition.php +++ b/src/Definition.php @@ -31,4 +31,16 @@ class Definition { Custom::nonQuery(Query\Definition::ensureIndexOn($tableName, $indexName, $fields), []); } + + /** + * Create a full-document index on a table (PostgreSQL only) + * + * @param string $tableName The name of the table on which the document index should be created + * @param DocumentIndex $indexType The type of document index to create + * @throws DocumentException If the database mode is not PostgreSQL or if an error occurs creating the index + */ + public static function ensureDocumentIndex(string $tableName, DocumentIndex $indexType): void + { + Custom::nonQuery(Query\Definition::ensureDocumentIndexOn($tableName, $indexType), []); + } } diff --git a/src/DocumentIndex.php b/src/DocumentIndex.php new file mode 100644 index 0000000..0728657 --- /dev/null +++ b/src/DocumentIndex.php @@ -0,0 +1,15 @@ +, @?, @@ operators) */ + case Optimized; +} diff --git a/src/Query.php b/src/Query.php index 1bcbc08..51ed2e4 100644 --- a/src/Query.php +++ b/src/Query.php @@ -48,6 +48,36 @@ class Query return self::whereByFields([Field::EQ(Configuration::$idField, $docId ?? '', $paramName)]); } + /** + * Create a WHERE clause fragment to implement a JSON containment query (PostgreSQL only) + * + * @param string $paramName The name of the parameter (optional; defaults to `:criteria`) + * @return string The WHERE clause fragment for a JSON containment query + * @throws DocumentException If the database mode is not PostgreSQL + */ + public static function whereDataContains(string $paramName = ':criteria'): string + { + if (Configuration::$mode <> Mode::PgSQL) { + throw new DocumentException('JSON containment is only supported on PostgreSQL'); + } + return "data @> $paramName"; + } + + /** + * Create a WHERE clause fragment to implement a JSON Path match query (PostgreSQL only) + * + * @param string $paramName The name of the parameter (optional; defaults to `:path`) + * @return string The WHERE clause fragment for a JSON Path match query + * @throws DocumentException If the database mode is not PostgreSQL + */ + public static function whereJsonPathMatches(string $paramName = ':path'): string + { + if (Configuration::$mode <> Mode::PgSQL) { + throw new DocumentException('JSON Path matching is only supported on PostgreSQL'); + } + return "data @? $paramName::jsonpath"; + } + /** * Create an `INSERT` statement for a document * diff --git a/src/Query/Count.php b/src/Query/Count.php index 8727e96..7efed68 100644 --- a/src/Query/Count.php +++ b/src/Query/Count.php @@ -33,4 +33,28 @@ class Count { return self::all($tableName) . ' WHERE ' . Query::whereByFields($fields, $match); } + + /** + * Query to count matching documents using a JSON containment query (PostgreSQL only) + * + * @param string $tableName The name of the table in which documents should be counted + * @return string The query to count documents using a JSON containment query + * @throws DocumentException If the database mode is not PostgreSQL + */ + public static function byContains(string $tableName): string + { + return self::all($tableName) . ' WHERE ' . Query::whereDataContains(); + } + + /** + * Query to count matching documents using a JSON Path match (PostgreSQL only) + * + * @param string $tableName The name of the table in which documents should be counted + * @return string The query to count documents using a JSON Path match + * @throws DocumentException If the database mode is not PostgreSQL + */ + public static function byJsonPath(string $tableName): string + { + return self::all($tableName) . ' WHERE ' . Query::whereJsonPathMatches(); + } } diff --git a/src/Query/Definition.php b/src/Query/Definition.php index 6e584f5..6c94f01 100644 --- a/src/Query/Definition.php +++ b/src/Query/Definition.php @@ -2,7 +2,7 @@ namespace BitBadger\PDODocument\Query; -use BitBadger\PDODocument\{Configuration, DocumentException, Mode}; +use BitBadger\PDODocument\{Configuration, DocumentException, DocumentIndex, Mode}; /** * Queries to define tables and indexes @@ -68,4 +68,25 @@ class Definition { return str_replace('INDEX', 'UNIQUE INDEX', self::ensureIndexOn($tableName, 'key', [Configuration::$idField])); } + + /** + * Create a document-wide index on a table (PostgreSQL only) + * + * @param string $tableName The name of the table on which the document index should be created + * @param DocumentIndex $indexType The type of index to be created + * @return string The SQL statement to create an index on JSON documents in the specified table + * @throws DocumentException If the database mode is not PostgreSQL + */ + public static function ensureDocumentIndexOn(string $tableName, DocumentIndex $indexType): string + { + if (Configuration::$mode <> Mode::PgSQL) { + throw new DocumentException('Document indexes are only supported on PostgreSQL'); + } + [, $tbl] = self::splitSchemaAndTable($tableName); + $extraOps = match ($indexType) { + DocumentIndex::Full => '', + DocumentIndex::Optimized => ' jsonb_path_ops' + }; + return "CREATE INDEX IF NOT EXISTS idx_{$tbl}_document ON $tableName USING GIN (data$extraOps)"; + } } diff --git a/src/Query/Delete.php b/src/Query/Delete.php index 576378e..f043bd7 100644 --- a/src/Query/Delete.php +++ b/src/Query/Delete.php @@ -35,4 +35,28 @@ class Delete { return "DELETE FROM $tableName WHERE " . Query::whereByFields($fields, $match); } + + /** + * Query to delete documents using a JSON containment query (PostgreSQL only) + * + * @param string $tableName The name of the table from which documents should be deleted + * @return string The DELETE statement to delete documents via a JSON containment query + * @throws DocumentException If the database mode is not PostgreSQL + */ + public static function byContains(string $tableName): string + { + return "DELETE FROM $tableName WHERE " . Query::whereDataContains(); + } + + /** + * Query to delete documents using a JSON Path match query (PostgreSQL only) + * + * @param string $tableName The name of the table from which documents should be deleted + * @return string The DELETE statement to delete documents via a JSON Path match + * @throws DocumentException If the database mode is not PostgreSQL + */ + public static function byJsonPath(string $tableName): string + { + return "DELETE FROM $tableName WHERE " . Query::whereJsonPathMatches(); + } } diff --git a/src/Query/Exists.php b/src/Query/Exists.php index f2d07ee..f6eb305 100644 --- a/src/Query/Exists.php +++ b/src/Query/Exists.php @@ -47,4 +47,28 @@ class Exists { return self::query($tableName, Query::whereByFields($fields, $match)); } + + /** + * Query to determine if documents exist using a JSON containment query (PostgreSQL only) + * + * @param string $tableName The name of the table in which document existence should be checked + * @return string The query to determine document existence by a JSON containment query + * @throws DocumentException If the database mode is not PostgreSQL + */ + public static function byContains(string $tableName): string + { + return self::query($tableName, Query::whereDataContains()); + } + + /** + * Query to determine if documents exist using a JSON Path match query (PostgreSQL only) + * + * @param string $tableName The name of the table in which document existence should be checked + * @return string The query to determine document existence by a JSON Path match + * @throws DocumentException If the database mode is not PostgreSQL + */ + public static function byJsonPath(string $tableName): string + { + return self::query($tableName, Query::whereJsonPathMatches()); + } } diff --git a/src/Query/Find.php b/src/Query/Find.php index 68e004b..c649208 100644 --- a/src/Query/Find.php +++ b/src/Query/Find.php @@ -35,4 +35,28 @@ class Find { return Query::selectFromTable($tableName) . ' WHERE ' . Query::whereByFields($fields, $match); } + + /** + * Query to retrieve documents using a JSON containment query (PostgreSQL only) + * + * @param string $tableName The name of the table from which documents should be retrieved + * @return string The SELECT statement to retrieve documents by a JSON containment query + * @throws DocumentException If the database mode is not PostgreSQL + */ + public static function byContains(string $tableName): string + { + return Query::selectFromTable($tableName) . ' WHERE ' . Query::whereDataContains(); + } + + /** + * Query to retrieve documents using a JSON Path match query (PostgreSQL only) + * + * @param string $tableName The name of the table from which documents should be retrieved + * @return string The SELECT statement to retrieve documents by a JSON Path match + * @throws DocumentException If the database mode is not PostgreSQL + */ + public static function byJsonPath(string $tableName): string + { + return Query::selectFromTable($tableName) . ' WHERE ' . Query::whereJsonPathMatches(); + } } diff --git a/src/Query/Patch.php b/src/Query/Patch.php index 2cfd059..d320735 100644 --- a/src/Query/Patch.php +++ b/src/Query/Patch.php @@ -53,4 +53,28 @@ class Patch { return self::update($tableName, Query::whereByFields($field, $match)); } + + /** + * Query to patch (partially update) a document via a JSON containment query (PostgreSQL only) + * + * @param string $tableName The name of the table in which documents should be patched + * @return string The query to patch documents via a JSON containment query + * @throws DocumentException If the database mode is not PostgreSQL + */ + public static function byContains(string $tableName): string + { + return self::update($tableName, Query::whereDataContains()); + } + + /** + * Query to patch (partially update) a document via a JSON Path match query (PostgreSQL only) + * + * @param string $tableName The name of the table in which documents should be patched + * @return string The query to patch documents via a JSON Path match + * @throws DocumentException If the database mode is not PostgreSQL + */ + public static function byJsonPath(string $tableName): string + { + return self::update($tableName, Query::whereJsonPathMatches()); + } } diff --git a/src/Query/RemoveFields.php b/src/Query/RemoveFields.php index 766395c..a35c641 100644 --- a/src/Query/RemoveFields.php +++ b/src/Query/RemoveFields.php @@ -65,4 +65,30 @@ class RemoveFields { return self::update($tableName, $parameters, Query::whereByFields($fields, $match)); } + + /** + * 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 + * @return string The UPDATE statement to remove fields from documents via a JSON containment query + * @throws DocumentException If the database mode is not PostgreSQL + */ + public static function byContains(string $tableName, array $parameters): string + { + return self::update($tableName, $parameters, Query::whereDataContains()); + } + + /** + * 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 + * @return string The UPDATE statement to remove fields from documents via a JSON Path match + * @throws DocumentException + */ + public static function byJsonPath(string $tableName, array $parameters): string + { + return self::update($tableName, $parameters, Query::whereJsonPathMatches()); + } } diff --git a/tests/integration/postgresql/DefinitionTest.php b/tests/integration/postgresql/DefinitionTest.php index ff3d5c8..e770704 100644 --- a/tests/integration/postgresql/DefinitionTest.php +++ b/tests/integration/postgresql/DefinitionTest.php @@ -2,7 +2,7 @@ namespace Test\Integration\PostgreSQL; -use BitBadger\PDODocument\{Custom, Definition, DocumentException}; +use BitBadger\PDODocument\{Custom, Definition, DocumentException, DocumentIndex}; use BitBadger\PDODocument\Mapper\ExistsMapper; use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; @@ -41,7 +41,7 @@ class DefinitionTest extends TestCase [':name' => $name], new ExistsMapper()); } - public function testEnsureTableSucceeds() + public function testEnsureTableSucceeds(): void { $this->assertFalse($this->itExists('ensured'), 'The table should not exist already'); $this->assertFalse($this->itExists('idx_ensured_key'), 'The key index should not exist already'); @@ -50,11 +50,29 @@ class DefinitionTest extends TestCase $this->assertTrue($this->itExists('idx_ensured_key'), 'The key index should now exist'); } - public function testEnsureFieldIndexSucceeds() + public function testEnsureFieldIndexSucceeds(): void { $this->assertFalse($this->itExists('idx_ensured_test'), 'The index should not exist already'); Definition::ensureTable('ensured'); Definition::ensureFieldIndex('ensured', 'test', ['name', 'age']); $this->assertTrue($this->itExists('idx_ensured_test'), 'The index should now exist'); } + + public function testEnsureDocumentIndexSucceedsForFull(): void + { + $docIdx = 'idx_' . ThrowawayDb::TABLE . '_document'; + Definition::ensureTable(ThrowawayDb::TABLE); + $this->assertFalse($this->itExists($docIdx), 'The document index should not exist'); + Definition::ensureDocumentIndex(ThrowawayDb::TABLE, DocumentIndex::Full); + $this->assertTrue($this->itExists($docIdx), 'The document index should now exist'); + } + + public function testEnsureDocumentIndexSucceedsForOptimized(): void + { + $docIdx = 'idx_' . ThrowawayDb::TABLE . '_document'; + Definition::ensureTable(ThrowawayDb::TABLE); + $this->assertFalse($this->itExists($docIdx), 'The document index should not exist'); + Definition::ensureDocumentIndex(ThrowawayDb::TABLE, DocumentIndex::Optimized); + $this->assertTrue($this->itExists($docIdx), 'The document index should now exist'); + } } diff --git a/tests/integration/sqlite/DefinitionTest.php b/tests/integration/sqlite/DefinitionTest.php index 59b192f..f89304a 100644 --- a/tests/integration/sqlite/DefinitionTest.php +++ b/tests/integration/sqlite/DefinitionTest.php @@ -2,7 +2,7 @@ namespace Test\Integration\SQLite; -use BitBadger\PDODocument\{Custom, Definition, DocumentException}; +use BitBadger\PDODocument\{Custom, Definition, DocumentException, DocumentIndex}; use BitBadger\PDODocument\Mapper\ExistsMapper; use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; @@ -41,7 +41,7 @@ class DefinitionTest extends TestCase [':name' => $name], new ExistsMapper()); } - public function testEnsureTableSucceeds() + public function testEnsureTableSucceeds(): void { $this->assertFalse($this->itExists('ensured'), 'The table should not exist already'); $this->assertFalse($this->itExists('idx_ensured_key'), 'The key index should not exist already'); @@ -50,11 +50,17 @@ class DefinitionTest extends TestCase $this->assertTrue($this->itExists('idx_ensured_key'), 'The key index should now exist'); } - public function testEnsureFieldIndexSucceeds() + public function testEnsureFieldIndexSucceeds(): void { $this->assertFalse($this->itExists('idx_ensured_test'), 'The index should not exist already'); Definition::ensureTable('ensured'); Definition::ensureFieldIndex('ensured', 'test', ['name', 'age']); $this->assertTrue($this->itExists('idx_ensured_test'), 'The index should now exist'); } + + public function testEnsureDocumentIndexFails(): void + { + $this->expectException(DocumentException::class); + Definition::ensureDocumentIndex('nope', DocumentIndex::Full); + } } diff --git a/tests/integration/sqlite/ThrowawayDb.php b/tests/integration/sqlite/ThrowawayDb.php index 6b4f56a..ff2b1b2 100644 --- a/tests/integration/sqlite/ThrowawayDb.php +++ b/tests/integration/sqlite/ThrowawayDb.php @@ -48,6 +48,6 @@ class ThrowawayDb public static function destroy(string $fileName): void { Configuration::resetPDO(); - unlink("./$fileName"); + if (file_exists("./$fileName")) unlink("./$fileName"); } } diff --git a/tests/unit/ConfigurationTest.php b/tests/unit/ConfigurationTest.php index 50dd909..6eb80f7 100644 --- a/tests/unit/ConfigurationTest.php +++ b/tests/unit/ConfigurationTest.php @@ -9,6 +9,7 @@ use PHPUnit\Framework\TestCase; /** * Unit tests for the Configuration class */ +#[TestDox('Configuration (Unit tests)')] class ConfigurationTest extends TestCase { #[TestDox('ID field default succeeds')] diff --git a/tests/unit/DocumentExceptionTest.php b/tests/unit/DocumentExceptionTest.php index 7103575..c068473 100644 --- a/tests/unit/DocumentExceptionTest.php +++ b/tests/unit/DocumentExceptionTest.php @@ -4,11 +4,13 @@ namespace Test\Unit; use BitBadger\PDODocument\DocumentException; use Exception; +use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; /** * Unit tests for the DocumentException class */ +#[TestDox('Document Exception (Unit tests)')] class DocumentExceptionTest extends TestCase { public function testConstructorSucceedsWithCodeAndPriorException() diff --git a/tests/unit/FieldMatchTest.php b/tests/unit/FieldMatchTest.php index 9fd8942..f7d1ea4 100644 --- a/tests/unit/FieldMatchTest.php +++ b/tests/unit/FieldMatchTest.php @@ -3,11 +3,13 @@ namespace Test\Unit; use BitBadger\PDODocument\FieldMatch; +use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; /** * Unit tests for the FieldMatch enum */ +#[TestDox('Field Match (Unit tests)')] class FieldMatchTest extends TestCase { public function testToStringSucceedsForAll(): void diff --git a/tests/unit/FieldTest.php b/tests/unit/FieldTest.php index d2639c4..a98bb12 100644 --- a/tests/unit/FieldTest.php +++ b/tests/unit/FieldTest.php @@ -9,6 +9,7 @@ use PHPUnit\Framework\TestCase; /** * Unit tests for the Field class */ +#[TestDox('Field (Unit tests)')] class FieldTest extends TestCase { #[TestDox('Append parameter succeeds for EX')] diff --git a/tests/unit/Mapper/ArrayMapperTest.php b/tests/unit/Mapper/ArrayMapperTest.php index 51a8603..b16de99 100644 --- a/tests/unit/Mapper/ArrayMapperTest.php +++ b/tests/unit/Mapper/ArrayMapperTest.php @@ -3,11 +3,13 @@ namespace Test\Unit\Mapper; use BitBadger\PDODocument\Mapper\ArrayMapper; +use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; /** * Unit tests for the ArrayMapper class */ +#[TestDox('Array Mapper (Unit tests)')] class ArrayMapperTest extends TestCase { public function testMapSucceeds(): void diff --git a/tests/unit/Mapper/CountMapperTest.php b/tests/unit/Mapper/CountMapperTest.php index 130763a..cdc04f2 100644 --- a/tests/unit/Mapper/CountMapperTest.php +++ b/tests/unit/Mapper/CountMapperTest.php @@ -3,11 +3,13 @@ namespace Test\Unit\Mapper; use BitBadger\PDODocument\Mapper\CountMapper; +use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; /** * Unit tests for the CountMapper class */ +#[TestDox('Count Mapper (Unit tests)')] class CountMapperTest extends TestCase { public function testMapSucceeds(): void diff --git a/tests/unit/Mapper/DocumentMapperTest.php b/tests/unit/Mapper/DocumentMapperTest.php index 5213312..691dedf 100644 --- a/tests/unit/Mapper/DocumentMapperTest.php +++ b/tests/unit/Mapper/DocumentMapperTest.php @@ -22,6 +22,7 @@ class TestDocument /** * Unit tests for the DocumentMapper class */ +#[TestDox('Document Mapper (Unit tests)')] class DocumentMapperTest extends TestCase { public function testConstructorSucceedsWithDefaultField(): void diff --git a/tests/unit/Mapper/ExistsMapperTest.php b/tests/unit/Mapper/ExistsMapperTest.php index 1dbaf02..7e4eac8 100644 --- a/tests/unit/Mapper/ExistsMapperTest.php +++ b/tests/unit/Mapper/ExistsMapperTest.php @@ -10,6 +10,7 @@ use PHPUnit\Framework\TestCase; /** * Unit tests for the ExistsMapper class */ +#[TestDox('Exists Mapper (Unit tests)')] class ExistsMapperTest extends TestCase { #[TestDox('Map succeeds for PostgreSQL')] diff --git a/tests/unit/Mapper/StringMapperTest.php b/tests/unit/Mapper/StringMapperTest.php index 57c1c0a..9bda0ca 100644 --- a/tests/unit/Mapper/StringMapperTest.php +++ b/tests/unit/Mapper/StringMapperTest.php @@ -3,8 +3,13 @@ namespace Test\Unit\Mapper; use BitBadger\PDODocument\Mapper\StringMapper; +use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; +/** + * Unit tests for the StringMapper class + */ +#[TestDox('String Mapper (Unit tests)')] class StringMapperTest extends TestCase { public function testMapSucceedsWhenFieldIsPresentAndString() diff --git a/tests/unit/OpTest.php b/tests/unit/OpTest.php index 3cb3106..cac2247 100644 --- a/tests/unit/OpTest.php +++ b/tests/unit/OpTest.php @@ -9,6 +9,7 @@ use PHPUnit\Framework\TestCase; /** * Unit tests for the Op enumeration */ +#[TestDox('Op (Unit tests)')] class OpTest extends TestCase { #[TestDox('To string succeeds for EQ')] diff --git a/tests/unit/ParametersTest.php b/tests/unit/ParametersTest.php index 3d1595d..9ef2002 100644 --- a/tests/unit/ParametersTest.php +++ b/tests/unit/ParametersTest.php @@ -9,6 +9,7 @@ use PHPUnit\Framework\TestCase; /** * Unit tests for the Parameters class */ +#[TestDox('Parameters (Unit tests)')] class ParametersTest extends TestCase { #[TestDox('ID succeeds with string')] diff --git a/tests/unit/Query/CountTest.php b/tests/unit/Query/CountTest.php index 69eb6a7..58d9ac0 100644 --- a/tests/unit/Query/CountTest.php +++ b/tests/unit/Query/CountTest.php @@ -2,30 +2,64 @@ namespace Test\Unit\Query; -use BitBadger\PDODocument\{Configuration, Field, Mode}; +use BitBadger\PDODocument\{Configuration, DocumentException, Field, Mode}; use BitBadger\PDODocument\Query\Count; +use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; /** * Unit tests for the Count class */ +#[TestDox('Count Queries (Unit tests)')] class CountTest extends TestCase { + public function tearDown(): void + { + Configuration::$mode = null; + parent::tearDown(); + } - public function testAllSucceeds() + public function testAllSucceeds(): void { $this->assertEquals('SELECT COUNT(*) FROM a_table', Count::all('a_table'), 'SELECT statement not generated correctly'); } - public function testByFieldsSucceeds() + public function testByFieldsSucceeds(): void { Configuration::$mode = Mode::SQLite; - try { - $this->assertEquals("SELECT COUNT(*) FROM somewhere WHERE data->>'errors' > :errors", - Count::byFields('somewhere', [Field::GT('errors', 10, ':errors')])); - } finally { - Configuration::$mode = null; - } + $this->assertEquals("SELECT COUNT(*) FROM somewhere WHERE data->>'errors' > :errors", + Count::byFields('somewhere', [Field::GT('errors', 10, ':errors')]), + 'SELECT statement not generated correctly'); + } + + #[TestDox('By contains succeeds for PostgreSQL')] + public function testByContainsSucceedsForPostgreSQL(): void + { + Configuration::$mode = Mode::PgSQL; + $this->assertEquals("SELECT COUNT(*) FROM the_table WHERE data @> :criteria", Count::byContains('the_table'), + 'SELECT statement not generated correctly'); + } + + #[TestDox('By contains fails for non PostgreSQL')] + public function testByContainsFailsForNonPostgreSQL(): void + { + $this->expectException(DocumentException::class); + Count::byContains(''); + } + + #[TestDox('By JSON Path succeeds for PostgreSQL')] + public function testByJsonPathSucceedsForPostgreSQL(): void + { + Configuration::$mode = Mode::PgSQL; + $this->assertEquals("SELECT COUNT(*) FROM a_table WHERE data @? :path::jsonpath", Count::byJsonPath('a_table'), + 'SELECT statement not generated correctly'); + } + + #[TestDox('By JSON Path fails for non PostgreSQL')] + public function testByJsonPathFailsForNonPostgreSQL(): void + { + $this->expectException(DocumentException::class); + Count::byJsonPath(''); } } diff --git a/tests/unit/Query/DefinitionTest.php b/tests/unit/Query/DefinitionTest.php index c579db3..3b5db8f 100644 --- a/tests/unit/Query/DefinitionTest.php +++ b/tests/unit/Query/DefinitionTest.php @@ -2,7 +2,7 @@ namespace Test\Unit\Query; -use BitBadger\PDODocument\{Configuration, DocumentException, Mode}; +use BitBadger\PDODocument\{Configuration, DocumentException, DocumentIndex, Mode}; use BitBadger\PDODocument\Query\Definition; use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; @@ -10,36 +10,34 @@ use PHPUnit\Framework\TestCase; /** * Unit tests for the Definition class */ +#[TestDox('Definition Queries (Unit tests)')] class DefinitionTest extends TestCase { + protected function tearDown(): void + { + Configuration::$mode = null; + parent::tearDown(); + } + #[TestDox('Ensure table succeeds for PosgtreSQL')] public function testEnsureTableSucceedsForPostgreSQL(): void { - try { - Configuration::$mode = Mode::PgSQL; - $this->assertEquals('CREATE TABLE IF NOT EXISTS documents (data JSONB NOT NULL)', - Definition::ensureTable('documents'), 'CREATE TABLE statement not generated correctly'); - } finally { - Configuration::$mode = null; - } + Configuration::$mode = Mode::PgSQL; + $this->assertEquals('CREATE TABLE IF NOT EXISTS documents (data JSONB NOT NULL)', + Definition::ensureTable('documents'), 'CREATE TABLE statement not generated correctly'); } #[TestDox('Ensure table succeeds for SQLite')] public function testEnsureTableSucceedsForSQLite(): void { - try { - Configuration::$mode = Mode::SQLite; - $this->assertEquals('CREATE TABLE IF NOT EXISTS dox (data TEXT NOT NULL)', Definition::ensureTable('dox'), - 'CREATE TABLE statement not generated correctly'); - } finally { - Configuration::$mode = null; - } + Configuration::$mode = Mode::SQLite; + $this->assertEquals('CREATE TABLE IF NOT EXISTS dox (data TEXT NOT NULL)', Definition::ensureTable('dox'), + 'CREATE TABLE statement not generated correctly'); } public function testEnsureTableFailsWhenModeNotSet(): void { $this->expectException(DocumentException::class); - Configuration::$mode = null; Definition::ensureTable('boom'); } @@ -57,9 +55,30 @@ class DefinitionTest extends TestCase 'CREATE INDEX statement not generated correctly'); } - public function testEnsureKey(): void + public function testEnsureKeySucceeds(): void { $this->assertEquals("CREATE UNIQUE INDEX IF NOT EXISTS idx_tbl_key ON tbl ((data->>'id'))", Definition::ensureKey('tbl'), 'CREATE INDEX statement for document key not generated correctly'); } + + public function testEnsureDocumentIndexOnSucceedsForSchemaAndFull(): void + { + Configuration::$mode = Mode::PgSQL; + $this->assertEquals("CREATE INDEX IF NOT EXISTS idx_tbl_document ON my.tbl USING GIN (data)", + Definition::ensureDocumentIndexOn('my.tbl', DocumentIndex::Full)); + } + + public function testEnsureDocumentIndexOnSucceedsForNoSchemaAndOptimized(): void + { + Configuration::$mode = Mode::PgSQL; + $this->assertEquals("CREATE INDEX IF NOT EXISTS idx_it_document ON it USING GIN (data jsonb_path_ops)", + Definition::ensureDocumentIndexOn('it', DocumentIndex::Optimized)); + } + + #[TestDox('Ensure document index on fails for non PostgreSQL')] + public function testEnsureDocumentIndexOnFailsForNonPostgreSQL(): void + { + $this->expectException(DocumentException::class); + Definition::ensureDocumentIndexOn('', DocumentIndex::Full); + } } diff --git a/tests/unit/Query/DeleteTest.php b/tests/unit/Query/DeleteTest.php index 1ac3c7b..9efe38b 100644 --- a/tests/unit/Query/DeleteTest.php +++ b/tests/unit/Query/DeleteTest.php @@ -2,7 +2,7 @@ namespace Test\Unit\Query; -use BitBadger\PDODocument\{Configuration, Field, Mode}; +use BitBadger\PDODocument\{Configuration, DocumentException, Field, Mode}; use BitBadger\PDODocument\Query\Delete; use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; @@ -10,13 +10,9 @@ use PHPUnit\Framework\TestCase; /** * Unit tests for the Delete class */ +#[TestDox('Delete Queries (Unit tests)')] class DeleteTest extends TestCase { - protected function setUp(): void - { - Configuration::$mode = Mode::SQLite; - } - protected function tearDown(): void { Configuration::$mode = null; @@ -25,14 +21,46 @@ class DeleteTest extends TestCase #[TestDox('By ID succeeds')] public function testByIdSucceeds(): void { + Configuration::$mode = Mode::SQLite; $this->assertEquals("DELETE FROM over_there WHERE data->>'id' = :id", Delete::byId('over_there'), 'DELETE statement not constructed correctly'); } public function testByFieldsSucceeds(): void { + Configuration::$mode = Mode::SQLite; $this->assertEquals("DELETE FROM my_table WHERE data->>'value' < :max AND data->>'value' >= :min", Delete::byFields('my_table', [Field::LT('value', 99, ':max'), Field::GE('value', 18, ':min')]), 'DELETE statement not constructed correctly'); } + + #[TestDox('By contains succeeds for PostgreSQL')] + public function testByContainsSucceedsForPostgreSQL(): void + { + Configuration::$mode = Mode::PgSQL; + $this->assertEquals('DELETE FROM somewhere WHERE data @> :criteria', Delete::byContains('somewhere'), + 'DELETE statement not constructed correctly'); + } + + #[TestDox('By contains fails for non PostgreSQL')] + public function testByContainsFailsForNonPostgreSQL(): void + { + $this->expectException(DocumentException::class); + Delete::byContains(''); + } + + #[TestDox('By JSON Path succeeds for PostgreSQL')] + public function testByJsonPathSucceedsForPostgreSQL(): void + { + Configuration::$mode = Mode::PgSQL; + $this->assertEquals('DELETE FROM here WHERE data @? :path::jsonpath', Delete::byJsonPath('here'), + 'DELETE statement not constructed correctly'); + } + + #[TestDox('By JSON Path fails for non PostgreSQL')] + public function testByJsonPathFailsForNonPostgreSQL(): void + { + $this->expectException(DocumentException::class); + Delete::byJsonPath(''); + } } diff --git a/tests/unit/Query/ExistsTest.php b/tests/unit/Query/ExistsTest.php index 416c9dd..ba77418 100644 --- a/tests/unit/Query/ExistsTest.php +++ b/tests/unit/Query/ExistsTest.php @@ -2,7 +2,7 @@ namespace Test\Unit\Query; -use BitBadger\PDODocument\{Configuration, Field, Mode}; +use BitBadger\PDODocument\{Configuration, DocumentException, Field, Mode}; use BitBadger\PDODocument\Query\Exists; use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; @@ -10,13 +10,9 @@ use PHPUnit\Framework\TestCase; /** * Unit tests for the Exists class */ +#[TestDox('Exists Queries (Unit tests)')] class ExistsTest extends TestCase { - protected function setUp(): void - { - Configuration::$mode = Mode::SQLite; - } - protected function tearDown(): void { Configuration::$mode = null; @@ -24,6 +20,7 @@ class ExistsTest extends TestCase public function testQuerySucceeds(): void { + Configuration::$mode = Mode::SQLite; $this->assertEquals('SELECT EXISTS (SELECT 1 FROM abc WHERE def)', Exists::query('abc', 'def'), 'Existence query not generated correctly'); } @@ -31,14 +28,46 @@ class ExistsTest extends TestCase #[TestDox('By ID succeeds')] public function testByIdSucceeds(): void { + Configuration::$mode = Mode::SQLite; $this->assertEquals("SELECT EXISTS (SELECT 1 FROM dox WHERE data->>'id' = :id)", Exists::byId('dox'), 'Existence query not generated correctly'); } public function testByFieldsSucceeds(): void { + Configuration::$mode = Mode::SQLite; $this->assertEquals("SELECT EXISTS (SELECT 1 FROM box WHERE data->>'status' <> :status)", Exists::byFields('box', [Field::NE('status', 'occupied', ':status')]), 'Existence query not generated correctly'); } + + #[TestDox('By contains succeeds for PostgreSQL')] + public function testByContainsSucceedsForPostgreSQL(): void + { + Configuration::$mode = Mode::PgSQL; + $this->assertEquals('SELECT EXISTS (SELECT 1 FROM pocket WHERE data @> :criteria)', + Exists::byContains('pocket'), 'Existence query not generated correctly'); + } + + #[TestDox('By contains fails for non PostgreSQL')] + public function testByContainsFailsForNonPostgreSQL(): void + { + $this->expectException(DocumentException::class); + Exists::byContains(''); + } + + #[TestDox('By JSON Path succeeds for PostgreSQL')] + public function testByJsonPathSucceedsForPostgreSQL(): void + { + Configuration::$mode = Mode::PgSQL; + $this->assertEquals('SELECT EXISTS (SELECT 1 FROM lint WHERE data @? :path::jsonpath)', + Exists::byJsonPath('lint'), 'Existence query not generated correctly'); + } + + #[TestDox('By JSON Path fails for non PostgreSQL')] + public function testByJsonPathFailsForNonPostgreSQL(): void + { + $this->expectException(DocumentException::class); + Exists::byJsonPath(''); + } } diff --git a/tests/unit/Query/FindTest.php b/tests/unit/Query/FindTest.php index 10e7d73..2a98d82 100644 --- a/tests/unit/Query/FindTest.php +++ b/tests/unit/Query/FindTest.php @@ -2,7 +2,7 @@ namespace Test\Unit\Query; -use BitBadger\PDODocument\{Configuration, Field, FieldMatch, Mode}; +use BitBadger\PDODocument\{Configuration, DocumentException, Field, FieldMatch, Mode}; use BitBadger\PDODocument\Query\Find; use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; @@ -10,13 +10,9 @@ use PHPUnit\Framework\TestCase; /** * Unit tests for the Find class */ +#[TestDox('Find Queries (Unit tests)')] class FindTest extends TestCase { - protected function setUp(): void - { - Configuration::$mode = Mode::SQLite; - } - protected function tearDown(): void { Configuration::$mode = null; @@ -25,15 +21,47 @@ class FindTest extends TestCase #[TestDox('By ID succeeds')] public function testByIdSucceeds(): void { + Configuration::$mode = Mode::SQLite; $this->assertEquals("SELECT data FROM here WHERE data->>'id' = :id", Find::byId('here'), 'SELECT query not generated correctly'); } public function testByFieldsSucceeds(): void { + Configuration::$mode = Mode::SQLite; $this->assertEquals("SELECT data FROM there WHERE data->>'active' = :act OR data->>'locked' = :lock", Find::byFields('there', [Field::EQ('active', true, ':act'), Field::EQ('locked', true, ':lock')], FieldMatch::Any), 'SELECT query not generated correctly'); } + + #[TestDox('By contains succeeds for PostgreSQL')] + public function testByContainsSucceedsForPostgreSQL(): void + { + Configuration::$mode = Mode::PgSQL; + $this->assertEquals('SELECT data FROM disc WHERE data @> :criteria', Find::byContains('disc'), + 'SELECT query not generated correctly'); + } + + #[TestDox('By contains fails for non PostgreSQL')] + public function testByContainsFailsForNonPostgreSQL(): void + { + $this->expectException(DocumentException::class); + Find::byContains(''); + } + + #[TestDox('By JSON Path succeeds for PostgreSQL')] + public function testByJsonPathSucceedsForPostgreSQL(): void + { + Configuration::$mode = Mode::PgSQL; + $this->assertEquals('SELECT data FROM light WHERE data @? :path::jsonpath', Find::byJsonPath('light'), + 'SELECT query not generated correctly'); + } + + #[TestDox('By JSON Path fails for non PostgreSQL')] + public function testByJsonPathFailsForNonPostgreSQL(): void + { + $this->expectException(DocumentException::class); + Find::byJsonPath(''); + } } diff --git a/tests/unit/Query/PatchTest.php b/tests/unit/Query/PatchTest.php index f4b1608..bf5e05e 100644 --- a/tests/unit/Query/PatchTest.php +++ b/tests/unit/Query/PatchTest.php @@ -10,71 +10,87 @@ use PHPUnit\Framework\TestCase; /** * Unit tests for the Patch class */ +#[TestDox('Patch Queries (Unit tests)')] class PatchTest extends TestCase { + protected function tearDown(): void + { + Configuration::$mode = null; + parent::tearDown(); + } #[TestDox('By ID succeeds for PostgreSQL')] public function testByIdSucceedsForPostgreSQL(): void { - try { - Configuration::$mode = Mode::PgSQL; - $this->assertEquals("UPDATE doc_table SET data = data || :data WHERE data->>'id' = :id", - Patch::byId('doc_table'), 'Patch UPDATE statement is not correct'); - } finally { - Configuration::$mode = null; - } + Configuration::$mode = Mode::PgSQL; + $this->assertEquals("UPDATE doc_table SET data = data || :data WHERE data->>'id' = :id", + Patch::byId('doc_table'), 'Patch UPDATE statement is not correct'); } #[TestDox('By ID succeeds for SQLite')] public function testByIdSucceedsForSQLite(): void { - try { - Configuration::$mode = Mode::SQLite; - $this->assertEquals("UPDATE my_table SET data = json_patch(data, json(:data)) WHERE data->>'id' = :id", - Patch::byId('my_table'), 'Patch UPDATE statement is not correct'); - } finally { - Configuration::$mode = null; - } + Configuration::$mode = Mode::SQLite; + $this->assertEquals("UPDATE my_table SET data = json_patch(data, json(:data)) WHERE data->>'id' = :id", + Patch::byId('my_table'), 'Patch UPDATE statement is not correct'); } #[TestDox('By ID fails when mode not set')] public function testByIdFailsWhenModeNotSet(): void { $this->expectException(DocumentException::class); - Configuration::$mode = null; Patch::byId('oof'); } #[TestDox('By fields succeeds for PostgreSQL')] public function testByFieldsSucceedsForPostgreSQL(): void { - try { - Configuration::$mode = Mode::PgSQL; - $this->assertEquals("UPDATE that SET data = data || :data WHERE (data->>'something')::numeric < :some", - Patch::byFields('that', [Field::LT('something', 17, ':some')]), - 'Patch UPDATE statement is not correct'); - } finally { - Configuration::$mode = null; - } + Configuration::$mode = Mode::PgSQL; + $this->assertEquals("UPDATE that SET data = data || :data WHERE (data->>'something')::numeric < :some", + Patch::byFields('that', [Field::LT('something', 17, ':some')]), 'Patch UPDATE statement is not correct'); } #[TestDox('By fields succeeds for SQLite')] public function testByFieldsSucceedsForSQLite(): void { - try { - Configuration::$mode = Mode::SQLite; - $this->assertEquals( - "UPDATE a_table SET data = json_patch(data, json(:data)) WHERE data->>'something' > :it", - Patch::byFields('a_table', [Field::GT('something', 17, ':it')]), - 'Patch UPDATE statement is not correct'); - } finally { - Configuration::$mode = null; - } + Configuration::$mode = Mode::SQLite; + $this->assertEquals( + "UPDATE a_table SET data = json_patch(data, json(:data)) WHERE data->>'something' > :it", + Patch::byFields('a_table', [Field::GT('something', 17, ':it')]), 'Patch UPDATE statement is not correct'); } public function testByFieldsFailsWhenModeNotSet(): void { $this->expectException(DocumentException::class); - Configuration::$mode = null; Patch::byFields('oops', []); } + + #[TestDox('By contains succeeds for PostgreSQL')] + public function testByContainsSucceedsForPostgreSQL(): void + { + Configuration::$mode = Mode::PgSQL; + $this->assertEquals('UPDATE this SET data = data || :data WHERE data @> :criteria', Patch::byContains('this'), + 'Patch UPDATE statement is not correct'); + } + + #[TestDox('By contains fails for non PostgreSQL')] + public function testByContainsFailsForNonPostgreSQL(): void + { + $this->expectException(DocumentException::class); + Patch::byContains(''); + } + + #[TestDox('By JSON Path succeeds for PostgreSQL')] + public function testByJsonPathSucceedsForPostgreSQL(): void + { + Configuration::$mode = Mode::PgSQL; + $this->assertEquals('UPDATE that SET data = data || :data WHERE data @? :path::jsonpath', + Patch::byJsonPath('that'), 'Patch UPDATE statement is not correct'); + } + + #[TestDox('By JSON Path fails for non PostgreSQL')] + public function testByJsonPathFailsForNonPostgreSQL(): void + { + $this->expectException(DocumentException::class); + Patch::byJsonPath(''); + } } diff --git a/tests/unit/Query/RemoveFieldsTest.php b/tests/unit/Query/RemoveFieldsTest.php index 1933845..7d5dfac 100644 --- a/tests/unit/Query/RemoveFieldsTest.php +++ b/tests/unit/Query/RemoveFieldsTest.php @@ -10,108 +10,117 @@ use PHPUnit\Framework\TestCase; /** * Unit tests for the RemoveFields class */ +#[TestDox('Remove Fields Queries (Unit tests)')] class RemoveFieldsTest extends TestCase { + protected function tearDown(): void + { + Configuration::$mode = null; + } + #[TestDox('Update succeeds for PostgreSQL')] public function testUpdateSucceedsForPostgreSQL(): void { - try { - Configuration::$mode = Mode::PgSQL; - $this->assertEquals('UPDATE taco SET data = data - :names::text[] WHERE it = true', - RemoveFields::update('taco', [':names' => "{one,two}"], 'it = true'), - 'UPDATE statement not correct'); - } finally { - Configuration::$mode = null; - } + Configuration::$mode = Mode::PgSQL; + $this->assertEquals('UPDATE taco SET data = data - :names::text[] WHERE it = true', + RemoveFields::update('taco', [':names' => "{one,two}"], 'it = true'), 'UPDATE statement not correct'); } #[TestDox('Update succeeds for SQLite')] public function testUpdateSucceedsForSQLite(): void { - try { - Configuration::$mode = Mode::SQLite; - $this->assertEquals('UPDATE burrito SET data = json_remove(data, :name0, :name1, :name2) WHERE a = b', - RemoveFields::update('burrito', Parameters::fieldNames(':name', ['one', 'two', 'ten']), 'a = b'), - 'UPDATE statement not correct'); - } finally { - Configuration::$mode = null; - } + Configuration::$mode = Mode::SQLite; + $this->assertEquals('UPDATE burrito SET data = json_remove(data, :name0, :name1, :name2) WHERE a = b', + RemoveFields::update('burrito', Parameters::fieldNames(':name', ['one', 'two', 'ten']), 'a = b'), + 'UPDATE statement not correct'); } public function testUpdateFailsWhenModeNotSet(): void { $this->expectException(DocumentException::class); - Configuration::$mode = null; RemoveFields::update('wow', [], ''); } #[TestDox('By ID succeeds for PostgreSQL')] public function testByIdSucceedsForPostgreSQL() { - try { - Configuration::$mode = Mode::PgSQL; - $this->assertEquals("UPDATE churro SET data = data - :bite::text[] WHERE data->>'id' = :id", - RemoveFields::byId('churro', Parameters::fieldNames(':bite', ['byte'])), - 'UPDATE statement not correct'); - } finally { - Configuration::$mode = null; - } + Configuration::$mode = Mode::PgSQL; + $this->assertEquals("UPDATE churro SET data = data - :bite::text[] WHERE data->>'id' = :id", + RemoveFields::byId('churro', Parameters::fieldNames(':bite', ['byte'])), 'UPDATE statement not correct'); } #[TestDox('By ID succeeds for SQLite')] public function testByIdSucceedsForSQLite() { - try { - Configuration::$mode = Mode::SQLite; - $this->assertEquals("UPDATE quesadilla SET data = json_remove(data, :bite0) WHERE data->>'id' = :id", - RemoveFields::byId('quesadilla', Parameters::fieldNames(':bite', ['byte'])), - 'UPDATE statement not correct'); - } finally { - Configuration::$mode = null; - } + Configuration::$mode = Mode::SQLite; + $this->assertEquals("UPDATE quesadilla SET data = json_remove(data, :bite0) WHERE data->>'id' = :id", + RemoveFields::byId('quesadilla', Parameters::fieldNames(':bite', ['byte'])), + 'UPDATE statement not correct'); } #[TestDox('By ID fails when mode not set')] public function testByIdFailsWhenModeNotSet(): void { $this->expectException(DocumentException::class); - Configuration::$mode = null; RemoveFields::byId('oof', []); } #[TestDox('By fields succeeds for PostgreSQL')] public function testByFieldsSucceedsForPostgreSQL() { - try { - Configuration::$mode = Mode::PgSQL; - $this->assertEquals("UPDATE enchilada SET data = data - :sauce::text[] WHERE data->>'cheese' = :queso", - RemoveFields::byFields('enchilada', [Field::EQ('cheese', 'jack', ':queso')], - Parameters::fieldNames(':sauce', ['white'])), - 'UPDATE statement not correct'); - } finally { - Configuration::$mode = null; - } + Configuration::$mode = Mode::PgSQL; + $this->assertEquals("UPDATE enchilada SET data = data - :sauce::text[] WHERE data->>'cheese' = :queso", + RemoveFields::byFields('enchilada', [Field::EQ('cheese', 'jack', ':queso')], + Parameters::fieldNames(':sauce', ['white'])), + 'UPDATE statement not correct'); } #[TestDox('By fields succeeds for SQLite')] public function testByFieldsSucceedsForSQLite() { - try { - Configuration::$mode = Mode::SQLite; - $this->assertEquals( - "UPDATE chimichanga SET data = json_remove(data, :filling0) WHERE data->>'side' = :rice", - RemoveFields::byFields('chimichanga', [Field::EQ('side', 'beans', ':rice')], - Parameters::fieldNames(':filling', ['beef'])), - 'UPDATE statement not correct'); - } finally { - Configuration::$mode = null; - } + Configuration::$mode = Mode::SQLite; + $this->assertEquals( + "UPDATE chimichanga SET data = json_remove(data, :filling0) WHERE data->>'side' = :rice", + RemoveFields::byFields('chimichanga', [Field::EQ('side', 'beans', ':rice')], + Parameters::fieldNames(':filling', ['beef'])), + 'UPDATE statement not correct'); } public function testByFieldsFailsWhenModeNotSet(): void { $this->expectException(DocumentException::class); - Configuration::$mode = null; RemoveFields::byFields('boing', [], []); } + + #[TestDox('By contains succeeds for PostgreSQL')] + public function testByContainsSucceedsForPostgreSQL(): void + { + Configuration::$mode = Mode::PgSQL; + $this->assertEquals('UPDATE food SET data = data - :drink::text[] WHERE data @> :criteria', + RemoveFields::byContains('food', Parameters::fieldNames(':drink', ['a', 'b'])), + 'UPDATE statement not correct'); + } + + #[TestDox('By contains fails for non PostgreSQL')] + public function testByContainsFailsForNonPostgreSQL(): void + { + $this->expectException(DocumentException::class); + RemoveFields::byContains('', []); + } + + #[TestDox('By JSON Path succeeds for PostgreSQL')] + public function testByJsonPathSucceedsForPostgreSQL(): void + { + Configuration::$mode = Mode::PgSQL; + $this->assertEquals('UPDATE dessert SET data = data - :cake::text[] WHERE data @? :path::jsonpath', + RemoveFields::byJsonPath('dessert', Parameters::fieldNames(':cake', ['b', 'c'])), + 'UPDATE statement not correct'); + } + + #[TestDox('By JSON Path fails for non PostgreSQL')] + public function testByJsonPathFailsForNonPostgreSQL(): void + { + $this->expectException(DocumentException::class); + RemoveFields::byJsonPath('', []); + } } diff --git a/tests/unit/QueryTest.php b/tests/unit/QueryTest.php index a3418fe..3c0c945 100644 --- a/tests/unit/QueryTest.php +++ b/tests/unit/QueryTest.php @@ -9,6 +9,7 @@ use PHPUnit\Framework\TestCase; /** * Unit tests for the Query class */ +#[TestDox('Query (Unit tests)')] class QueryTest extends TestCase { protected function setUp(): void @@ -60,6 +61,68 @@ class QueryTest extends TestCase $this->assertEquals("data->>'id' = :di", Query::whereById(':di'), 'WHERE fragment not constructed correctly'); } + public function testWhereDataContainsSucceedsWithDefaultParameter(): void + { + Configuration::$mode = Mode::PgSQL; + try { + $this->assertEquals('data @> :criteria', Query::whereDataContains(), + 'WHERE fragment not constructed correctly'); + } finally { + Configuration::$mode = null; + } + } + + public function testWhereDataContainsSucceedsWithSpecifiedParameter(): void + { + Configuration::$mode = Mode::PgSQL; + try { + $this->assertEquals('data @> :it', Query::whereDataContains(':it'), + 'WHERE fragment not constructed correctly'); + } finally { + Configuration::$mode = null; + } + } + + #[TestDox('Where data contains fails if not PostgreSQL')] + public function testWhereDataContainsFailsIfNotPostgreSQL(): void + { + Configuration::$mode = null; + $this->expectException(DocumentException::class); + Query::whereDataContains(); + } + + #[TestDox('Where JSON Path matches succeeds with default parameter')] + public function testWhereJsonPathMatchesSucceedsWithDefaultParameter(): void + { + Configuration::$mode = Mode::PgSQL; + try { + $this->assertEquals('data @? :path::jsonpath', Query::whereJsonPathMatches(), + 'WHERE fragment not constructed correctly'); + } finally { + Configuration::$mode = null; + } + } + + #[TestDox('Where JSON Path matches succeeds with specified parameter')] + public function testWhereJsonPathMatchesSucceedsWithSpecifiedParameter(): void + { + Configuration::$mode = Mode::PgSQL; + try { + $this->assertEquals('data @? :road::jsonpath', Query::whereJsonPathMatches(':road'), + 'WHERE fragment not constructed correctly'); + } finally { + Configuration::$mode = null; + } + } + + #[TestDox('Where JSON Path matches fails if not PostgreSQL')] + public function testWhereJsonPathMatchesFailsIfNotPostgreSQL(): void + { + Configuration::$mode = null; + $this->expectException(DocumentException::class); + Query::whereJsonPathMatches(); + } + #[TestDox('Insert succeeds with no auto-ID for PostgreSQL')] public function testInsertSucceedsWithNoAutoIdForPostgreSQL(): void { -- 2.45.1 From 7de39a41fc48dd27f55ed019fa663c05bf95e425 Mon Sep 17 00:00:00 2001 From: "Daniel J. Summers" Date: Thu, 13 Jun 2024 21:39:16 -0400 Subject: [PATCH 3/4] Add byContains and byJsonPath throughout - Change to JSON Path function to work around PDO syntax quirk --- src/Count.php | 27 +++++++ src/Delete.php | 24 ++++++ src/Exists.php | 27 +++++++ src/Find.php | 62 +++++++++++++++ src/Patch.php | 28 +++++++ src/Query.php | 2 +- src/RemoveFields.php | 30 ++++++++ tests/integration/postgresql/CountTest.php | 26 +++++++ tests/integration/postgresql/DeleteTest.php | 30 ++++++++ tests/integration/postgresql/ExistsTest.php | 26 +++++++ tests/integration/postgresql/FindTest.php | 76 +++++++++++++++++++ tests/integration/postgresql/PatchTest.php | 51 ++++++++++++- .../postgresql/RemoveFieldsTest.php | 53 +++++++++++++ tests/integration/sqlite/CountTest.php | 15 +++- tests/integration/sqlite/DeleteTest.php | 15 +++- tests/integration/sqlite/ExistsTest.php | 16 +++- tests/integration/sqlite/FindTest.php | 28 ++++++- tests/integration/sqlite/PatchTest.php | 15 +++- tests/integration/sqlite/RemoveFieldsTest.php | 15 +++- tests/unit/Query/CountTest.php | 6 +- tests/unit/Query/DeleteTest.php | 4 +- tests/unit/Query/ExistsTest.php | 2 +- tests/unit/Query/FindTest.php | 4 +- tests/unit/Query/PatchTest.php | 2 +- tests/unit/Query/RemoveFieldsTest.php | 3 +- tests/unit/QueryTest.php | 4 +- 26 files changed, 569 insertions(+), 22 deletions(-) diff --git a/src/Count.php b/src/Count.php index 62b2513..8254d74 100644 --- a/src/Count.php +++ b/src/Count.php @@ -36,4 +36,31 @@ class Count return Custom::scalar(Query\Count::byFields($tableName, $namedFields, $match), Parameters::addFields($namedFields, []), new CountMapper()); } + + /** + * 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 + * @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 + */ + public static function byContains(string $tableName, array|object $criteria): int + { + return Custom::scalar(Query\Count::byContains($tableName), Parameters::json(':criteria', $criteria), + new CountMapper()); + } + + /** + * Count matching documents using a JSON Path match query (`@?`; PostgreSQL only) + * + * @param string $tableName The name of the table in which documents should be counted + * @param string $path The JSON Path match string + * @return int The number of documents matching the given JSON Path criteria + * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs + */ + public static function byJsonPath(string $tableName, string $path): int + { + return Custom::scalar(Query\Count::byJsonPath($tableName), [':path' => $path], new CountMapper()); + } } diff --git a/src/Delete.php b/src/Delete.php index 22b84c8..d325724 100644 --- a/src/Delete.php +++ b/src/Delete.php @@ -33,4 +33,28 @@ class Delete Custom::nonQuery(Query\Delete::byFields($tableName, $namedFields, $match), Parameters::addFields($namedFields, [])); } + + /** + * 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 + * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs + */ + public static function byContains(string $tableName, array|object $criteria): void + { + Custom::nonQuery(Query\Delete::byContains($tableName), Parameters::json(':criteria', $criteria)); + } + + /** + * Delete documents matching a JSON Path match query (`@?`; PostgreSQL only) + * + * @param string $tableName The table from which documents should be deleted + * @param string $path The JSON Path match string + * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs + */ + public static function byJsonPath(string $tableName, string $path): void + { + Custom::nonQuery(Query\Delete::byJsonPath($tableName), [':path' => $path]); + } } diff --git a/src/Exists.php b/src/Exists.php index c668107..74142bc 100644 --- a/src/Exists.php +++ b/src/Exists.php @@ -37,4 +37,31 @@ class Exists return Custom::scalar(Query\Exists::byFields($tableName, $namedFields, $match), Parameters::addFields($namedFields, []), new ExistsMapper()); } + + /** + * 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 + * @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 + */ + public static function byContains(string $tableName, array|object $criteria): bool + { + return Custom::scalar(Query\Exists::byContains($tableName), Parameters::json(':criteria', $criteria), + new ExistsMapper()); + } + + /** + * Determine if documents exist by a JSON Path match query (`@?`; PostgreSQL only) + * + * @param string $tableName The name of the table in which document existence should be determined + * @param string $path The JSON Path match string + * @return bool True if any documents match the JSON Path string, false if not + * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs + */ + public static function byJsonPath(string $tableName, string $path): bool + { + return Custom::scalar(Query\Exists::byJsonPath($tableName), [':path' => $path], new ExistsMapper()); + } } diff --git a/src/Find.php b/src/Find.php index d6022f1..055868b 100644 --- a/src/Find.php +++ b/src/Find.php @@ -58,6 +58,37 @@ class Find Parameters::addFields($namedFields, []), new DocumentMapper($className)); } + /** + * Retrieve documents via a JSON containment query (`@>`; PostgreSQL only) + * + * @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 class-string $className The name of the class to be retrieved + * @return DocumentList A list of documents matching the JSON containment query + * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs + */ + public static function byContains(string $tableName, array|object $criteria, string $className): DocumentList + { + return Custom::list(Query\Find::byContains($tableName), Parameters::json(':criteria', $criteria), + new DocumentMapper($className)); + } + + /** + * Retrieve documents via a JSON Path match query (`@?`; PostgreSQL only) + * + * @template TDoc The type of document to be retrieved + * @param string $tableName The name of the table from which documents should be retrieved + * @param string $path The JSON Path match string + * @param class-string $className The name of the class to be retrieved + * @return DocumentList A list of documents matching the JSON Path + * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs + */ + public static function byJsonPath(string $tableName, string $path, string $className): DocumentList + { + return Custom::list(Query\Find::byJsonPath($tableName), [':path' => $path], new DocumentMapper($className)); + } + /** * Retrieve documents via a comparison on JSON fields, returning only the first result * @@ -76,4 +107,35 @@ class Find return Custom::single(Query\Find::byFields($tableName, $namedFields, $match), Parameters::addFields($namedFields, []), new DocumentMapper($className)); } + + /** + * Retrieve documents via a JSON containment query (`@>`), returning only the first result (PostgreSQL only) + * + * @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 class-string $className The name of the class to be retrieved + * @return false|TDoc The first document matching the JSON containment query if any is found, false otherwise + * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs + */ + public static function firstByContains(string $tableName, array|object $criteria, string $className): mixed + { + return Custom::single(Query\Find::byContains($tableName), Parameters::json(':criteria', $criteria), + new DocumentMapper($className)); + } + + /** + * Retrieve documents via a JSON Path match query (`@?`), returning only the first result (PostgreSQL only) + * + * @template TDoc The type of document to be retrieved + * @param string $tableName The name of the table from which documents should be retrieved + * @param string $path The JSON Path match string + * @param class-string $className The name of the class to be retrieved + * @return false|TDoc The first document matching the JSON Path if any is found, false otherwise + * @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs + */ + public static function firstByJsonPath(string $tableName, string $path, string $className): mixed + { + return Custom::single(Query\Find::byJsonPath($tableName), [':path' => $path], new DocumentMapper($className)); + } } diff --git a/src/Patch.php b/src/Patch.php index 038d9cd..f8e2737 100644 --- a/src/Patch.php +++ b/src/Patch.php @@ -37,4 +37,32 @@ class Patch Custom::nonQuery(Query\Patch::byFields($tableName, $namedFields, $match), Parameters::addFields($namedFields, Parameters::json(':data', $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 array|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 + { + Custom::nonQuery(Query\Patch::byContains($tableName), + array_merge(Parameters::json(':criteria', $criteria), Parameters::json(':data', $patch))); + } + + /** + * Patch documents using a JSON Path match query (`@?`; PostgreSQL only) + * + * @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) + * @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 + { + Custom::nonQuery(Query\Patch::byJsonPath($tableName), + array_merge([':path' => $path], Parameters::json(':data', $patch))); + } } diff --git a/src/Query.php b/src/Query.php index 51ed2e4..82f6824 100644 --- a/src/Query.php +++ b/src/Query.php @@ -75,7 +75,7 @@ class Query if (Configuration::$mode <> Mode::PgSQL) { throw new DocumentException('JSON Path matching is only supported on PostgreSQL'); } - return "data @? $paramName::jsonpath"; + return "jsonb_path_exists(data, $paramName::jsonpath)"; } /** diff --git a/src/RemoveFields.php b/src/RemoveFields.php index 792468b..1885bfe 100644 --- a/src/RemoveFields.php +++ b/src/RemoveFields.php @@ -39,4 +39,34 @@ class RemoveFields Custom::nonQuery(Query\RemoveFields::byFields($tableName, $namedFields, $nameParams, $match), Parameters::addFields($namedFields, $nameParams)); } + + /** + * 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 array|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 + { + $nameParams = Parameters::fieldNames(':name', $fieldNames); + Custom::nonQuery(Query\RemoveFields::byContains($tableName, $nameParams), + array_merge(Parameters::json(':criteria', $criteria), $nameParams)); + } + + /** + * Remove fields from documents via a JSON Path match query (`@?`; PostgreSQL only) + * + * @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 + * @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 + { + $nameParams = Parameters::fieldNames(':name', $fieldNames); + Custom::nonQuery(Query\RemoveFields::byJsonPath($tableName, $nameParams), + array_merge([':path' => $path], $nameParams)); + } } diff --git a/tests/integration/postgresql/CountTest.php b/tests/integration/postgresql/CountTest.php index 7403013..dbdb6ae 100644 --- a/tests/integration/postgresql/CountTest.php +++ b/tests/integration/postgresql/CountTest.php @@ -44,4 +44,30 @@ class CountTest extends TestCase $count = Count::byFields(ThrowawayDb::TABLE, [Field::BT('value', 'aardvark', 'apple')]); $this->assertEquals(1, $count, 'There should have been 1 matching document'); } + + public function testByContainsSucceedsWhenDocumentsMatch(): void + { + $this->assertEquals(2, Count::byContains(ThrowawayDb::TABLE, ['value' => 'purple']), + 'There should have been 2 matching documents'); + } + + public function testByContainsSucceedsWhenNoDocumentsMatch(): void + { + $this->assertEquals(0, Count::byContains(ThrowawayDb::TABLE, ['value' => 'magenta']), + 'There should have been no matching documents'); + } + + #[TestDox('By JSON Path succeeds when documents match')] + public function testByJsonPathSucceedsWhenDocumentsMatch(): void + { + $this->assertEquals(2, Count::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ < 5)'), + 'There should have been 2 matching documents'); + } + + #[TestDox('By JSON Path succeeds when no documents match')] + public function testByJsonPathSucceedsWhenNoDocumentsMatch(): void + { + $this->assertEquals(0, Count::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 100)'), + 'There should have been no matching documents'); + } } diff --git a/tests/integration/postgresql/DeleteTest.php b/tests/integration/postgresql/DeleteTest.php index 2c85011..cac03cc 100644 --- a/tests/integration/postgresql/DeleteTest.php +++ b/tests/integration/postgresql/DeleteTest.php @@ -56,4 +56,34 @@ class DeleteTest extends TestCase Delete::byFields(ThrowawayDb::TABLE, [Field::EQ('value', 'crimson')]); $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents remaining'); } + + public function testByContainsSucceedsWhenDocumentsAreDeleted(): void + { + $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start'); + Delete::byContains(ThrowawayDb::TABLE, ['value' => 'purple']); + $this->assertEquals(3, Count::all(ThrowawayDb::TABLE), 'There should have been 3 documents remaining'); + } + + public function testByContainsSucceedsWhenDocumentsAreNotDeleted(): void + { + $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start'); + Delete::byContains(ThrowawayDb::TABLE, ['target' => 'acquired']); + $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents remaining'); + } + + #[TestDox('By JSON Path succeeds when documents are deleted')] + public function testByJsonPathSucceedsWhenDocumentsAreDeleted(): void + { + $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start'); + Delete::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ <> 0)'); + $this->assertEquals(1, Count::all(ThrowawayDb::TABLE), 'There should have been 1 document remaining'); + } + + #[TestDox('By JSON Path succeeds when documents are not deleted')] + public function testByJsonPathSucceedsWhenDocumentsAreNotDeleted(): void + { + $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents to start'); + Delete::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ < 0)'); + $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents remaining'); + } } diff --git a/tests/integration/postgresql/ExistsTest.php b/tests/integration/postgresql/ExistsTest.php index cc7509c..ef67b34 100644 --- a/tests/integration/postgresql/ExistsTest.php +++ b/tests/integration/postgresql/ExistsTest.php @@ -51,4 +51,30 @@ class ExistsTest extends TestCase $this->assertFalse(Exists::byFields(ThrowawayDb::TABLE, [Field::LT('nothing', 'none')]), 'There should not have been any existing documents'); } + + public function testByContainsSucceedsWhenDocumentsExist(): void + { + $this->assertTrue(Exists::byContains(ThrowawayDb::TABLE, ['value' => 'purple']), + 'There should have been existing documents'); + } + + public function testByContainsSucceedsWhenNoMatchingDocumentsExist(): void + { + $this->assertFalse(Exists::byContains(ThrowawayDb::TABLE, ['value' => 'violet']), + 'There should not have been existing documents'); + } + + #[TestDox('By JSON Path succeeds when documents exist')] + public function testByJsonPathSucceedsWhenDocumentsExist(): void + { + $this->assertTrue(Exists::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ == 10)'), + 'There should have been existing documents'); + } + + #[TestDox('By JSON Path succeeds when no matching documents exist')] + public function testByJsonPathSucceedsWhenNoMatchingDocumentsExist(): void + { + $this->assertFalse(Exists::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ == 10.1)'), + 'There should have been existing documents'); + } } diff --git a/tests/integration/postgresql/FindTest.php b/tests/integration/postgresql/FindTest.php index 4649911..3895d31 100644 --- a/tests/integration/postgresql/FindTest.php +++ b/tests/integration/postgresql/FindTest.php @@ -86,6 +86,40 @@ class FindTest extends TestCase $this->assertFalse($docs->hasItems(), 'There should have been no documents in the list'); } + public function testByContainsSucceedsWhenDocumentsAreFound(): void + { + $docs = Find::byContains(ThrowawayDb::TABLE, ['value' => 'purple'], TestDocument::class); + $this->assertNotNull($docs, 'There should have been a document list returned'); + $count = 0; + foreach ($docs->items() as $ignored) $count++; + $this->assertEquals(2, $count, 'There should have been 2 documents in the list'); + } + + public function testByContainsSucceedsWhenNoDocumentsAreFound(): void + { + $docs = Find::byContains(ThrowawayDb::TABLE, ['value' => 'indigo'], TestDocument::class); + $this->assertNotNull($docs, 'There should have been a document list returned'); + $this->assertFalse($docs->hasItems(), 'The document list should be empty'); + } + + #[TestDox('By JSON Path succeeds when documents are found')] + public function testByJsonPathSucceedsWhenDocumentsAreFound(): void + { + $docs = Find::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', TestDocument::class); + $this->assertNotNull($docs, 'There should have been a document list returned'); + $count = 0; + foreach ($docs->items() as $ignored) $count++; + $this->assertEquals(2, $count, 'There should have been 2 documents in the list'); + } + + #[TestDox('By JSON Path succeeds when no documents are found')] + public function testByJsonPathSucceedsWhenNoDocumentsAreFound(): void + { + $docs = Find::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 100)', TestDocument::class); + $this->assertNotNull($docs, 'There should have been a document list returned'); + $this->assertFalse($docs->hasItems(), 'The document list should be empty'); + } + public function testFirstByFieldsSucceedsWhenADocumentIsFound(): void { $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'another')], TestDocument::class); @@ -105,4 +139,46 @@ class FindTest extends TestCase $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'absent')], TestDocument::class); $this->assertFalse($doc, 'There should not have been a document returned'); } + + public function testFirstByContainsSucceedsWhenADocumentIsFound(): void + { + $doc = Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'FIRST!'], TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals('one', $doc->id, 'The incorrect document was returned'); + } + + public function testFirstByContainsSucceedsWhenMultipleDocumentsAreFound(): void + { + $doc = Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'purple'], TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertContains($doc->id, ['four', 'five'], 'An incorrect document was returned'); + } + + public function testFirstByContainsSucceedsWhenADocumentIsNotFound(): void + { + $doc = Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'indigo'], TestDocument::class); + $this->assertFalse($doc, 'There should not have been a document returned'); + } + + #[TestDox('First by JSON Path succeeds when a document is found')] + public function testFirstByJsonPathSucceedsWhenADocumentIsFound(): void + { + $doc = Find::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ == 10)', TestDocument::class); + $this->assertEquals('two', $doc->id, 'The incorrect document was returned'); + } + + #[TestDox('First by JSON Path succeeds when multiple documents are found')] + public function testFirstByJsonPathSucceedsWhenMultipleDocumentsAreFound(): void + { + $doc = Find::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertContains($doc->id, ['four', 'five'], 'An incorrect document was returned'); + } + + #[TestDox('First by JSON Path succeeds when a document is not found')] + public function testFirstByJsonPathSucceedsWhenADocumentIsNotFound(): void + { + $doc = Find::firstByJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 100)', TestDocument::class); + $this->assertFalse($doc, 'There should not have been a document returned'); + } } diff --git a/tests/integration/postgresql/PatchTest.php b/tests/integration/postgresql/PatchTest.php index 1b58aa8..e8bfad1 100644 --- a/tests/integration/postgresql/PatchTest.php +++ b/tests/integration/postgresql/PatchTest.php @@ -2,7 +2,7 @@ namespace Test\Integration\PostgreSQL; -use BitBadger\PDODocument\{Count, Field, Find, Patch}; +use BitBadger\PDODocument\{Count, Exists, Field, Find, Patch}; use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; use Test\Integration\TestDocument; @@ -40,7 +40,9 @@ class PatchTest extends TestCase #[TestDox('By ID succeeds when no document is updated')] public function testByIdSucceedsWhenNoDocumentIsUpdated(): void { - Patch::byId(ThrowawayDb::TABLE, 'forty-seven', ['foo' => 'green']); + $id = 'forty-seven'; + $this->assertFalse(Exists::byId(ThrowawayDb::TABLE, $id), 'The document should not exist'); + Patch::byId(ThrowawayDb::TABLE, $id, ['foo' => 'green']); $this->assertTrue(true, 'The above not throwing an exception is the test'); } @@ -53,7 +55,50 @@ class PatchTest extends TestCase public function testByFieldsSucceedsWhenNoDocumentIsUpdated(): void { - Patch::byFields(ThrowawayDb::TABLE, [Field::EQ('value', 'burgundy')], ['foo' => 'green']); + $fields = [Field::EQ('value', 'burgundy')]; + $this->assertEquals(0, Count::byFields(ThrowawayDb::TABLE, $fields), 'There should be no matching documents'); + Patch::byFields(ThrowawayDb::TABLE, $fields, ['foo' => 'green']); + $this->assertTrue(true, 'The above not throwing an exception is the test'); + } + + public function testByContainsSucceedsWhenDocumentsAreUpdated(): void + { + Patch::byContains(ThrowawayDb::TABLE, ['value' => 'another'], ['num_value' => 12]); + $doc = Find::firstByContains(ThrowawayDb::TABLE, ['value' => 'another'], TestDocument::class); + $this->assertNotFalse($doc, 'There should have been a document returned'); + $this->assertEquals('two', $doc->id, 'An incorrect document was returned'); + $this->assertEquals(12, $doc->num_value, 'The document was not patched'); + } + + public function testByContainsSucceedsWhenNoDocumentsAreUpdated(): void + { + $criteria = ['value' => 'updated']; + $this->assertEquals(0, Count::byContains(ThrowawayDb::TABLE, $criteria), + 'There should be no matching documents'); + Patch::byContains(ThrowawayDb::TABLE, $criteria, ['sub.foo' => 'green']); + $this->assertTrue(true, 'The above not throwing an exception is the test'); + } + + #[TestDox('By JSON Path succeeds when documents are updated')] + public function testByJsonPathSucceedsWhenDocumentsAreUpdated(): void + { + Patch::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', ['value' => 'blue']); + $docs = Find::byJsonPath(ThrowawayDb::TABLE, '$.num_value ? (@ > 10)', TestDocument::class); + $this->assertNotNull($docs, 'There should have been a document list returned'); + $this->assertTrue($docs->hasItems(), 'The document list should not be empty'); + foreach ($docs->items() as $item) { + $this->assertContains($item->id, ['four', 'five'], 'An incorrect document was returned'); + $this->assertEquals('blue', $item->value, 'The document was not patched'); + } + } + + #[TestDox('By JSON Path succeeds when documents are not updated')] + public function testByJsonPathSucceedsWhenDocumentsAreNotUpdated(): void + { + $path = '$.num_value ? (@ > 100)'; + $this->assertEquals(0, Count::byJsonPath(ThrowawayDb::TABLE, $path), + 'There should be no documents matching this path'); + Patch::byJsonPath(ThrowawayDb::TABLE, $path, ['value' => 'blue']); $this->assertTrue(true, 'The above not throwing an exception is the test'); } } diff --git a/tests/integration/postgresql/RemoveFieldsTest.php b/tests/integration/postgresql/RemoveFieldsTest.php index 37c27e2..9015e7a 100644 --- a/tests/integration/postgresql/RemoveFieldsTest.php +++ b/tests/integration/postgresql/RemoveFieldsTest.php @@ -71,4 +71,57 @@ class RemoveFieldsTest extends TestCase RemoveFields::byFields(ThrowawayDb::TABLE, [Field::NE('missing', 'nope')], ['value']); $this->assertTrue(true, 'The above not throwing an exception is the test'); } + + public function testByContainsSucceedsWhenAFieldIsRemoved(): void + { + $criteria = ['sub' => ['foo' => 'green']]; + RemoveFields::byContains(ThrowawayDb::TABLE, $criteria, ['value']); + $docs = Find::byContains(ThrowawayDb::TABLE, $criteria, TestDocument::class); + $this->assertNotNull($docs, 'There should have been a document list returned'); + $this->assertTrue($docs->hasItems(), 'The document list should not have been empty'); + foreach ($docs->items() as $item) { + $this->assertContains($item->id, ['two', 'four'], 'An incorrect document was returned'); + $this->assertEquals('', $item->value, 'The value field was not removed'); + } + } + + public function testByContainsSucceedsWhenAFieldIsNotRemoved(): void + { + RemoveFields::byContains(ThrowawayDb::TABLE, ['sub' => ['foo' => 'green']], ['invalid_field']); + $this->assertTrue(true, 'The above not throwing an exception is the test'); + } + + public function testByContainsSucceedsWhenNoDocumentIsMatched(): void + { + RemoveFields::byContains(ThrowawayDb::TABLE, ['value' => 'substantial'], ['num_value']); + $this->assertTrue(true, 'The above not throwing an exception is the test'); + } + + #[TestDox('By JSON Path succeeds when a field is removed')] + public function testByJsonPathSucceedsWhenAFieldIsRemoved(): void + { + $path = '$.value ? (@ == "purple")'; + RemoveFields::byJsonPath(ThrowawayDb::TABLE, $path, ['sub']); + $docs = Find::byJsonPath(ThrowawayDb::TABLE, $path, TestDocument::class); + $this->assertNotNull($docs, 'There should have been a document list returned'); + $this->assertTrue($docs->hasItems(), 'The document list should not have been empty'); + foreach ($docs->items() as $item) { + $this->assertContains($item->id, ['four', 'five'], 'An incorrect document was returned'); + $this->assertNull($item->sub, 'The sub field was not removed'); + } + } + + #[TestDox('By JSON Path succeeds when a field is not removed')] + public function testByJsonPathSucceedsWhenAFieldIsNotRemoved(): void + { + RemoveFields::byJsonPath(ThrowawayDb::TABLE, '$.value ? (@ == "purple")', ['submarine']); + $this->assertTrue(true, 'The above not throwing an exception is the test'); + } + + #[TestDox('By JSON Path succeeds when no document is matched')] + public function testByJsonPathSucceedsWhenNoDocumentIsMatched(): void + { + RemoveFields::byJsonPath(ThrowawayDb::TABLE, '$.value ? (@ == "mauve")', ['value']); + $this->assertTrue(true, 'The above not throwing an exception is the test'); + } } diff --git a/tests/integration/sqlite/CountTest.php b/tests/integration/sqlite/CountTest.php index 259bf28..285d4d2 100644 --- a/tests/integration/sqlite/CountTest.php +++ b/tests/integration/sqlite/CountTest.php @@ -2,7 +2,7 @@ namespace Test\Integration\SQLite; -use BitBadger\PDODocument\{Count, Field}; +use BitBadger\PDODocument\{Count, DocumentException, Field}; use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; @@ -44,4 +44,17 @@ class CountTest extends TestCase $count = Count::byFields(ThrowawayDb::TABLE, [Field::BT('value', 'aardvark', 'apple')]); $this->assertEquals(1, $count, 'There should have been 1 matching document'); } + + public function testByContainsFails(): void + { + $this->expectException(DocumentException::class); + Count::byContains('', []); + } + + #[TestDox('By JSON Path fails')] + public function testByJsonPathFails(): void + { + $this->expectException(DocumentException::class); + Count::byJsonPath('', ''); + } } diff --git a/tests/integration/sqlite/DeleteTest.php b/tests/integration/sqlite/DeleteTest.php index 58a664a..e012d0b 100644 --- a/tests/integration/sqlite/DeleteTest.php +++ b/tests/integration/sqlite/DeleteTest.php @@ -2,7 +2,7 @@ namespace Test\Integration\SQLite; -use BitBadger\PDODocument\{Count, Delete, Field}; +use BitBadger\PDODocument\{Count, Delete, DocumentException, Field}; use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; @@ -56,4 +56,17 @@ class DeleteTest extends TestCase Delete::byFields(ThrowawayDb::TABLE, [Field::EQ('value', 'crimson')]); $this->assertEquals(5, Count::all(ThrowawayDb::TABLE), 'There should have been 5 documents remaining'); } + + public function testByContainsFails(): void + { + $this->expectException(DocumentException::class); + Delete::byContains('', []); + } + + #[TestDox('By JSON Path fails')] + public function testByJsonPathFails(): void + { + $this->expectException(DocumentException::class); + Delete::byJsonPath('', ''); + } } diff --git a/tests/integration/sqlite/ExistsTest.php b/tests/integration/sqlite/ExistsTest.php index 0454b10..e9966ff 100644 --- a/tests/integration/sqlite/ExistsTest.php +++ b/tests/integration/sqlite/ExistsTest.php @@ -2,7 +2,7 @@ namespace Test\Integration\SQLite; -use BitBadger\PDODocument\{Exists, Field}; +use BitBadger\PDODocument\{DocumentException, Exists, Field}; use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; @@ -51,4 +51,18 @@ class ExistsTest extends TestCase $this->assertFalse(Exists::byFields(ThrowawayDb::TABLE, [Field::LT('nothing', 'none')]), 'There should not have been any existing documents'); } + + public function testByContainsFails(): void + { + $this->expectException(DocumentException::class); + Exists::byContains('', []); + } + + #[TestDox('By JSON Path fails')] + public function testByJsonPathFails(): void + { + $this->expectException(DocumentException::class); + Exists::byJsonPath('', ''); + } } + diff --git a/tests/integration/sqlite/FindTest.php b/tests/integration/sqlite/FindTest.php index c134433..c1677a0 100644 --- a/tests/integration/sqlite/FindTest.php +++ b/tests/integration/sqlite/FindTest.php @@ -2,7 +2,7 @@ namespace Test\Integration\SQLite; -use BitBadger\PDODocument\{Custom, Document, Field, Find}; +use BitBadger\PDODocument\{Custom, Document, DocumentException, Field, Find}; use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; use Test\Integration\TestDocument; @@ -85,6 +85,19 @@ class FindTest extends TestCase $this->assertFalse($docs->hasItems(), 'There should have been no documents in the list'); } + public function testByContainsFails(): void + { + $this->expectException(DocumentException::class); + Find::byContains('', [], TestDocument::class); + } + + #[TestDox('By JSON Path fails')] + public function testByJsonPathFails(): void + { + $this->expectException(DocumentException::class); + Find::byJsonPath('', '', TestDocument::class); + } + public function testFirstByFieldsSucceedsWhenADocumentIsFound(): void { $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'another')], TestDocument::class); @@ -104,4 +117,17 @@ class FindTest extends TestCase $doc = Find::firstByFields(ThrowawayDb::TABLE, [Field::EQ('value', 'absent')], TestDocument::class); $this->assertFalse($doc, 'There should not have been a document returned'); } + + public function testFirstByContainsFails(): void + { + $this->expectException(DocumentException::class); + Find::firstByContains('', [], TestDocument::class); + } + + #[TestDox('First by JSON Path fails')] + public function testFirstByJsonPathFails(): void + { + $this->expectException(DocumentException::class); + Find::firstByJsonPath('', '', TestDocument::class); + } } diff --git a/tests/integration/sqlite/PatchTest.php b/tests/integration/sqlite/PatchTest.php index b366425..5598753 100644 --- a/tests/integration/sqlite/PatchTest.php +++ b/tests/integration/sqlite/PatchTest.php @@ -2,7 +2,7 @@ namespace Test\Integration\SQLite; -use BitBadger\PDODocument\{Count, Field, Find, Patch}; +use BitBadger\PDODocument\{Count, DocumentException, Field, Find, Patch}; use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; use Test\Integration\TestDocument; @@ -56,4 +56,17 @@ class PatchTest extends TestCase Patch::byFields(ThrowawayDb::TABLE, [Field::EQ('value', 'burgundy')], ['foo' => 'green']); $this->assertTrue(true, 'The above not throwing an exception is the test'); } + + public function testByContainsFails(): void + { + $this->expectException(DocumentException::class); + Patch::byContains('', [], []); + } + + #[TestDox('By JSON Path fails')] + public function testByJsonPathFails(): void + { + $this->expectException(DocumentException::class); + Patch::byJsonPath('', '', []); + } } diff --git a/tests/integration/sqlite/RemoveFieldsTest.php b/tests/integration/sqlite/RemoveFieldsTest.php index e1b3cf1..d656ded 100644 --- a/tests/integration/sqlite/RemoveFieldsTest.php +++ b/tests/integration/sqlite/RemoveFieldsTest.php @@ -2,7 +2,7 @@ namespace Test\Integration\SQLite; -use BitBadger\PDODocument\{Field, Find, RemoveFields}; +use BitBadger\PDODocument\{DocumentException, Field, Find, RemoveFields}; use PHPUnit\Framework\Attributes\TestDox; use PHPUnit\Framework\TestCase; use Test\Integration\TestDocument; @@ -71,4 +71,17 @@ class RemoveFieldsTest extends TestCase RemoveFields::byFields(ThrowawayDb::TABLE, [Field::NE('missing', 'nope')], ['value']); $this->assertTrue(true, 'The above not throwing an exception is the test'); } + + public function testByContainsFails(): void + { + $this->expectException(DocumentException::class); + RemoveFields::byContains('', [], []); + } + + #[TestDox('By JSON Path fails')] + public function testByJsonPathFails(): void + { + $this->expectException(DocumentException::class); + RemoveFields::byJsonPath('', '', []); + } } diff --git a/tests/unit/Query/CountTest.php b/tests/unit/Query/CountTest.php index 58d9ac0..8917cea 100644 --- a/tests/unit/Query/CountTest.php +++ b/tests/unit/Query/CountTest.php @@ -37,7 +37,7 @@ class CountTest extends TestCase public function testByContainsSucceedsForPostgreSQL(): void { Configuration::$mode = Mode::PgSQL; - $this->assertEquals("SELECT COUNT(*) FROM the_table WHERE data @> :criteria", Count::byContains('the_table'), + $this->assertEquals('SELECT COUNT(*) FROM the_table WHERE data @> :criteria', Count::byContains('the_table'), 'SELECT statement not generated correctly'); } @@ -52,8 +52,8 @@ class CountTest extends TestCase public function testByJsonPathSucceedsForPostgreSQL(): void { Configuration::$mode = Mode::PgSQL; - $this->assertEquals("SELECT COUNT(*) FROM a_table WHERE data @? :path::jsonpath", Count::byJsonPath('a_table'), - 'SELECT statement not generated correctly'); + $this->assertEquals('SELECT COUNT(*) FROM a_table WHERE jsonb_path_exists(data, :path::jsonpath)', + Count::byJsonPath('a_table'), 'SELECT statement not generated correctly'); } #[TestDox('By JSON Path fails for non PostgreSQL')] diff --git a/tests/unit/Query/DeleteTest.php b/tests/unit/Query/DeleteTest.php index 9efe38b..7206e3f 100644 --- a/tests/unit/Query/DeleteTest.php +++ b/tests/unit/Query/DeleteTest.php @@ -53,8 +53,8 @@ class DeleteTest extends TestCase public function testByJsonPathSucceedsForPostgreSQL(): void { Configuration::$mode = Mode::PgSQL; - $this->assertEquals('DELETE FROM here WHERE data @? :path::jsonpath', Delete::byJsonPath('here'), - 'DELETE statement not constructed correctly'); + $this->assertEquals('DELETE FROM here WHERE jsonb_path_exists(data, :path::jsonpath)', + Delete::byJsonPath('here'), 'DELETE statement not constructed correctly'); } #[TestDox('By JSON Path fails for non PostgreSQL')] diff --git a/tests/unit/Query/ExistsTest.php b/tests/unit/Query/ExistsTest.php index ba77418..053e340 100644 --- a/tests/unit/Query/ExistsTest.php +++ b/tests/unit/Query/ExistsTest.php @@ -60,7 +60,7 @@ class ExistsTest extends TestCase public function testByJsonPathSucceedsForPostgreSQL(): void { Configuration::$mode = Mode::PgSQL; - $this->assertEquals('SELECT EXISTS (SELECT 1 FROM lint WHERE data @? :path::jsonpath)', + $this->assertEquals('SELECT EXISTS (SELECT 1 FROM lint WHERE jsonb_path_exists(data, :path::jsonpath))', Exists::byJsonPath('lint'), 'Existence query not generated correctly'); } diff --git a/tests/unit/Query/FindTest.php b/tests/unit/Query/FindTest.php index 2a98d82..36677f2 100644 --- a/tests/unit/Query/FindTest.php +++ b/tests/unit/Query/FindTest.php @@ -54,8 +54,8 @@ class FindTest extends TestCase public function testByJsonPathSucceedsForPostgreSQL(): void { Configuration::$mode = Mode::PgSQL; - $this->assertEquals('SELECT data FROM light WHERE data @? :path::jsonpath', Find::byJsonPath('light'), - 'SELECT query not generated correctly'); + $this->assertEquals('SELECT data FROM light WHERE jsonb_path_exists(data, :path::jsonpath)', + Find::byJsonPath('light'), 'SELECT query not generated correctly'); } #[TestDox('By JSON Path fails for non PostgreSQL')] diff --git a/tests/unit/Query/PatchTest.php b/tests/unit/Query/PatchTest.php index bf5e05e..8382730 100644 --- a/tests/unit/Query/PatchTest.php +++ b/tests/unit/Query/PatchTest.php @@ -83,7 +83,7 @@ class PatchTest extends TestCase public function testByJsonPathSucceedsForPostgreSQL(): void { Configuration::$mode = Mode::PgSQL; - $this->assertEquals('UPDATE that SET data = data || :data WHERE data @? :path::jsonpath', + $this->assertEquals('UPDATE that SET data = data || :data WHERE jsonb_path_exists(data, :path::jsonpath)', Patch::byJsonPath('that'), 'Patch UPDATE statement is not correct'); } diff --git a/tests/unit/Query/RemoveFieldsTest.php b/tests/unit/Query/RemoveFieldsTest.php index 7d5dfac..c3b71a5 100644 --- a/tests/unit/Query/RemoveFieldsTest.php +++ b/tests/unit/Query/RemoveFieldsTest.php @@ -112,7 +112,8 @@ class RemoveFieldsTest extends TestCase public function testByJsonPathSucceedsForPostgreSQL(): void { Configuration::$mode = Mode::PgSQL; - $this->assertEquals('UPDATE dessert SET data = data - :cake::text[] WHERE data @? :path::jsonpath', + $this->assertEquals( + 'UPDATE dessert SET data = data - :cake::text[] WHERE jsonb_path_exists(data, :path::jsonpath)', RemoveFields::byJsonPath('dessert', Parameters::fieldNames(':cake', ['b', 'c'])), 'UPDATE statement not correct'); } diff --git a/tests/unit/QueryTest.php b/tests/unit/QueryTest.php index 3c0c945..623e7d7 100644 --- a/tests/unit/QueryTest.php +++ b/tests/unit/QueryTest.php @@ -96,7 +96,7 @@ class QueryTest extends TestCase { Configuration::$mode = Mode::PgSQL; try { - $this->assertEquals('data @? :path::jsonpath', Query::whereJsonPathMatches(), + $this->assertEquals('jsonb_path_exists(data, :path::jsonpath)', Query::whereJsonPathMatches(), 'WHERE fragment not constructed correctly'); } finally { Configuration::$mode = null; @@ -108,7 +108,7 @@ class QueryTest extends TestCase { Configuration::$mode = Mode::PgSQL; try { - $this->assertEquals('data @? :road::jsonpath', Query::whereJsonPathMatches(':road'), + $this->assertEquals('jsonb_path_exists(data, :road::jsonpath)', Query::whereJsonPathMatches(':road'), 'WHERE fragment not constructed correctly'); } finally { Configuration::$mode = null; -- 2.45.1 From e5db95fe9df1cc0e547320e3d319ca8cfbd8e89e Mon Sep 17 00:00:00 2001 From: "Daniel J. Summers" Date: Fri, 21 Jun 2024 09:44:50 -0400 Subject: [PATCH 4/4] Add PostgreSQL verbiage --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index eba1cf7..650cb41 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # PDODocument -This library allows SQLite (and, by v1.0.0-beta1, PostgreSQL) to be treated as a document database. It is a PHP implementation of the .NET [BitBadger.Documents](https://git.bitbadger.solutions/bit-badger/BitBadger.Documents) library. +This library allows SQLite and PostgreSQL to be treated as document databases. It is a PHP implementation of the .NET [BitBadger.Documents](https://git.bitbadger.solutions/bit-badger/BitBadger.Documents) library. ## Add via Composer @@ -29,4 +29,4 @@ In all generated scenarios, if the ID value is not 0 or blank, that ID will be u ## Usage -Documentation for this library is not complete; however, its structure is very similar to the .NET version, so [its documentation will help](https://bitbadger.solutions/open-source/relational-documents/basic-usage.html) until its project specific documentation is developed. Things like `Count.All()` become `Count::all`, and all the `byField` operations are named `byFields` and take an array of fields. +Documentation for this library is not complete (writing it is one of the goals before the “beta” tag is dropped); however, its structure is very similar to the .NET version, so [its documentation will help](https://bitbadger.solutions/open-source/relational-documents/basic-usage.html) until its project specific documentation is developed. Things like `Count.All()` become `Count::all`, and all the `byField` operations are named `byFields` and take an array of fields. -- 2.45.1