253 lines
12 KiB
PHP
253 lines
12 KiB
PHP
<?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);
|
|
}
|
|
|
|
/**
|
|
* Set the content type of this page's output to JSON
|
|
*/
|
|
public static function setContentType(): void
|
|
{
|
|
header('Content-Type: application/json; charset=UTF-8');
|
|
}
|
|
}
|