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

Add Custom JSON, Json methods; WIP on tests

Browse Source
This commit is contained in:
Daniel J. Summers
2025-04-22 21:32:30 -04:00
parent f6756d79f1
commit 46b079b237
6 changed files with 600 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

244
src/Json.php Normal file
View File

@@ -0,0 +1,244 @@
<?php
/**
* @author Daniel J. Summers <daniel@bitbadger.solutions>
* @license MIT
*/
declare(strict_types=1);
namespace BitBadger\PDODocument;
/**
* Functions to retrieve and output documents as JSON
*/
class Json
{
/**
* Retrieve all JSON documents in the given table
*
* @param string $tableName The table from which documents should be retrieved
* @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
* @return string A JSON array of all documents from the table
* @throws DocumentException If any is encountered
*/
public static function all(string $tableName, array $orderBy = []): string
{
return Custom::jsonArray(Query::selectFromTable($tableName) . Query::orderBy($orderBy), []);
}
/**
* Retrieve a JSON document by its ID
*
* @param string $tableName The table from which the document should be retrieved
* @param mixed $docId The ID of the document to retrieve
* @return string The JSON document if found, `{}` otherwise
* @throws DocumentException If any is encountered
*/
public static function byId(string $tableName, mixed $docId): string
{
return Custom::jsonSingle(Query\Find::byId($tableName, $docId), Parameters::id($docId));
}
/**
* Retrieve JSON documents via a comparison on JSON fields
*
* @param string $tableName The table from which documents should be retrieved
* @param Field[] $fields The field comparison to match
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
* @return string A JSON array of documents matching the given field comparison
* @throws DocumentException If any is encountered
*/
public static function byFields(string $tableName, array $fields, ?FieldMatch $match = null,
array $orderBy = []): string
{
Parameters::nameFields($fields);
return Custom::jsonArray(Query\Find::byFields($tableName, $fields, $match) . Query::orderBy($orderBy),
Parameters::addFields($fields, []));
}
/**
* Retrieve JSON documents via a JSON containment query (`@>`; PostgreSQL only)
*
* @param string $tableName The name of the table from which documents should be retrieved
* @param mixed[]|object $criteria The criteria for the JSON containment query
* @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
* @return string A JSON array 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, array $orderBy = []): string
{
return Custom::jsonArray(Query\Find::byContains($tableName) . Query::orderBy($orderBy),
Parameters::json(':criteria', $criteria));
}
/**
* Retrieve JSON documents via a JSON Path match query (`@?`; PostgreSQL only)
*
* @param string $tableName The name of the table from which documents should be retrieved
* @param string $path The JSON Path match string
* @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
* @return string A JSON array 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, array $orderBy = []): string
{
return Custom::jsonArray(Query\Find::byJsonPath($tableName) . Query::orderBy($orderBy), [':path' => $path]);
}
/**
* Retrieve JSON documents via a comparison on JSON fields, returning only the first result
*
* @param string $tableName The table from which the document should be retrieved
* @param Field[] $fields The field comparison to match
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
* @return string The first JSON document if any matches are found, `{}` otherwise
* @throws DocumentException If any is encountered
*/
public static function firstByFields(string $tableName, array $fields, ?FieldMatch $match = null,
array $orderBy = []): string
{
Parameters::nameFields($fields);
return Custom::jsonSingle(Query\Find::byFields($tableName, $fields, $match) . Query::orderBy($orderBy),
Parameters::addFields($fields, []));
}
/**
* Retrieve JSON documents via a JSON containment query (`@>`), returning only the first result (PostgreSQL only)
*
* @param string $tableName The name of the table from which documents should be retrieved
* @param mixed[]|object $criteria The criteria for the JSON containment query
* @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
* @return string The first JSON document if any matches are found, `{}` otherwise
* @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
*/
public static function firstByContains(string $tableName, array|object $criteria, array $orderBy = []): string
{
return Custom::jsonSingle(Query\Find::byContains($tableName) . Query::orderBy($orderBy),
Parameters::json(':criteria', $criteria));
}
/**
* Retrieve JSON documents via a JSON Path match query (`@?`), returning only the first result (PostgreSQL only)
*
* @param string $tableName The name of the table from which documents should be retrieved
* @param string $path The JSON Path match string
* @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
* @return string The first JSON document if any matches are found, `{}` otherwise
* @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
*/
public static function firstByJsonPath(string $tableName, string $path, array $orderBy = []): string
{
return Custom::jsonSingle(Query\Find::byJsonPath($tableName) . Query::orderBy($orderBy), [':path' => $path]);
}
/**
* Output all JSON documents in the given table
*
* @param string $tableName The table from which documents should be retrieved
* @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
* @throws DocumentException If any is encountered
*/
public static function outputAll(string $tableName, array $orderBy = []): void
{
Custom::outputJsonArray(Query::selectFromTable($tableName) . Query::orderBy($orderBy), []);
}
/**
* Output a JSON document by its ID
*
* @param string $tableName The table from which the document should be retrieved
* @param mixed $docId The ID of the document to retrieve
* @throws DocumentException If any is encountered
*/
public static function outputById(string $tableName, mixed $docId): void
{
echo self::byId($tableName, $docId);
}
/**
* Output JSON documents via a comparison on JSON fields
*
* @param string $tableName The table from which documents should be retrieved
* @param Field[] $fields The field comparison to match
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
* @throws DocumentException If any is encountered
*/
public static function outputByFields(string $tableName, array $fields, ?FieldMatch $match = null,
array $orderBy = []): void
{
Parameters::nameFields($fields);
Custom::outputJsonArray(Query\Find::byFields($tableName, $fields, $match) . Query::orderBy($orderBy),
Parameters::addFields($fields, []));
}
/**
* Output JSON documents via a JSON containment query (`@>`; PostgreSQL only)
*
* @param string $tableName The name of the table from which documents should be retrieved
* @param mixed[]|object $criteria The criteria for the JSON containment query
* @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
* @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
*/
public static function outputByContains(string $tableName, array|object $criteria, array $orderBy = []): void
{
Custom::outputJsonArray(Query\Find::byContains($tableName) . Query::orderBy($orderBy),
Parameters::json(':criteria', $criteria));
}
/**
* Output JSON documents via a JSON Path match query (`@?`; PostgreSQL only)
*
* @param string $tableName The name of the table from which documents should be retrieved
* @param string $path The JSON Path match string
* @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
* @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
*/
public static function outputByJsonPath(string $tableName, string $path, array $orderBy = []): void
{
Custom::outputJsonArray(Query\Find::byJsonPath($tableName) . Query::orderBy($orderBy), [':path' => $path]);
}
/**
* Output JSON documents via a comparison on JSON fields, returning only the first result
*
* @param string $tableName The table from which the document should be retrieved
* @param Field[] $fields The field comparison to match
* @param FieldMatch|null $match How to handle multiple conditions (optional; defaults to All)
* @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
* @throws DocumentException If any is encountered
*/
public static function outputFirstByFields(string $tableName, array $fields, ?FieldMatch $match = null,
array $orderBy = []): void
{
echo self::firstByFields($tableName, $fields, $match, $orderBy);
}
/**
* Output JSON documents via a JSON containment query (`@>`), returning only the first result (PostgreSQL only)
*
* @param string $tableName The name of the table from which documents should be retrieved
* @param mixed[]|object $criteria The criteria for the JSON containment query
* @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
* @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
*/
public static function outputFirstByContains(string $tableName, array|object $criteria, array $orderBy = []): void
{
echo self::firstByContains($tableName, $criteria, $orderBy);
}
/**
* Output JSON documents via a JSON Path match query (`@?`), returning only the first result (PostgreSQL only)
*
* @param string $tableName The name of the table from which documents should be retrieved
* @param string $path The JSON Path match string
* @param Field[] $orderBy Fields by which the results should be ordered (optional, default no ordering)
* @throws DocumentException If the database mode is not PostgreSQL, or if an error occurs
*/
public static function outputFirstByJsonPath(string $tableName, string $path, array $orderBy = []): void
{
echo self::firstByJsonPath($tableName, $path, $orderBy);
}
}