feat(pagination): move Pagination to namespace and introduce PageNumber, PageSize and Equatable

This commit is contained in:
Jérémy Munsch 2026-09-15 12:49:13 +02:00
parent f098582fe6
commit 09c8806a5e
Signed by: forge-joniko
GPG key ID: D7EFE2F5CB6CC0E4
6 changed files with 99 additions and 23 deletions

View file

@ -29,8 +29,8 @@ final readonly class ApiConfig
if (! in_array(strtolower($endpoint->getScheme()), ['http', 'https'])) {
throw new \InvalidArgumentException('endpoint must have http or https scheme');
}
if ($curlTimeOut < 0) {
throw new \InvalidArgumentException('curlTimeOut must be non-negative');
if ($curlTimeOut <= 0) {
throw new \InvalidArgumentException('curlTimeOut must be positive');
}
if ($maxRetries < 0) {
throw new \InvalidArgumentException('maxRetries must be non-negative');

10
src/Lib/Equatable.php Normal file
View file

@ -0,0 +1,10 @@
<?php
declare(strict_types=1);
namespace Uwil\ArcadiaApiPhpClient\Lib;
interface Equatable
{
public function equals(mixed $other): bool;
}

View file

@ -0,0 +1,53 @@
<?php
declare(strict_types=1);
namespace Uwil\ArcadiaApiPhpClient\Lib\Pagination;
use Uwil\ArcadiaApiPhpClient\Lib\Equatable;
/**
* Value object representing a page number in pagination (1-indexed).
*/
final readonly class PageNumber implements \JsonSerializable, \Stringable, Equatable
{
public const int DEFAULT_PAGE = 1;
public function __construct(
public int $value = self::DEFAULT_PAGE,
) {
if ($this->value <= 0) {
throw new \InvalidArgumentException('Page number must be greater than 0');
}
}
public static function of(int $value): self
{
return new self($value);
}
public static function default(): self
{
return new self(self::DEFAULT_PAGE);
}
public function value(): int
{
return $this->value;
}
public function equals(mixed $other): bool
{
return $other instanceof self && $this->value === $other->value;
}
public function __toString(): string
{
return (string) $this->value;
}
public function jsonSerialize(): int
{
return $this->value;
}
}

View file

@ -2,12 +2,14 @@
declare(strict_types=1);
namespace Uwil\ArcadiaApiPhpClient\Lib;
namespace Uwil\ArcadiaApiPhpClient\Lib\Pagination;
use Uwil\ArcadiaApiPhpClient\Lib\Equatable;
/**
* Value object representing a page size in pagination.
*/
final readonly class PageSize implements \JsonSerializable, \Stringable
final readonly class PageSize implements \JsonSerializable, \Stringable, Equatable
{
public const int DEFAULT_SIZE = 50;
@ -41,6 +43,11 @@ final readonly class PageSize implements \JsonSerializable, \Stringable
return $this->value;
}
public function equals(mixed $other): bool
{
return $other instanceof self && $this->value === $other->value;
}
public function __toString(): string
{
return (string) $this->value;

View file

@ -2,12 +2,14 @@
declare(strict_types=1);
namespace Uwil\ArcadiaApiPhpClient\Lib;
namespace Uwil\ArcadiaApiPhpClient\Lib\Pagination;
use Uwil\ArcadiaApiPhpClient\Lib\Equatable;
/**
* Immutable value object representing a pagination range.
*/
final class Pagination
final class Pagination implements Equatable
{
/** ERR_TOO_MANY_RECORDS fixed to 10k */
public const int MAX_PAGE_SIZE = PageSize::MAX_PAGE_SIZE;
@ -50,24 +52,30 @@ final class Pagination
return (int) ($this->from / $this->pageSize()) + 1;
}
public function pageSizeVo(): PageSize
{
return new PageSize($this->pageSize());
}
public function pageNumberVo(): PageNumber
{
return new PageNumber($this->pageNumber());
}
public function equals(mixed $other): bool
{
return $other instanceof self && $this->from === $other->from && $this->to === $other->to;
}
public static function ofIndexes(int $from, int $to): self
{
return new self($from, $to);
}
public static function ofPage(int $pageNumber, int | PageSize $pageSize): self
public static function ofPage(PageNumber $pageNumber, PageSize $pageSize = new PageSize()): self
{
$resolvedPageSize = $pageSize instanceof PageSize ? $pageSize->value : $pageSize;
if ($pageNumber <= 0) {
throw new \InvalidArgumentException('Page number must be positive and non-zero');
}
if ($resolvedPageSize <= 0) {
throw new \InvalidArgumentException('Page size must be positive and non-zero');
}
$fromIndex = ($pageNumber - 1) * $resolvedPageSize;
$toIndex = max($pageNumber * $resolvedPageSize - 1, 1);
$fromIndex = ($pageNumber->value - 1) * $pageSize->value;
$toIndex = max($pageNumber->value * $pageSize->value - 1, 1);
return new self($fromIndex, $toIndex);
}
@ -87,9 +95,9 @@ final class Pagination
return new self($fromIndex, $toIndex);
}
public static function firstPage(int | PageSize $pageSize = new PageSize()): self
public static function firstPage(PageSize $pageSize = new PageSize()): self
{
return self::ofPage(1, $pageSize);
return self::ofPage(new PageNumber(1), $pageSize);
}
public function __toString(): string

View file

@ -6,8 +6,6 @@ namespace Uwil\ArcadiaApiPhpClient\Lib\Pagination;
use Uwil\ArcadiaApiPhpClient\Error\ApiError;
use Uwil\ArcadiaApiPhpClient\Lib\ApiDto\Dto\PaginationDto;
use Uwil\ArcadiaApiPhpClient\Lib\PageSize;
use Uwil\ArcadiaApiPhpClient\Lib\Pagination;
/**
* Lazy stream / cursor iterator over paginated API resources.
@ -60,7 +58,7 @@ final class StreamOf implements \IteratorAggregate
$pageNumber = 1;
do {
$pagination = Pagination::ofPage($pageNumber, $this->pageSize);
$pagination = Pagination::ofPage(new PageNumber($pageNumber), $this->pageSize);
$result = ($this->pageFetcher)($pagination);
if ($result instanceof ApiError) {