diff --git a/documentation/Bruno/Arcadia Api/Api/V1/Brands/List Brands (Clamped Pagination).yml b/documentation/Bruno/Arcadia Api/Api/V1/Brands/List Brands (Clamped Pagination).yml new file mode 100644 index 0000000..865caa5 --- /dev/null +++ b/documentation/Bruno/Arcadia Api/Api/V1/Brands/List Brands (Clamped Pagination).yml @@ -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 diff --git a/documentation/Bruno/Arcadia Api/Api/V1/Brands/List Brands.yml b/documentation/Bruno/Arcadia Api/Api/V1/Brands/List Brands.yml index 035ae8a..3b9d058 100644 --- a/documentation/Bruno/Arcadia Api/Api/V1/Brands/List Brands.yml +++ b/documentation/Bruno/Arcadia Api/Api/V1/Brands/List Brands.yml @@ -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 diff --git a/documentation/Bruno/Arcadia Api/Api/V1/Employees/List Employees.yml b/documentation/Bruno/Arcadia Api/Api/V1/Employees/List Employees.yml index af0844e..397ea9a 100644 --- a/documentation/Bruno/Arcadia Api/Api/V1/Employees/List Employees.yml +++ b/documentation/Bruno/Arcadia Api/Api/V1/Employees/List Employees.yml @@ -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 diff --git a/documentation/Bruno/Arcadia Api/Api/V1/IncoSheets/List Inco Sheets.yml b/documentation/Bruno/Arcadia Api/Api/V1/IncoSheets/List Inco Sheets.yml index c1757ce..b6b27b7 100644 --- a/documentation/Bruno/Arcadia Api/Api/V1/IncoSheets/List Inco Sheets.yml +++ b/documentation/Bruno/Arcadia Api/Api/V1/IncoSheets/List Inco Sheets.yml @@ -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 diff --git a/documentation/OpenApi/openapi.yaml b/documentation/OpenApi/openapi.yaml index e8902fe..8a3cd1d 100644 --- a/documentation/OpenApi/openapi.yaml +++ b/documentation/OpenApi/openapi.yaml @@ -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 diff --git a/src/Presentation/Api/V1/Http/Requests/Brands/BrandsIndexRequest.php b/src/Presentation/Api/V1/Http/Requests/Brands/BrandsIndexRequest.php index 1d4c3e1..d1df367 100644 --- a/src/Presentation/Api/V1/Http/Requests/Brands/BrandsIndexRequest.php +++ b/src/Presentation/Api/V1/Http/Requests/Brands/BrandsIndexRequest.php @@ -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], ]; } } diff --git a/src/Presentation/Api/V1/Http/Requests/Employees/EmployeesIndexRequest.php b/src/Presentation/Api/V1/Http/Requests/Employees/EmployeesIndexRequest.php index ae29155..0521bb2 100644 --- a/src/Presentation/Api/V1/Http/Requests/Employees/EmployeesIndexRequest.php +++ b/src/Presentation/Api/V1/Http/Requests/Employees/EmployeesIndexRequest.php @@ -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() diff --git a/src/Presentation/Api/V1/Http/Requests/IncoSheets/IncoSheetsIndexRequest.php b/src/Presentation/Api/V1/Http/Requests/IncoSheets/IncoSheetsIndexRequest.php index 715e301..67479f2 100644 --- a/src/Presentation/Api/V1/Http/Requests/IncoSheets/IncoSheetsIndexRequest.php +++ b/src/Presentation/Api/V1/Http/Requests/IncoSheets/IncoSheetsIndexRequest.php @@ -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() diff --git a/src/Shared/Pagination.php b/src/Shared/Pagination.php index 253b552..f9eed48 100644 --- a/src/Shared/Pagination.php +++ b/src/Shared/Pagination.php @@ -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); } diff --git a/tests/Unit/Shared/PaginationTest.php b/tests/Unit/Shared/PaginationTest.php index 71ebadf..090c859 100644 --- a/tests/Unit/Shared/PaginationTest.php +++ b/tests/Unit/Shared/PaginationTest.php @@ -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], ]); });