bit-badger/pdo-document
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 16 Wiki Activity

alpha2 (#2)

Browse Source 
- Change multiple field matching to enum
- Implement auto-generated IDs

Reviewed-on: #2
This commit is contained in:
Daniel J. Summers 2024-06-11 11:07:56 +00:00
parent 1f1f06679f
commit 330e272187
26 changed files with 617 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
README.md
View File

@ -8,6 +8,25 @@ This library allows SQLite (and, by v1.0.0-beta1, PostgreSQL) to be treated as a
`composer require bit-badger/pdo-document`
## Configuration
### Connection Details
The static variable `Configuration::$pdoDSN` must be set to the [PDO data source name](https://www.php.net/manual/en/pdo.construct.php#refsect1-pdo.construct-parameters) for your database. `Configuration` also has `$username`, `$password`, and `$options` variables that will be used to construct the PDO object it will use for data access.
### Document Identifiers
Each document must have a unique identifier. By default, the library assumes that this is a property or array key named `id`, but this can be controlled by setting `Configuration::$idField`. Once documents exist, this should not be changed.
IDs can be generated automatically on insert. The `AutoId` enumeration has 4 values:
- `AutoId::None` is the default; no IDs will be generated
- `AutoId::Number` will assign max-ID-plus-one to documents with an ID of 0
- `AutoId::UUID` will generate a v4 <abbr title="Universally Unique Identifier">UUID</abbr> for documents with an empty `string` ID
- `AutoId::RandomString` will generate a string of letters and numbers for documents with an empty `string` ID; `Configuration::$idStringLength` controls the length of the generated string, and defaults to 16 characters
In all generated scenarios, if the ID value is not 0 or blank, that ID will be used instead of a generated one.
## 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.

2
composer.json
View File

@ -17,7 +17,7 @@
"rss": "https://git.bitbadger.solutions/bit-badger/pdo-document.rss"
},
"require": {
"php": ">=8.3",
"php": ">=8.2",
"netresearch/jsonmapper": "^4",
"ext-pdo": "*"
},

4
composer.lock generated
View File

@ -4,7 +4,7 @@
"Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
"This file is @generated automatically"
],
"content-hash": "ca79f450e8e715ad61ba3581734c0fe7",
"content-hash": "20bf0d96304e429b431535d05ff4585a",
"packages": [
{
"name": "netresearch/jsonmapper",
@ -1697,7 +1697,7 @@
"prefer-stable": false,
"prefer-lowest": false,
"platform": {
"php": ">=8.3",
"php": ">=8.2",
"ext-pdo": "*"
},
"platform-dev": [],

51
src/AutoId.php Normal file
View File

@ -0,0 +1,51 @@
<?php declare(strict_types=1);
namespace BitBadger\PDODocument;
use Random\RandomException;
/**
* How automatic ID generation should be performed
*/
enum AutoId
{
/** Do not automatically generate IDs */
case None;
/** New documents with a 0 ID should receive max ID plus one */
case Number;
/** New documents with a blank ID should receive a v4 UUID (Universally Unique Identifier) */
case UUID;
/** New documents with a blank ID should receive a random string (set `Configuration::$idStringLength`) */
case RandomString;
/**
* Generate a v4 UUID
*
* @return string The v4 UUID
* @throws RandomException If an appropriate source of randomness cannot be found
*/
public static function generateUUID(): string
{
// hat tip: https://stackoverflow.com/a/15875555/276707
$bytes = random_bytes(16);
$bytes[6] = chr(ord($bytes[6]) & 0x0f | 0x40); // set version to 0100
$bytes[8] = chr(ord($bytes[8]) & 0x3f | 0x80); // set bits 6-7 to 10
return vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($bytes), 4));
}
/**
* Generate a random string ID
*
* @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
{
return bin2hex(random_bytes(Configuration::$idStringLength / 2));
}
}

12
src/Configuration.php
View File

@ -12,6 +12,14 @@ class Configuration
/** @var string The name of the ID field used in the database (will be treated as the primary key) */
public static string $idField = 'id';
/** @var AutoId The automatic ID generation process to use */
public static AutoId $autoId = AutoId::None;
/**
* @var int The number of characters a string generated by `AutoId::RandomString` will have (must be an even number)
*/
public static int $idStringLength = 16;
/** @var string The data source name (DSN) of the connection string */
public static string $pdoDSN = '';
@ -59,7 +67,9 @@ class Configuration
return self::$_pdo;
}
/**
* Clear the current PDO instance
*/
public static function resetPDO(): void
{
self::$_pdo = null;

6
src/Count.php
View File

@ -26,14 +26,14 @@ class Count
*
* @param string $tableName The name of the table in which documents should be counted
* @param array|Field[] $fields The field comparison to match
* @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @return int The count of documents matching the field comparison
* @throws DocumentException If one is encountered
*/
public static function byFields(string $tableName, array $fields, string $conjunction = 'AND'): int
public static function byFields(string $tableName, array $fields, ?FieldMatch $match = null): int
{
$namedFields = Parameters::nameFields($fields);
return Custom::scalar(Query\Count::byFields($tableName, $namedFields, $conjunction),
return Custom::scalar(Query\Count::byFields($tableName, $namedFields, $match),
Parameters::addFields($namedFields, []), new CountMapper());
}
}

6
src/Delete.php
View File

@ -24,13 +24,13 @@ class Delete
*
* @param string $tableName The table from which documents should be deleted
* @param array|Field[] $fields The field comparison to match
* @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @throws DocumentException If any is encountered
*/
public static function byFields(string $tableName, array $fields, string $conjunction = 'AND'): void
public static function byFields(string $tableName, array $fields, ?FieldMatch $match = null): void
{
$namedFields = Parameters::nameFields($fields);
Custom::nonQuery(Query\Delete::byFields($tableName, $namedFields, $conjunction),
Custom::nonQuery(Query\Delete::byFields($tableName, $namedFields, $match),
Parameters::addFields($namedFields, []));
}
}

20
src/Document.php
View File

@ -16,7 +16,25 @@ class Document
*/
public static function insert(string $tableName, array|object $document): void
{
Custom::nonQuery(Query::insert($tableName), Parameters::json(':data', $document));
$doInsert = fn() => Custom::nonQuery(Query::insert($tableName), Parameters::json(':data', $document));
if (Configuration::$autoId == AutoId::None) {
$doInsert();
return;
}
$id = Configuration::$idField;
$idProvided =
(is_array( $document) && is_int( $document[$id]) && $document[$id] <> 0)
|| (is_array( $document) && is_string($document[$id]) && $document[$id] <> '')
|| (is_object($document) && is_int( $document->{$id}) && $document->{$id} <> 0)
|| (is_object($document) && is_string($document->{$id}) && $document->{$id} <> '');
if ($idProvided) {
$doInsert();
} else {
Custom::nonQuery(Query::insert($tableName, Configuration::$autoId), Parameters::json(':data', $document));
}
}
/**

6
src/Exists.php
View File

@ -27,14 +27,14 @@ class Exists
*
* @param string $tableName The name of the table in which document existence should be determined
* @param Field[] $fields The field comparison to match
* @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @return bool True if any documents match the field comparison, false if not
* @throws DocumentException If any is encountered
*/
public static function byFields(string $tableName, array $fields, string $conjunction = 'AND'): bool
public static function byFields(string $tableName, array $fields, ?FieldMatch $match = null): bool
{
$namedFields = Parameters::nameFields($fields);
return Custom::scalar(Query\Exists::byFields($tableName, $namedFields, $conjunction),
return Custom::scalar(Query\Exists::byFields($tableName, $namedFields, $match),
Parameters::addFields($namedFields, []), new ExistsMapper());
}
}

28
src/FieldMatch.php Normal file
View File

@ -0,0 +1,28 @@
<?php declare(strict_types=1);
namespace BitBadger\PDODocument;
/**
* How multiple fields should be matched
*/
enum FieldMatch
{
/** Match all provided fields (`AND`) */
case All;
/** Match any provided fields (`OR`) */
case Any;
/**
* Get the SQL keyword for this enumeration value
*
* @return string The SQL keyword for this enumeration value
*/
public function toString(): string
{
return match ($this) {
FieldMatch::All => 'AND',
FieldMatch::Any => 'OR'
};
}
}

12
src/Find.php
View File

@ -45,15 +45,15 @@ class Find
* @param string $tableName The table from which documents should be retrieved
* @param array|Field[] $fields The field comparison to match
* @param class-string<TDoc> $className The name of the class to be retrieved
* @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @return DocumentList<TDoc> A list of documents matching the given field comparison
* @throws DocumentException If any is encountered
*/
public static function byFields(string $tableName, array $fields, string $className,
string $conjunction = 'AND'): DocumentList
?FieldMatch $match = null): DocumentList
{
$namedFields = Parameters::nameFields($fields);
return Custom::list(Query\Find::byFields($tableName, $namedFields, $conjunction),
return Custom::list(Query\Find::byFields($tableName, $namedFields, $match),
Parameters::addFields($namedFields, []), new DocumentMapper($className));
}
@ -64,15 +64,15 @@ class Find
* @param string $tableName The table from which the document should be retrieved
* @param array|Field[] $fields The field comparison to match
* @param class-string<TDoc> $className The name of the class to be retrieved
* @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @return false|TDoc The first document if any matches are found, false otherwise
* @throws DocumentException If any is encountered
*/
public static function firstByFields(string $tableName, array $fields, string $className,
string $conjunction = 'AND'): mixed
?FieldMatch $match = null): mixed
{
$namedFields = Parameters::nameFields($fields);
return Custom::single(Query\Find::byFields($tableName, $namedFields, $conjunction),
return Custom::single(Query\Find::byFields($tableName, $namedFields, $match),
Parameters::addFields($namedFields, []), new DocumentMapper($className));
}
}

6
src/Patch.php
View File

@ -27,14 +27,14 @@ class Patch
* @param string $tableName The table in which documents should be patched
* @param array|Field[] $fields The field comparison to match
* @param array|object $patch The object with which the documents should be patched (will be JSON-encoded)
* @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @throws DocumentException If any is encountered
*/
public static function byFields(string $tableName, array $fields, array|object $patch,
string $conjunction = 'AND'): void
?FieldMatch $match = null): void
{
$namedFields = Parameters::nameFields($fields);
Custom::nonQuery(Query\Patch::byFields($tableName, $namedFields, $conjunction),
Custom::nonQuery(Query\Patch::byFields($tableName, $namedFields, $match),
Parameters::addFields($namedFields, Parameters::json(':data', $patch)));
}
}

51
src/Query.php
View File

@ -2,6 +2,8 @@
namespace BitBadger\PDODocument;
use Random\RandomException;
/**
* Query construction functions
*/
@ -22,12 +24,14 @@ class Query
* Create a WHERE clause fragment to implement a comparison on fields in a JSON document
*
* @param Field[] $fields The field comparison to generate
* @param string $conjunction How to join multiple conditions (optional; defaults to AND)
* @param FieldMatch|null $match How to join multiple conditions (optional; defaults to All)
* @return string The WHERE clause fragment matching the given fields and parameter
* @throws DocumentException If the database mode has not been set
*/
public static function whereByFields(array $fields, string $conjunction = 'AND'): string
public static function whereByFields(array $fields, ?FieldMatch $match = null): string
{
return implode(" $conjunction ", array_map(fn($it) => $it->toWhere(), $fields));
return implode(' ' . ($match ?? FieldMatch::All)->toString() . ' ',
array_map(fn($it) => $it->toWhere(), $fields));
}
/**
@ -35,6 +39,7 @@ class Query
*
* @param string $paramName The parameter name where the value of the ID will be provided (optional; default @id)
* @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
{
@ -42,14 +47,39 @@ class Query
}
/**
* Query to insert a document
* Create an `INSERT` statement for a document
*
* @param string $tableName The name of the table into which a document should be inserted
* @return string The INSERT statement for the given table
* @param string $tableName The name of the table into which the document will be inserted
* @param AutoId|null $autoId The version of automatic ID query to generate (optional, defaults to None)
* @return string The `INSERT` statement to insert a document
* @throws DocumentException If the database mode is not set
*/
public static function insert(string $tableName): string
public static function insert(string $tableName, ?AutoId $autoId = null): string
{
return "INSERT INTO $tableName VALUES (:data)";
try {
$id = Configuration::$idField;
$values = match (Configuration::$mode) {
Mode::SQLite => match ($autoId ?? AutoId::None) {
AutoId::None => ':data',
AutoId::Number => "json_set(:data, '$.$id', "
. "(SELECT coalesce(max(data->>'$id'), 0) + 1 FROM $tableName))",
AutoId::UUID => "json_set(:data, '$.$id', '" . AutoId::generateUUID() . "')",
AutoId::RandomString => "json_set(:data, '$.$id', '" . AutoId::generateRandom() ."')"
},
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() . "\"}'",
},
default =>
throw new DocumentException('Database mode not set; cannot generate auto-ID INSERT statement'),
};
return "INSERT INTO $tableName VALUES ($values)";
} catch (RandomException $ex) {
throw new DocumentException('Unable to generate ID: ' . $ex->getMessage(), previous: $ex);
}
}
/**
@ -60,8 +90,8 @@ class Query
*/
public static function save(string $tableName): string
{
return self::insert($tableName)
. " ON CONFLICT ((data->>'" . Configuration::$idField . "')) DO UPDATE SET data = EXCLUDED.data";
$id = Configuration::$idField;
return "INSERT INTO $tableName VALUES (:data) ON CONFLICT ((data->>'$id')) DO UPDATE SET data = EXCLUDED.data";
}
/**
@ -69,6 +99,7 @@ class Query
*
* @param string $tableName The name of the table in which the document should be updated
* @return string The UPDATE query for the document
* @throws DocumentException If the database mode has not been set
*/
public static function update(string $tableName): string
{

9
src/Query/Count.php
View File

@ -2,7 +2,7 @@
namespace BitBadger\PDODocument\Query;
use BitBadger\PDODocument\{Field, Query};
use BitBadger\PDODocument\{DocumentException, Field, FieldMatch, Query};
/**
* Queries for counting documents
@ -25,11 +25,12 @@ class Count
*
* @param string $tableName The name of the table in which documents should be counted
* @param Field[] $fields The field comparison to match
* @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
* @param FieldMatch|null $match How to join multiple conditions (optional; defaults to All)
* @return string The query to count documents using a field comparison
* @throws DocumentException If the database mode has not been set
*/
public static function byFields(string $tableName, array $fields, string $conjunction = 'AND'): string
public static function byFields(string $tableName, array $fields, ?FieldMatch $match = null): string
{
return self::all($tableName) . ' WHERE ' . Query::whereByFields($fields, $conjunction);
return self::all($tableName) . ' WHERE ' . Query::whereByFields($fields, $match);
}
}

10
src/Query/Delete.php
View File

@ -2,7 +2,7 @@
namespace BitBadger\PDODocument\Query;
use BitBadger\PDODocument\{Field, Query};
use BitBadger\PDODocument\{DocumentException, Field, FieldMatch, Query};
/**
* Queries to delete documents
@ -14,6 +14,7 @@ class Delete
*
* @param string $tableName The name of the table from which a document should be deleted
* @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
{
@ -25,11 +26,12 @@ class Delete
*
* @param string $tableName The name of the table from which documents should be deleted
* @param Field[] $fields The field comparison to match
* @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @return string The DELETE statement to delete documents via field comparison
* @throws DocumentException If the database mode has not been set
*/
public static function byFields(string $tableName, array $fields, string $conjunction = 'AND'): string
public static function byFields(string $tableName, array $fields, ?FieldMatch $match = null): string
{
return "DELETE FROM $tableName WHERE " . Query::whereByFields($fields, $conjunction);
return "DELETE FROM $tableName WHERE " . Query::whereByFields($fields, $match);
}
}

10
src/Query/Exists.php
View File

@ -2,7 +2,7 @@
namespace BitBadger\PDODocument\Query;
use BitBadger\PDODocument\{Field, Query};
use BitBadger\PDODocument\{DocumentException, Field, FieldMatch, Query};
/**
* Queries to determine document existence
@ -26,6 +26,7 @@ class Exists
*
* @param string $tableName The name of the table in which document existence should be checked
* @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
{
@ -37,11 +38,12 @@ class Exists
*
* @param string $tableName The name of the table in which document existence should be checked
* @param Field[] $fields The field comparison to match
* @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @return string The query to determine document existence by field comparison
* @throws DocumentException If the database mode has not been set
*/
public static function byFields(string $tableName, array $fields, string $conjunction = 'AND'): string
public static function byFields(string $tableName, array $fields, ?FieldMatch $match = null): string
{
return self::query($tableName, Query::whereByFields($fields, $conjunction));
return self::query($tableName, Query::whereByFields($fields, $match));
}
}

10
src/Query/Find.php
View File

@ -2,7 +2,7 @@
namespace BitBadger\PDODocument\Query;
use BitBadger\PDODocument\{Field, Query};
use BitBadger\PDODocument\{DocumentException, Field, FieldMatch, Query};
/**
* Queries for retrieving documents
@ -14,6 +14,7 @@ class Find
*
* @param string $tableName The name of the table from which a document should be retrieved
* @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
{
@ -25,11 +26,12 @@ class Find
*
* @param string $tableName The name of the table from which documents should be retrieved
* @param Field[] $fields The field comparison to match
* @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @return string The SELECT statement to retrieve documents by field comparison
* @throws DocumentException If the database mode has not been set
*/
public static function byFields(string $tableName, array $fields, string $conjunction = 'AND'): string
public static function byFields(string $tableName, array $fields, ?FieldMatch $match = null): string
{
return Query::selectFromTable($tableName) . ' WHERE ' . Query::whereByFields($fields, $conjunction);
return Query::selectFromTable($tableName) . ' WHERE ' . Query::whereByFields($fields, $match);
}
}

8
src/Query/Patch.php
View File

@ -2,7 +2,7 @@
namespace BitBadger\PDODocument\Query;
use BitBadger\PDODocument\{Configuration, DocumentException, Field, Mode, Query};
use BitBadger\PDODocument\{Configuration, DocumentException, Field, FieldMatch, Mode, Query};
/**
* Queries to perform partial updates on documents
@ -44,12 +44,12 @@ class Patch
*
* @param string $tableName The name of the table in which documents should be patched
* @param array|Field[] $field The field comparison to match
* @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @return string The query to patch documents via field comparison
* @throws DocumentException If the database mode has not been set
*/
public static function byFields(string $tableName, array $field, string $conjunction = 'AND'): string
public static function byFields(string $tableName, array $field, ?FieldMatch $match = null): string
{
return self::update($tableName, Query::whereByFields($field, $conjunction));
return self::update($tableName, Query::whereByFields($field, $match));
}
}

8
src/Query/RemoveFields.php
View File

@ -2,7 +2,7 @@
namespace BitBadger\PDODocument\Query;
use BitBadger\PDODocument\{Configuration, DocumentException, Field, Mode, Query};
use BitBadger\PDODocument\{Configuration, DocumentException, Field, FieldMatch, Mode, Query};
/**
* Queries to remove fields from documents
@ -54,13 +54,13 @@ class RemoveFields
* @param string $tableName The name of the table in which documents should be manipulated
* @param array|Field[] $fields The field comparison to match
* @param array $parameters The parameter list for the query
* @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @return string The UPDATE statement to remove fields from documents via field comparison
* @throws DocumentException If the database mode has not been set
*/
public static function byFields(string $tableName, array $fields, array $parameters,
string $conjunction = 'AND'): string
?FieldMatch $match = null): string
{
return self::update($tableName, $parameters, Query::whereByFields($fields, $conjunction));
return self::update($tableName, $parameters, Query::whereByFields($fields, $match));
}
}

6
src/RemoveFields.php
View File

@ -28,15 +28,15 @@ class RemoveFields
* @param string $tableName The table in which documents should have fields removed
* @param array|Field[] $fields The field comparison to match
* @param array|string[] $fieldNames The names of the fields to be removed
* @param string $conjunction How to handle multiple conditions (optional; defaults to `AND`)
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @throws DocumentException If any is encountered
*/
public static function byFields(string $tableName, array $fields, array $fieldNames,
string $conjunction = 'AND'): void
?FieldMatch $match = null): void
{
$nameParams = Parameters::fieldNames(':name', $fieldNames);
$namedFields = Parameters::nameFields($fields);
Custom::nonQuery(Query\RemoveFields::byFields($tableName, $namedFields, $nameParams, $conjunction),
Custom::nonQuery(Query\RemoveFields::byFields($tableName, $namedFields, $nameParams, $match),
Parameters::addFields($namedFields, $nameParams));
}
}

11
tests/integration/NumDocument.php Normal file
View File

@ -0,0 +1,11 @@
<?php declare(strict_types=1);
namespace Test\Integration;
/**
* A test document with a numeric ID
*/
class NumDocument
{
public function __construct(public int $id = 0, public string $value = '') { }
}

224
tests/integration/sqlite/DocumentTest.php
View File

@ -2,10 +2,11 @@
namespace Test\Integration\SQLite;
use BitBadger\PDODocument\{Document, DocumentException, Find};
use BitBadger\PDODocument\{AutoId, Configuration, Custom, Document, DocumentException, Field, Find};
use BitBadger\PDODocument\Mapper\ArrayMapper;
use PHPUnit\Framework\Attributes\TestDox;
use PHPUnit\Framework\TestCase;
use Test\Integration\{SubDocument, TestDocument};
use Test\Integration\{NumDocument, SubDocument, TestDocument};
/**
* SQLite integration tests for the Document class
@ -28,7 +29,125 @@ class DocumentTest extends TestCase
parent::tearDown();
}
public function testInsertSucceeds(): void
#[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 data->>'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);
@ -41,6 +160,105 @@ class DocumentTest extends TestCase
$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);

14
tests/unit/ConfigurationTest.php
View File

@ -2,7 +2,7 @@
namespace Test\Unit;
use BitBadger\PDODocument\{Configuration, DocumentException};
use BitBadger\PDODocument\{AutoId, Configuration, DocumentException};
use PHPUnit\Framework\Attributes\TestDox;
use PHPUnit\Framework\TestCase;
@ -29,6 +29,18 @@ class ConfigurationTest extends TestCase
}
}
#[TestDox('Auto ID default succeeds')]
public function testAutoIdDefaultSucceeds(): void
{
$this->assertEquals(AutoId::None, Configuration::$autoId, 'Auto ID should default to None');
}
#[TestDox('ID string length default succeeds')]
public function testIdStringLengthDefaultSucceeds(): void
{
$this->assertEquals(16, Configuration::$idStringLength, 'ID string length should default to 16');
}
#[TestDox("Db conn fails when no DSN specified")]
public function testDbConnFailsWhenNoDSNSpecified(): void
{

22
tests/unit/FieldMatchTest.php Normal file
View File

@ -0,0 +1,22 @@
<?php declare(strict_types=1);
namespace Test\Unit;
use BitBadger\PDODocument\FieldMatch;
use PHPUnit\Framework\TestCase;
/**
* Unit tests for the FieldMatch enum
*/
class FieldMatchTest extends TestCase
{
public function testToStringSucceedsForAll(): void
{
$this->assertEquals('AND', FieldMatch::All->toString(), 'All should have returned AND');
}
public function testToStringSucceedsForAny(): void
{
$this->assertEquals('OR', FieldMatch::Any->toString(), 'Any should have returned OR');
}
}

5
tests/unit/Query/FindTest.php
View File

@ -2,7 +2,7 @@
namespace Test\Unit\Query;
use BitBadger\PDODocument\{Configuration, Field, Mode};
use BitBadger\PDODocument\{Configuration, Field, FieldMatch, Mode};
use BitBadger\PDODocument\Query\Find;
use PHPUnit\Framework\Attributes\TestDox;
use PHPUnit\Framework\TestCase;
@ -32,7 +32,8 @@ class FindTest extends TestCase
public function testByFieldsSucceeds(): void
{
$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')], 'OR'),
Find::byFields('there', [Field::EQ('active', true, ':act'), Field::EQ('locked', true, ':lock')],
FieldMatch::Any),
'SELECT query not generated correctly');
}
}

130
tests/unit/QueryTest.php
View File

@ -2,7 +2,7 @@
namespace Test\Unit;
use BitBadger\PDODocument\{Configuration, Field, Mode, Query};
use BitBadger\PDODocument\{AutoId, Configuration, DocumentException, Field, FieldMatch, Mode, Query};
use PHPUnit\Framework\Attributes\TestDox;
use PHPUnit\Framework\TestCase;
@ -33,17 +33,18 @@ class QueryTest extends TestCase
Query::whereByFields([Field::LE('test_field', '', ':it')]), 'WHERE fragment not constructed correctly');
}
public function testWhereByFieldsSucceedsForMultipleFields(): void
public function testWhereByFieldsSucceedsForMultipleFieldsAll(): void
{
$this->assertEquals("data->>'test_field' <= :it AND data->>'other_field' = :other",
Query::whereByFields([Field::LE('test_field', '', ':it'), Field::EQ('other_field', '', ':other')]),
'WHERE fragment not constructed correctly');
}
public function testWhereByFieldsSucceedsForMultipleFieldsWithOr(): void
public function testWhereByFieldsSucceedsForMultipleFieldsAny(): void
{
$this->assertEquals("data->>'test_field' <= :it OR data->>'other_field' = :other",
Query::whereByFields([Field::LE('test_field', '', ':it'), Field::EQ('other_field', '', ':other')], 'OR'),
Query::whereByFields([Field::LE('test_field', '', ':it'), Field::EQ('other_field', '', ':other')],
FieldMatch::Any),
'WHERE fragment not constructed correctly');
}
@ -59,10 +60,125 @@ class QueryTest extends TestCase
$this->assertEquals("data->>'id' = :di", Query::whereById(':di'), 'WHERE fragment not constructed correctly');
}
public function testInsertSucceeds(): void
#[TestDox('Insert succeeds with no auto-ID for PostgreSQL')]
public function testInsertSucceedsWithNoAutoIdForPostgreSQL(): void
{
$this->assertEquals('INSERT INTO my_table VALUES (:data)', Query::insert('my_table'),
'INSERT statement not constructed correctly');
Configuration::$mode = Mode::PgSQL;
try {
$this->assertEquals('INSERT INTO test_tbl VALUES (:data)', Query::insert('test_tbl'),
'INSERT statement not constructed correctly');
} finally {
Configuration::$mode = null;
}
}
#[TestDox('Insert succeeds with no auto-ID for SQLite')]
public function testInsertSucceedsWithNoAutoIdForSQLite(): void
{
Configuration::$mode = Mode::SQLite;
try {
$this->assertEquals('INSERT INTO test_tbl VALUES (:data)', Query::insert('test_tbl'),
'INSERT statement not constructed correctly');
} finally {
Configuration::$mode = null;
}
}
#[TestDox('Insert succeeds with auto numeric ID for PostgreSQL')]
public function testInsertSucceedsWithAutoNumericIdForPostgreSQL(): void
{
Configuration::$mode = Mode::PgSQL;
try {
$this->assertEquals(
"INSERT INTO test_tbl VALUES (:data || ('{\"id\":' "
. "|| (SELECT COALESCE(MAX(data->>'id'), 0) + 1 FROM test_tbl) || '}'))",
Query::insert('test_tbl', AutoId::Number), 'INSERT statement not constructed correctly');
} finally {
Configuration::$mode = null;
}
}
#[TestDox('Insert succeeds with auto numeric ID for SQLite')]
public function testInsertSucceedsWithAutoNumericIdForSQLite(): void
{
Configuration::$mode = Mode::SQLite;
try {
$this->assertEquals(
"INSERT INTO test_tbl VALUES (json_set(:data, '$.id', "
. "(SELECT coalesce(max(data->>'id'), 0) + 1 FROM test_tbl)))",
Query::insert('test_tbl', AutoId::Number), 'INSERT statement not constructed correctly');
} finally {
Configuration::$mode = null;
}
}
#[TestDox('Insert succeeds with auto UUID for PostgreSQL')]
public function testInsertSucceedsWithAutoUuidForPostgreSQL(): void
{
Configuration::$mode = Mode::PgSQL;
try {
$query = Query::insert('test_tbl', AutoId::UUID);
$this->assertStringStartsWith("INSERT INTO test_tbl VALUES (:data || '{\"id\":\"", $query,
'INSERT statement not constructed correctly');
$this->assertStringEndsWith("\"}')", $query, 'INSERT statement not constructed correctly');
} finally {
Configuration::$mode = null;
}
}
#[TestDox('Insert succeeds with auto UUID for SQLite')]
public function testInsertSucceedsWithAutoUuidForSQLite(): void
{
Configuration::$mode = Mode::SQLite;
try {
$query = Query::insert('test_tbl', AutoId::UUID);
$this->assertStringStartsWith("INSERT INTO test_tbl VALUES (json_set(:data, '$.id', '", $query,
'INSERT statement not constructed correctly');
$this->assertStringEndsWith("'))", $query, 'INSERT statement not constructed correctly');
} finally {
Configuration::$mode = null;
}
}
#[TestDox('Insert succeeds with auto random string for PostgreSQL')]
public function testInsertSucceedsWithAutoRandomStringForPostgreSQL(): void
{
Configuration::$mode = Mode::PgSQL;
Configuration::$idStringLength = 8;
try {
$query = Query::insert('test_tbl', AutoId::RandomString);
$this->assertStringStartsWith("INSERT INTO test_tbl VALUES (:data || '{\"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);
$this->assertEquals(8, strlen($id), "Generated ID [$id] should have been 8 characters long");
} finally {
Configuration::$mode = null;
Configuration::$idStringLength = 16;
}
}
#[TestDox('Insert succeeds with auto random string for SQLite')]
public function testInsertSucceedsWithAutoRandomStringForSQLite(): void
{
Configuration::$mode = Mode::SQLite;
try {
$query = Query::insert('test_tbl', AutoId::RandomString);
$this->assertStringStartsWith("INSERT INTO test_tbl VALUES (json_set(:data, '$.id', '", $query,
'INSERT statement not constructed correctly');
$this->assertStringEndsWith("'))", $query, 'INSERT statement not constructed correctly');
$id = str_replace(["INSERT INTO test_tbl VALUES (json_set(:data, '$.id', '", "'))"], '', $query);
$this->assertEquals(16, strlen($id), "Generated ID [$id] should have been 16 characters long");
} finally {
Configuration::$mode = null;
}
}
public function testInsertFailsWhenModeNotSet(): void
{
$this->expectException(DocumentException::class);
Configuration::$mode = null;
Query::insert('kaboom');
}
public function testSaveSucceeds(): void