feat(pagination): add PageNumber and PageSize value objects and update Pagination

This commit is contained in:
Jérémy Munsch 2026-09-15 12:48:52 +02:00
parent e83a286e9b
commit 0c361c5ff7
Signed by: forge-joniko
GPG key ID: D7EFE2F5CB6CC0E4
6 changed files with 345 additions and 29 deletions

View file

@ -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

View file

@ -0,0 +1,53 @@
<?php
declare(strict_types=1);
namespace Shared\Pagination;
use Shared\DDD\Model\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

@ -0,0 +1,60 @@
<?php
declare(strict_types=1);
namespace Shared\Pagination;
use Shared\DDD\Model\Equatable;
/**
* Value object representing a page size in pagination.
*/
final readonly class PageSize implements \JsonSerializable, \Stringable, Equatable
{
public const int DEFAULT_SIZE = 25;
/** ERR_TOO_MANY_RECORDS fixed to 10k */
public const int MAX_PAGE_SIZE = 10000;
public function __construct(
public int $value = self::DEFAULT_SIZE,
) {
if ($this->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;
}
}

View file

@ -0,0 +1,76 @@
<?php
declare(strict_types=1);
namespace Tests\Unit\Shared\Pagination;
use InvalidArgumentException;
use Shared\Pagination\PageNumber;
covers(PageNumber::class);
describe('PageNumber Value Object Unit Tests', function (): void {
it('creates a valid page number with default value', function (): void {
// GIVEN / WHEN
$page = new PageNumber();
// THEN
expect($page->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();
});
});

View file

@ -0,0 +1,83 @@
<?php
declare(strict_types=1);
namespace Tests\Unit\Shared\Pagination;
use InvalidArgumentException;
use Shared\Pagination\PageSize;
covers(PageSize::class);
describe('PageSize Value Object Unit Tests', function (): void {
it('creates a valid page size with default value', function (): void {
// GIVEN / WHEN
$size = new PageSize();
// THEN
expect($size->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();
});
});

View file

@ -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();
});
});