129 lines
3.7 KiB
PHP
129 lines
3.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 ($row = $this->result->fetch(PDO::FETCH_ASSOC)) {
|
|
$this->first = $this->mapper->map($row);
|
|
} else {
|
|
$this->result = null;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Does this list have items remaining?
|
|
*
|
|
* @return bool True if there are items still to be retrieved from the list, false if not
|
|
*/
|
|
public function hasItems(): bool
|
|
{
|
|
return !is_null($this->result);
|
|
}
|
|
|
|
/**
|
|
* The items from the query result
|
|
*
|
|
* @return Generator<TDoc> The items from the document list
|
|
* @throws DocumentException If this is called once the generator has been consumed
|
|
*/
|
|
public function items(): Generator
|
|
{
|
|
if (!$this->result) {
|
|
if ($this->isConsumed) {
|
|
throw new DocumentException('Cannot call items() multiple times');
|
|
}
|
|
$this->isConsumed = true;
|
|
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);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* 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 $parameters An associative array of parameters for the query
|
|
* @param Mapper<TDoc> $mapper A mapper to deserialize JSON documents
|
|
* @return static The document list instance
|
|
* @throws DocumentException If any is encountered
|
|
*/
|
|
public static function create(string $query, array $parameters, Mapper $mapper): static
|
|
{
|
|
$stmt = &Custom::runQuery($query, $parameters);
|
|
return new static($stmt, $mapper);
|
|
}
|
|
}
|