diff --git a/src/Shared/Pagination.php b/src/Shared/Pagination.php index f9eed48..5cc79b3 100644 --- a/src/Shared/Pagination.php +++ b/src/Shared/Pagination.php @@ -4,13 +4,17 @@ declare(strict_types=1); namespace Shared; +use Shared\DDD\Model\Equatable; +use Shared\Pagination\PageNumber; +use Shared\Pagination\PageSize; + /** * Immutable value object representing a pagination range. */ -final readonly class Pagination +final readonly class Pagination implements Equatable { /** ERR_TOO_MANY_RECORDS fixed to 10k */ - public const int MAX_PAGE_SIZE = 10000; + public const int MAX_PAGE_SIZE = PageSize::MAX_PAGE_SIZE; private function __construct( private int $from, @@ -38,6 +42,21 @@ final readonly 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 { $from = max(0, $from); @@ -46,13 +65,10 @@ final readonly class Pagination return new self($from, $to); } - public static function ofPage(int $pageNumber, int $pageSize): self + public static function ofPage(PageNumber $pageNumber, PageSize $pageSize = new PageSize()): self { - $pageNumber = max(1, $pageNumber); - $pageSize = clamp($pageSize, 1, self::MAX_PAGE_SIZE); - - $fromIndex = ($pageNumber - 1) * $pageSize; - $toIndex = $fromIndex + $pageSize - 1; + $fromIndex = ($pageNumber->value - 1) * $pageSize->value; + $toIndex = $fromIndex + $pageSize->value - 1; return new self($fromIndex, $toIndex); } @@ -68,9 +84,9 @@ final readonly class Pagination return new self($fromIndex, $toIndex); } - public static function firstPage(int $pageSize = 25): 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/Shared/Pagination/PageNumber.php b/src/Shared/Pagination/PageNumber.php new file mode 100644 index 0000000..f2c143f --- /dev/null +++ b/src/Shared/Pagination/PageNumber.php @@ -0,0 +1,53 @@ +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/Shared/Pagination/PageSize.php b/src/Shared/Pagination/PageSize.php new file mode 100644 index 0000000..7d8faf9 --- /dev/null +++ b/src/Shared/Pagination/PageSize.php @@ -0,0 +1,60 @@ +value <= 0) { + throw new \InvalidArgumentException('Page size must be greater than 0'); + } + + if ($this->value > self::MAX_PAGE_SIZE) { + throw new \InvalidArgumentException('Page size must be less than or equal to ' . self::MAX_PAGE_SIZE); + } + } + + public static function of(int $value): self + { + return new self($value); + } + + public static function default(): self + { + return new self(self::DEFAULT_SIZE); + } + + 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/tests/Unit/Shared/Pagination/PageNumberTest.php b/tests/Unit/Shared/Pagination/PageNumberTest.php new file mode 100644 index 0000000..934628a --- /dev/null +++ b/tests/Unit/Shared/Pagination/PageNumberTest.php @@ -0,0 +1,76 @@ +value)->toBe(1) + ->and($page->value())->toBe(1) + ->and((string) $page)->toBe('1') + ->and(json_encode($page))->toBe('1'); + }); + + it('creates a valid page number with specific value', function (): void { + // GIVEN + $value = 5; + + // WHEN + $page = new PageNumber($value); + + // THEN + expect($page->value)->toBe(5) + ->and($page->value())->toBe(5) + ->and((string) $page)->toBe('5'); + }); + + it('creates a page number using of() factory', function (): void { + // GIVEN + $value = 10; + + // WHEN + $page = PageNumber::of($value); + + // THEN + expect($page->value)->toBe(10); + }); + + it('creates a page number using default() factory', function (): void { + // GIVEN / WHEN + $page = PageNumber::default(); + + // THEN + expect($page->value)->toBe(1); + }); + + it('rejects invalid page numbers', function (int $invalid): void { + // GIVEN / WHEN + expect(fn () => new PageNumber($invalid)) + // THEN + ->toThrow(InvalidArgumentException::class, 'Page number must be greater than 0'); + })->with([0, -1, -5, -100]); + + it('correctly checks equality with another instance', function (): void { + // GIVEN + $page1 = new PageNumber(2); + $page2 = new PageNumber(2); + $page3 = new PageNumber(3); + + // THEN + expect($page1->equals($page2))->toBeTrue() + ->and($page1->equals($page3))->toBeFalse() + ->and($page1->equals(2))->toBeFalse() + ->and($page1->equals(null))->toBeFalse() + ->and($page1->equals('2'))->toBeFalse(); + }); +}); diff --git a/tests/Unit/Shared/Pagination/PageSizeTest.php b/tests/Unit/Shared/Pagination/PageSizeTest.php new file mode 100644 index 0000000..d75025a --- /dev/null +++ b/tests/Unit/Shared/Pagination/PageSizeTest.php @@ -0,0 +1,83 @@ +value)->toBe(25) + ->and($size->value())->toBe(25) + ->and((string) $size)->toBe('25') + ->and(json_encode($size))->toBe('25'); + }); + + it('creates a valid page size with specific value', function (): void { + // GIVEN + $value = 50; + + // WHEN + $size = new PageSize($value); + + // THEN + expect($size->value)->toBe(50) + ->and($size->value())->toBe(50) + ->and((string) $size)->toBe('50'); + }); + + it('creates a page size using of() factory', function (): void { + // GIVEN + $value = 100; + + // WHEN + $size = PageSize::of($value); + + // THEN + expect($size->value)->toBe(100); + }); + + it('creates a page size using default() factory', function (): void { + // GIVEN / WHEN + $size = PageSize::default(); + + // THEN + expect($size->value)->toBe(25); + }); + + it('rejects invalid page sizes below 1', function (int $invalid): void { + // GIVEN / WHEN + expect(fn () => new PageSize($invalid)) + // THEN + ->toThrow(InvalidArgumentException::class, 'Page size must be greater than 0'); + })->with([0, -1, -10, -100]); + + it('rejects page size exceeding max allowed', function (): void { + // GIVEN / WHEN + expect(fn () => new PageSize(10001)) + // THEN + ->toThrow(InvalidArgumentException::class, 'Page size must be less than or equal to 10000'); + }); + + it('correctly checks equality with another instance', function (): void { + // GIVEN + $size1 = new PageSize(20); + $size2 = new PageSize(20); + $size3 = new PageSize(50); + + // THEN + expect($size1->equals($size2))->toBeTrue() + ->and($size1->equals($size3))->toBeFalse() + ->and($size1->equals(20))->toBeFalse() + ->and($size1->equals(null))->toBeFalse() + ->and($size1->equals('20'))->toBeFalse(); + }); +}); diff --git a/tests/Unit/Shared/PaginationTest.php b/tests/Unit/Shared/PaginationTest.php index 38a0248..62c8e63 100644 --- a/tests/Unit/Shared/PaginationTest.php +++ b/tests/Unit/Shared/PaginationTest.php @@ -5,14 +5,16 @@ declare(strict_types=1); namespace Tests\Unit\Shared; use Shared\Pagination; +use Shared\Pagination\PageNumber; +use Shared\Pagination\PageSize; covers(Pagination::class); describe('Pagination Value Object Unit Tests', function (): void { it('can be created from page and page size', function (): void { // GIVEN - $page = 2; - $size = 20; + $page = new PageNumber(2); + $size = new PageSize(20); // WHEN $pagination = Pagination::ofPage($page, $size); @@ -53,9 +55,20 @@ describe('Pagination Value Object Unit Tests', function (): void { ->and($pagination->pageSize())->toBe(10); }); - it('can be created using first page helper', function (): void { + it('can be created using first page helper with default size', function (): void { + // WHEN + $pagination = Pagination::firstPage(); + + // THEN + expect($pagination->from())->toBe(0) + ->and($pagination->to())->toBe(24) + ->and($pagination->pageSize())->toBe(25) + ->and($pagination->pageNumber())->toBe(1); + }); + + it('can be created using first page helper with explicit size', function (): void { // GIVEN - $pageSize = 15; + $pageSize = new PageSize(15); // WHEN $pagination = Pagination::firstPage($pageSize); @@ -92,21 +105,6 @@ describe('Pagination Value Object Unit Tests', function (): void { 'oversized range is clamped to max' => [0, 10001, 0, 10000], ]); - it('clamps invalid ofPage parameters', function (int $page, int $size, int $expectedPage, int $expectedSize): void { - // GIVEN / WHEN - $pagination = Pagination::ofPage($page, $size); - - // THEN - expect($pagination->pageNumber())->toBe($expectedPage) - ->and($pagination->pageSize())->toBe($expectedSize); - })->with([ - 'page 0 is clamped to 1' => [0, 10, 1, 10], - 'negative page clamped to 1' => [-1, 10, 1, 10], - 'size 0 is clamped to 1' => [1, 0, 1, 1], - 'negative size clamped to 1' => [1, -5, 1, 1], - 'oversized clamped to max' => [1, 20000, 1, 10000], - ]); - it('clamps invalid ofOffsetAndLimit parameters', function (int $offset, int $limit, int $expectedFrom, int $expectedSize): void { // GIVEN / WHEN $pagination = Pagination::ofOffsetAndLimit($offset, $limit); @@ -120,4 +118,34 @@ describe('Pagination Value Object Unit Tests', function (): void { 'negative limit clamped to 1' => [0, -5, 0, 1], 'oversized limit clamped' => [0, 20000, 0, 10000], ]); + + it('creates pagination using ofPage with Value Objects', function (): void { + // GIVEN + $pageNumber = new PageNumber(3); + $pageSize = new PageSize(15); + + // WHEN + $pagination = Pagination::ofPage($pageNumber, $pageSize); + + // THEN + expect($pagination->from())->toBe(30) + ->and($pagination->to())->toBe(44) + ->and($pagination->pageSize())->toBe(15) + ->and($pagination->pageNumber())->toBe(3) + ->and($pagination->pageNumberVo())->toEqual($pageNumber) + ->and($pagination->pageSizeVo())->toEqual($pageSize); + }); + + it('checks equality with another Pagination instance', function (): void { + // GIVEN + $p1 = Pagination::ofPage(new PageNumber(1), new PageSize(20)); + $p2 = Pagination::ofPage(new PageNumber(1), new PageSize(20)); + $p3 = Pagination::ofPage(new PageNumber(2), new PageSize(20)); + + // THEN + expect($p1->equals($p2))->toBeTrue() + ->and($p1->equals($p3))->toBeFalse() + ->and($p1->equals(null))->toBeFalse() + ->and($p1->equals('pagination'))->toBeFalse(); + }); });