feat(pagination): add PageNumber and PageSize value objects and update Pagination
This commit is contained in:
parent
e83a286e9b
commit
0c361c5ff7
6 changed files with 345 additions and 29 deletions
|
|
@ -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
|
||||
|
|
|
|||
53
src/Shared/Pagination/PageNumber.php
Normal file
53
src/Shared/Pagination/PageNumber.php
Normal 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;
|
||||
}
|
||||
}
|
||||
60
src/Shared/Pagination/PageSize.php
Normal file
60
src/Shared/Pagination/PageSize.php
Normal 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;
|
||||
}
|
||||
}
|
||||
76
tests/Unit/Shared/Pagination/PageNumberTest.php
Normal file
76
tests/Unit/Shared/Pagination/PageNumberTest.php
Normal 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();
|
||||
});
|
||||
});
|
||||
83
tests/Unit/Shared/Pagination/PageSizeTest.php
Normal file
83
tests/Unit/Shared/Pagination/PageSizeTest.php
Normal 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();
|
||||
});
|
||||
});
|
||||
|
|
@ -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();
|
||||
});
|
||||
});
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue