refactor(pagination): clamp out-of-bounds pagination values silently

This commit is contained in:
Jérémy Munsch 2026-08-25 08:26:50 +02:00
parent bdb72b65d6
commit 3582a3928c
Signed by: forge-joniko
GPG key ID: D7EFE2F5CB6CC0E4
10 changed files with 96 additions and 82 deletions

View file

@ -0,0 +1,24 @@
info:
name: List Brands (Clamped Pagination)
type: http
seq: 2
http:
method: GET
url: "{{ENDPOINT}}/api/{{APIV1}}/brands?page=0&pageSize=0"
params:
- name: page
value: "0"
type: query
description: Out-of-range page (clamped to 1 by the API)
- name: pageSize
value: "0"
type: query
description: Out-of-range pageSize (clamped to 1 by the API)
auth: inherit
settings:
encodeUrl: true
timeout: 0
followRedirects: true
maxRedirects: 5

View file

@ -10,20 +10,20 @@ http:
- name: page
value: "1"
type: query
description: 1-based page index
description: 1-based page index (out-of-range values are silently clamped)
- name: pageSize
value: "25"
type: query
description: Number of items per page (max 10000)
description: Number of items per page (max 10000, out-of-range values are silently clamped)
- name: offset
value: "0"
type: query
description: Offset for offset-based pagination
description: Offset for offset-based pagination (negative values clamped to 0)
disabled: true
- name: limit
value: "25"
type: query
description: Limit for offset-based pagination
description: Limit for offset-based pagination (out-of-range values are silently clamped)
disabled: true
auth: inherit

View file

@ -10,20 +10,20 @@ http:
- name: page
value: "1"
type: query
description: 1-based page index
description: 1-based page index (out-of-range values are silently clamped)
- name: pageSize
value: "25"
type: query
description: Number of items per page (max 10000)
description: Number of items per page (max 10000, out-of-range values are silently clamped)
- name: offset
value: "0"
type: query
description: Offset for offset-based pagination
description: Offset for offset-based pagination (negative values clamped to 0)
disabled: true
- name: limit
value: "25"
type: query
description: Limit for offset-based pagination
description: Limit for offset-based pagination (out-of-range values are silently clamped)
disabled: true
- name: since
value: 2026-01-01T00:00:00Z

View file

@ -10,20 +10,20 @@ http:
- name: page
value: "1"
type: query
description: 1-based page index
description: 1-based page index (out-of-range values are silently clamped)
- name: pageSize
value: "25"
type: query
description: Number of items per page (max 10000)
description: Number of items per page (max 10000, out-of-range values are silently clamped)
- name: offset
value: "0"
type: query
description: Offset for offset-based pagination
description: Offset for offset-based pagination (negative values clamped to 0)
disabled: true
- name: limit
value: "25"
type: query
description: Limit for offset-based pagination
description: Limit for offset-based pagination (out-of-range values are silently clamped)
disabled: true
- name: since
value: 2026-01-01T00:00:00Z

View file

@ -401,10 +401,9 @@ components:
name: page
in: query
required: false
description: Numéro de page (1-based).
description: Numéro de page (1-based). Les valeurs hors bornes sont silencieusement corrigées par l'API.
schema:
type: integer
minimum: 1
default: 1
example: 1
@ -412,10 +411,9 @@ components:
name: pageSize
in: query
required: false
description: Nombre d'éléments par page (max 10000).
description: Nombre d'éléments par page (max 10000). Les valeurs hors bornes sont silencieusement corrigées par l'API.
schema:
type: integer
minimum: 1
maximum: 10000
default: 25
example: 25
@ -424,7 +422,7 @@ components:
name: offset
in: query
required: false
description: Décalage d'index pour la pagination basée sur l'offset.
description: Décalage d'index pour la pagination basée sur l'offset. Les valeurs négatives sont silencieusement corrigées à 0.
schema:
type: integer
minimum: 0
@ -434,10 +432,9 @@ components:
name: limit
in: query
required: false
description: Nombre maximal d'enregistrements pour la pagination par offset.
description: Nombre maximal d'enregistrements pour la pagination par offset. Les valeurs hors bornes sont silencieusement corrigées par l'API.
schema:
type: integer
minimum: 1
maximum: 10000
example: 25

View file

@ -17,10 +17,10 @@ final class BrandsIndexRequest extends FormRequest
public function rules(): array
{
return [
'offset' => ['sometimes', 'integer', 'min:0'],
'limit' => ['sometimes', 'integer', 'min:1', 'max:' . Pagination::MAX_PAGE_SIZE],
'page' => ['sometimes', 'integer', 'min:1'],
'pageSize' => ['sometimes', 'integer', 'min:1', 'max:' . Pagination::MAX_PAGE_SIZE],
'offset' => ['sometimes', 'integer'],
'limit' => ['sometimes', 'integer', 'max:' . Pagination::MAX_PAGE_SIZE],
'page' => ['sometimes', 'integer'],
'pageSize' => ['sometimes', 'integer', 'max:' . Pagination::MAX_PAGE_SIZE],
];
}
}

View file

@ -24,10 +24,10 @@ final class EmployeesIndexRequest extends FormRequest
public function rules(): array
{
return [
'offset' => ['sometimes', 'integer', 'min:0'],
'limit' => ['sometimes', 'integer', 'min:1', 'max:' . Pagination::MAX_PAGE_SIZE],
'page' => ['sometimes', 'integer', 'min:1'],
'pageSize' => ['sometimes', 'integer', 'min:1', 'max:' . Pagination::MAX_PAGE_SIZE],
'offset' => ['sometimes', 'integer'],
'limit' => ['sometimes', 'integer', 'max:' . Pagination::MAX_PAGE_SIZE],
'page' => ['sometimes', 'integer'],
'pageSize' => ['sometimes', 'integer', 'max:' . Pagination::MAX_PAGE_SIZE],
'sortBy' => ['sometimes', Rule::in(array_map(
static fn (EmployeeSortColumn $case): string => $case->name,
EmployeeSortColumn::cases()

View file

@ -23,10 +23,10 @@ final class IncoSheetsIndexRequest extends FormRequest
public function rules(): array
{
return [
'offset' => ['sometimes', 'integer', 'min:0'],
'limit' => ['sometimes', 'integer', 'min:1', 'max:' . Pagination::MAX_PAGE_SIZE],
'page' => ['sometimes', 'integer', 'min:1'],
'pageSize' => ['sometimes', 'integer', 'min:1', 'max:' . Pagination::MAX_PAGE_SIZE],
'offset' => ['sometimes', 'integer'],
'limit' => ['sometimes', 'integer', 'max:' . Pagination::MAX_PAGE_SIZE],
'page' => ['sometimes', 'integer'],
'pageSize' => ['sometimes', 'integer', 'max:' . Pagination::MAX_PAGE_SIZE],
'sortBy' => ['sometimes', Rule::in(array_map(
static fn (IncoSheetSortColumn $case): string => $case->name,
IncoSheetSortColumn::cases()

View file

@ -12,22 +12,10 @@ final readonly class Pagination
/** ERR_TOO_MANY_RECORDS fixed to 10k */
public const int MAX_PAGE_SIZE = 10000;
public function __construct(
private function __construct(
private int $from,
private int $to,
) {
if ($from < 0) {
throw new \InvalidArgumentException('From index must be non-negative');
}
if ($to < 0) {
throw new \InvalidArgumentException('To index must be non-negative');
}
if ($to <= $from) {
throw new \InvalidArgumentException('To index must be greater than from index');
}
if (($to - $from + 1) > self::MAX_PAGE_SIZE) {
throw new \InvalidArgumentException('Page size must be less than or equal to ' . self::MAX_PAGE_SIZE);
}
}
public function from(): int
@ -52,35 +40,30 @@ final readonly class Pagination
public static function ofIndexes(int $from, int $to): self
{
$from = max(0, $from);
$to = clamp($to, $from + 1, $from + self::MAX_PAGE_SIZE);
return new self($from, $to);
}
public static function ofPage(int $pageNumber, int $pageSize): self
{
if ($pageNumber <= 0) {
throw new \InvalidArgumentException('Page number must be positive and non-zero');
}
if ($pageSize <= 0) {
throw new \InvalidArgumentException('Page size must be positive and non-zero');
}
$pageNumber = max(1, $pageNumber);
$pageSize = clamp($pageSize, 1, self::MAX_PAGE_SIZE);
$fromIndex = ($pageNumber - 1) * $pageSize;
$toIndex = max($pageNumber * $pageSize - 1, 1);
$toIndex = $fromIndex + $pageSize - 1;
return new self($fromIndex, $toIndex);
}
public static function ofOffsetAndLimit(int $offset, int $limit): self
{
if ($offset < 0) {
throw new \InvalidArgumentException('Offset must be non-negative');
}
if ($limit <= 0) {
throw new \InvalidArgumentException('Limit must be positive and non-zero');
}
$offset = max(0, $offset);
$limit = clamp($limit, 1, self::MAX_PAGE_SIZE);
$fromIndex = $offset;
$toIndex = max($offset + $limit - 1, 1);
$toIndex = $offset + $limit - 1;
return new self($fromIndex, $toIndex);
}

View file

@ -78,36 +78,46 @@ describe('Pagination Value Object Unit Tests', function (): void {
expect($stringRepresentation)->toBe('Pagination{from=0, to=9}');
});
it('throws InvalidArgumentException for invalid constructor inputs', function (int $from, int $to, string $expectedMessage): void {
// GIVEN / WHEN / THEN
expect(fn () => new Pagination($from, $to))
->toThrow(\InvalidArgumentException::class, $expectedMessage);
it('clamps invalid constructor-level values via ofIndexes', function (int $from, int $to, int $expectedFrom, int $expectedTo): void {
// GIVEN / WHEN
$pagination = Pagination::ofIndexes($from, $to);
// THEN
expect($pagination->from())->toBe($expectedFrom)
->and($pagination->to())->toBe($expectedTo);
})->with([
[-1, 10, 'From index must be non-negative'],
[0, -1, 'To index must be non-negative'],
[10, 5, 'To index must be greater than from index'],
[10, 10, 'To index must be greater than from index'],
[0, 10001, 'Page size must be less than or equal to 10000'],
'negative from is clamped to 0' => [-1, 10, 0, 10],
'to below from+1 is clamped to from+1' => [10, 5, 10, 11],
'to equal from is clamped to from+1' => [10, 10, 10, 11],
'oversized range is clamped to max' => [0, 10001, 0, 10000],
]);
it('throws InvalidArgumentException for invalid ofPage parameters', function (int $page, int $size, string $expectedMessage): void {
// GIVEN / WHEN / THEN
expect(fn () => Pagination::ofPage($page, $size))
->toThrow(\InvalidArgumentException::class, $expectedMessage);
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([
[0, 10, 'Page number must be positive and non-zero'],
[-1, 10, 'Page number must be positive and non-zero'],
[1, 0, 'Page size must be positive and non-zero'],
[1, -5, 'Page size must be positive and non-zero'],
'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('throws InvalidArgumentException for invalid ofOffsetAndLimit parameters', function (int $offset, int $limit, string $expectedMessage): void {
// GIVEN / WHEN / THEN
expect(fn () => Pagination::ofOffsetAndLimit($offset, $limit))
->toThrow(\InvalidArgumentException::class, $expectedMessage);
it('clamps invalid ofOffsetAndLimit parameters', function (int $offset, int $limit, int $expectedFrom, int $expectedSize): void {
// GIVEN / WHEN
$pagination = Pagination::ofOffsetAndLimit($offset, $limit);
// THEN
expect($pagination->from())->toBe($expectedFrom)
->and($pagination->pageSize())->toBe($expectedSize);
})->with([
[-1, 10, 'Offset must be non-negative'],
[0, 0, 'Limit must be positive and non-zero'],
[0, -5, 'Limit must be positive and non-zero'],
'negative offset clamped to 0' => [-1, 10, 0, 10],
'limit 0 clamped to 1' => [0, 0, 0, 1],
'negative limit clamped to 1' => [0, -5, 0, 1],
'oversized limit clamped' => [0, 20000, 0, 10000],
]);
});