From 09c8806a5e6de37ffa627d26d3e95126aeb921ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=A9r=C3=A9my=20Munsch?= Date: Tue, 15 Sep 2026 12:49:13 +0200 Subject: [PATCH] feat(pagination): move Pagination to namespace and introduce PageNumber, PageSize and Equatable --- src/Lib/ApiConfig.php | 4 +- src/Lib/Equatable.php | 10 +++++ src/Lib/Pagination/PageNumber.php | 53 +++++++++++++++++++++++++ src/Lib/{ => Pagination}/PageSize.php | 11 ++++- src/Lib/{ => Pagination}/Pagination.php | 40 +++++++++++-------- src/Lib/Pagination/StreamOf.php | 4 +- 6 files changed, 99 insertions(+), 23 deletions(-) create mode 100644 src/Lib/Equatable.php create mode 100644 src/Lib/Pagination/PageNumber.php rename src/Lib/{ => Pagination}/PageSize.php (82%) rename src/Lib/{ => Pagination}/Pagination.php (69%) diff --git a/src/Lib/ApiConfig.php b/src/Lib/ApiConfig.php index 47d2250..90a52f4 100644 --- a/src/Lib/ApiConfig.php +++ b/src/Lib/ApiConfig.php @@ -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'); diff --git a/src/Lib/Equatable.php b/src/Lib/Equatable.php new file mode 100644 index 0000000..3242212 --- /dev/null +++ b/src/Lib/Equatable.php @@ -0,0 +1,10 @@ +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; + } +} diff --git a/src/Lib/PageSize.php b/src/Lib/Pagination/PageSize.php similarity index 82% rename from src/Lib/PageSize.php rename to src/Lib/Pagination/PageSize.php index 0b2c7d3..c686dc4 100644 --- a/src/Lib/PageSize.php +++ b/src/Lib/Pagination/PageSize.php @@ -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; diff --git a/src/Lib/Pagination.php b/src/Lib/Pagination/Pagination.php similarity index 69% rename from src/Lib/Pagination.php rename to src/Lib/Pagination/Pagination.php index 2029625..53d54f4 100644 --- a/src/Lib/Pagination.php +++ b/src/Lib/Pagination/Pagination.php @@ -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 diff --git a/src/Lib/Pagination/StreamOf.php b/src/Lib/Pagination/StreamOf.php index f794f04..051b9fb 100644 --- a/src/Lib/Pagination/StreamOf.php +++ b/src/Lib/Pagination/StreamOf.php @@ -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) {