pdo-document/src/DocumentList.php
Daniel J. Summers 486028bd40 v2 RC1 Changes (#7)
- Changes `items` and `hasItems` on `DocumentList` to be properties
- Updates dependent option/result library, which contains similar changes

Reviewed-on: #7
2024-10-02 01:37:08 +00:00

148 lines
4.7 KiB
PHP

<?php
/**
* @author Daniel J. Summers <daniel@bitbadger.solutions>
* @license MIT
*/
declare(strict_types=1);
namespace BitBadger\PDODocument;
use BitBadger\PDODocument\Mapper\Mapper;
use Generator;
use PDO;
use PDOStatement;
/**
* A lazy iterator of results in a list; implementations will create new connections to the database and close/dispose
* them as required once the results have been exhausted.
*
* @template TDoc The domain class for items returned by this list
*/
class DocumentList
{
/** @var TDoc|null $first The first item from the results */
private mixed $first = null;
/** @var bool $isConsumed This is set to true once the generator has been exhausted */
private bool $isConsumed = false;
/**
* Constructor
*
* @param PDOStatement|null $result The result of the query
* @param Mapper<TDoc> $mapper The mapper to deserialize JSON
*/
private function __construct(private ?PDOStatement &$result, private readonly Mapper $mapper)
{
if (!is_null($this->result)) {
if ($row = $this->result->fetch(PDO::FETCH_ASSOC)) {
$this->first = $this->mapper->map($row);
} else {
$this->result = null;
}
}
}
/** @var bool True if there are items still to be retrieved from the list, false if not */
public bool $hasItems {
get => !is_null($this->result);
}
/**
* @var Generator<TDoc> The items from the document list
* @throws DocumentException If this is called once the generator has been consumed
*/
public Generator $items {
get {
if (!$this->result) {
if ($this->isConsumed) {
throw new DocumentException('Cannot call items() multiple times');
}
$this->isConsumed = true;
return;
}
if (!$this->first) {
$this->isConsumed = true;
$this->result = null;
return;
}
yield $this->first;
while ($row = $this->result->fetch(PDO::FETCH_ASSOC)) {
yield $this->mapper->map($row);
}
$this->isConsumed = true;
$this->result = null;
}
}
/**
* Map items by consuming the generator
*
* @template U The type to which each item should be mapped
* @param callable(TDoc): U $map The mapping function
* @return Generator<U> The result of the mapping function
* @throws DocumentException If this is called once the generator has been consumed
*/
public function map(callable $map): Generator
{
foreach ($this->items as $item) {
yield $map($item);
}
}
/**
* Iterate the generator, running the given function for each item
*
* @param callable(TDoc): void $f The function to run for each item
* @throws DocumentException If this is called once the generator has been consumed
*/
public function iter(callable $f): void
{
foreach ($this->items as $item) {
$f($item);
}
}
/**
* Iterate the generator, extracting key/value pairs returned as an associative array
*
* @template TValue The type for the mapped value
* @param callable(TDoc): (int|string) $keyFunc The function to extract a key from the document
* @param callable(TDoc): TValue $valueFunc The function to extract a value from the document
* @return TValue[] An associative array of values, keyed by the extracted keys
* @throws DocumentException If this is called once the generator has been consumed
*/
public function mapToArray(callable $keyFunc, callable $valueFunc): array
{
$results = [];
foreach ($this->items as $item) {
$results[$keyFunc($item)] = $valueFunc($item);
}
return $results;
}
/**
* Ensure the statement is destroyed if the generator is not exhausted
*/
public function __destruct()
{
if (!is_null($this->result)) $this->result = null;
}
/**
* Construct a new document list
*
* @param string $query The query to run to retrieve results
* @param array<string, mixed> $parameters An associative array of parameters for the query
* @param Mapper<TDoc> $mapper A mapper to deserialize JSON documents
* @return self<TDoc> The document list instance
* @throws DocumentException If any is encountered
*/
public static function create(string $query, array $parameters, Mapper $mapper): self
{
$stmt = &Custom::runQuery($query, $parameters);
return new self($stmt, $mapper);
}
}