feat(dto): implement PaginationDto for pagination metadata

Added PaginationDto to handle pagination details and links for API responses.
Updated related response classes to utilize the new PaginationDto.
This commit is contained in:
Jérémy Munsch 2026-08-14 12:02:13 +02:00
parent 2cc333f1df
commit 70375f8139
Signed by: forge-joniko
GPG key ID: D7EFE2F5CB6CC0E4
11 changed files with 172 additions and 59 deletions

View file

@ -4,6 +4,11 @@ declare(strict_types=1);
namespace Presentation\Api\V1\Contracts;
interface ApiResponseDto
use Illuminate\Contracts\Support\Arrayable;
/**
* @extends Arrayable<string, mixed>
*/
interface ApiResponseDto extends Arrayable
{
}

View file

@ -36,4 +36,12 @@ final readonly class EmployeeDto implements ApiResponseDto
plannedEndDate: $view->plannedEndDate?->format('Y-m-d'),
);
}
/** @return array<string, mixed> */
#[\Override]
public function toArray(): array
{
/** @var array<string, mixed> */
return get_object_vars($this);
}
}

View file

@ -36,4 +36,12 @@ final readonly class PaginatedEmployee implements ApiResponseDto
plannedEndDate: $employee->plannedEndDate?->format('Y-m-d'),
);
}
/** @return array<string, mixed> */
#[\Override]
public function toArray(): array
{
/** @var array<string, mixed> */
return get_object_vars($this);
}
}

View file

@ -14,6 +14,7 @@ final readonly class IncoSheetDto implements ApiResponseDto
{
/**
* @param array{allegations: array<int, string>, health: array<int, string>, nutrition: array<int, string>, other: array<int, string>} $allegations
* @param object $ingredients
* @param array{lowPart: int, highPart: int, approximative: bool}|null $portions
* @param array<int, array{code: int, label: string}> $allergens
* @param array{code: string, label: string} $brand
@ -158,4 +159,12 @@ final readonly class IncoSheetDto implements ApiResponseDto
updatedAt: $sheet->updatedAt?->format(\DateTimeInterface::ATOM),
);
}
/** @return array<string, mixed> */
#[\Override]
public function toArray(): array
{
/** @var array<string, mixed> */
return get_object_vars($this);
}
}

View file

@ -28,4 +28,12 @@ final readonly class IncoShortSheetDto implements ApiResponseDto
updatedAt: $sheet->updatedAt?->format(\DateTimeInterface::ATOM),
);
}
/** @return array<string, mixed> */
#[\Override]
public function toArray(): array
{
/** @var array<string, mixed> */
return get_object_vars($this);
}
}

View file

@ -0,0 +1,58 @@
<?php
declare(strict_types=1);
namespace Presentation\Api\V1\Dto;
use League\Uri\Http;
use Presentation\Api\V1\Contracts\ApiResponseDto;
final readonly class PaginationDto implements ApiResponseDto
{
/**
* @param array{self: string, first: string, prev: ?string, next: ?string, last: string} $links
*/
private function __construct(
public int $page,
public int $pageSize,
public int $totalItems,
public int $totalPages,
public array $links,
) {
}
public static function create(int $page, int $pageSize, int $totalItems, Http $baseUri): self
{
$totalPages = $pageSize > 0 ? (int) ceil($totalItems / $pageSize) : 1;
$firstUrl = (string) $baseUri->withQuery(http_build_query(['page' => 1, 'pageSize' => $pageSize]));
$lastUrl = (string) $baseUri->withQuery(http_build_query(['page' => $totalPages, 'pageSize' => $pageSize]));
$selfUrl = (string) $baseUri->withQuery(http_build_query(['page' => $page, 'pageSize' => $pageSize]));
$prevUrl = $page > 1 ? (string) $baseUri->withQuery(http_build_query(['page' => $page - 1, 'pageSize' => $pageSize])) : null;
$nextUrl = $page < $totalPages ? (string) $baseUri->withQuery(http_build_query(['page' => $page + 1, 'pageSize' => $pageSize])) : null;
return new self(
page: $page,
pageSize: $pageSize,
totalItems: $totalItems,
totalPages: $totalPages,
links: [
'self' => $selfUrl,
'first' => $firstUrl,
'prev' => $prevUrl,
'next' => $nextUrl,
'last' => $lastUrl,
],
);
}
/** @return array<string, mixed> */
#[\Override]
public function toArray(): array
{
/** @var array<string, mixed> $vars */
$vars = get_object_vars($this);
return $vars;
}
}

View file

@ -25,10 +25,8 @@ final readonly class EmployeeShowResponse implements ApiResponse
#[\Override]
public function present(): JsonResponse
{
$dto = EmployeeDto::fromView($this->view);
return response()->json([
'employee' => get_object_vars($dto),
'employee' => EmployeeDto::fromView($this->view),
]);
}
}

View file

@ -9,6 +9,7 @@ use Illuminate\Http\JsonResponse;
use League\Uri\Http;
use Presentation\Api\V1\Contracts\ApiResponse;
use Presentation\Api\V1\Dto\Employees\PaginatedEmployee as PaginatedEmployeeDto;
use Presentation\Api\V1\Dto\PaginationDto;
use Presentation\Api\V1\Presenters\Employees\EmployeesIndexView;
final readonly class EmployeesIndexResponse implements ApiResponse
@ -28,37 +29,19 @@ final readonly class EmployeesIndexResponse implements ApiResponse
#[\Override]
public function present(): JsonResponse
{
$page = $this->view->page;
$pageSize = $this->view->perPage;
$totalItems = $this->view->total;
$totalPages = $pageSize > 0 ? (int) ceil($totalItems / $pageSize) : 1;
$firstUrl = (string) $this->baseUri->withQuery(http_build_query(['page' => 1, 'pageSize' => $pageSize]));
$lastUrl = (string) $this->baseUri->withQuery(http_build_query(['page' => $totalPages, 'pageSize' => $pageSize]));
$selfUrl = (string) $this->baseUri->withQuery(http_build_query(['page' => $page, 'pageSize' => $pageSize]));
$prevUrl = $page > 1 ? (string) $this->baseUri->withQuery(http_build_query(['page' => $page - 1, 'pageSize' => $pageSize])) : null;
$nextUrl = $page < $totalPages ? (string) $this->baseUri->withQuery(http_build_query(['page' => $page + 1, 'pageSize' => $pageSize])) : null;
$pagination = PaginationDto::create(
page: $this->view->page,
pageSize: $this->view->perPage,
totalItems: $this->view->total,
baseUri: $this->baseUri,
);
return response()->json([
'employees' => array_map(
static fn (PaginatedEmployee $employee): array => get_object_vars(
PaginatedEmployeeDto::fromUsecase($employee)
),
static fn (PaginatedEmployee $employee): array => PaginatedEmployeeDto::fromUsecase($employee)->toArray(),
$this->view->employees
),
'pagination' => [
'page' => $page,
'pageSize' => $pageSize,
'totalItems' => $totalItems,
'totalPages' => $totalPages,
'links' => [
'self' => $selfUrl,
'first' => $firstUrl,
'prev' => $prevUrl,
'next' => $nextUrl,
'last' => $lastUrl,
],
],
'pagination' => $pagination,
]);
}
}

View file

@ -11,6 +11,7 @@ use League\Uri\Http;
use Presentation\Api\V1\Contracts\ApiResponse;
use Presentation\Api\V1\Dto\IncoSheets\IncoSheetDto;
use Presentation\Api\V1\Dto\IncoSheets\IncoShortSheetDto;
use Presentation\Api\V1\Dto\PaginationDto;
use Presentation\Api\V1\Presenters\IncoSheets\IncoSheetsIndexView;
final readonly class IncoSheetsIndexResponse implements ApiResponse
@ -30,39 +31,23 @@ final readonly class IncoSheetsIndexResponse implements ApiResponse
#[\Override]
public function present(): JsonResponse
{
$page = $this->view->page;
$pageSize = $this->view->perPage;
$totalItems = $this->view->total;
$totalPages = $pageSize > 0 ? (int) ceil($totalItems / $pageSize) : 1;
$firstUrl = (string) $this->baseUri->withQuery(http_build_query(['page' => 1, 'pageSize' => $pageSize]));
$lastUrl = (string) $this->baseUri->withQuery(http_build_query(['page' => $totalPages, 'pageSize' => $pageSize]));
$selfUrl = (string) $this->baseUri->withQuery(http_build_query(['page' => $page, 'pageSize' => $pageSize]));
$prevUrl = $page > 1 ? (string) $this->baseUri->withQuery(http_build_query(['page' => $page - 1, 'pageSize' => $pageSize])) : null;
$nextUrl = $page < $totalPages ? (string) $this->baseUri->withQuery(http_build_query(['page' => $page + 1, 'pageSize' => $pageSize])) : null;
$pagination = PaginationDto::create(
page: $this->view->page,
pageSize: $this->view->perPage,
totalItems: $this->view->total,
baseUri: $this->baseUri,
);
$items = array_map(
fn (PaginatedIncoSheet | PaginatedShortIncoSheet $sheet): array => $sheet instanceof PaginatedShortIncoSheet
? get_object_vars(IncoShortSheetDto::fromPaginatedShortIncoSheet($sheet))
: get_object_vars(IncoSheetDto::fromPaginatedIncoSheet($sheet)),
fn (PaginatedIncoSheet|PaginatedShortIncoSheet $sheet): array => $sheet instanceof PaginatedShortIncoSheet
? IncoShortSheetDto::fromPaginatedShortIncoSheet($sheet)->toArray()
: IncoSheetDto::fromPaginatedIncoSheet($sheet)->toArray(),
$this->view->incoSheets
);
return response()->json([
'incoSheets' => $items,
'pagination' => [
'page' => $page,
'pageSize' => $pageSize,
'totalItems' => $totalItems,
'totalPages' => $totalPages,
'links' => [
'self' => $selfUrl,
'first' => $firstUrl,
'prev' => $prevUrl,
'next' => $nextUrl,
'last' => $lastUrl,
],
],
'pagination' => $pagination,
]);
}
}

View file

@ -25,10 +25,8 @@ final readonly class IncoSheetsShowResponse implements ApiResponse
#[\Override]
public function present(): JsonResponse
{
$dto = IncoSheetDto::fromFindOutput($this->view->output);
return response()->json([
'incoSheet' => get_object_vars($dto),
'incoSheet' => IncoSheetDto::fromFindOutput($this->view->output),
]);
}
}

View file

@ -0,0 +1,53 @@
<?php
declare(strict_types=1);
namespace Tests\Unit\Presentation\Api\V1\Dto;
use League\Uri\Http;
use Presentation\Api\V1\Dto\PaginationDto;
covers(PaginationDto::class);
describe('PaginationDto Unit Tests', function (): void {
it('creates pagination metadata and links correctly', function (): void {
// GIVEN
$baseUri = Http::new('http://localhost/api/v1/employees');
// WHEN
$dto = PaginationDto::create(
page: 2,
pageSize: 10,
totalItems: 35,
baseUri: $baseUri,
);
// THEN
expect($dto->page)->toBe(2)
->and($dto->pageSize)->toBe(10)
->and($dto->totalItems)->toBe(35)
->and($dto->totalPages)->toBe(4)
->and($dto->links['self'])->toBe('http://localhost/api/v1/employees?page=2&pageSize=10')
->and($dto->links['first'])->toBe('http://localhost/api/v1/employees?page=1&pageSize=10')
->and($dto->links['prev'])->toBe('http://localhost/api/v1/employees?page=1&pageSize=10')
->and($dto->links['next'])->toBe('http://localhost/api/v1/employees?page=3&pageSize=10')
->and($dto->links['last'])->toBe('http://localhost/api/v1/employees?page=4&pageSize=10');
});
it('handles first page correctly with null prev link', function (): void {
// GIVEN
$baseUri = Http::new('http://localhost/api/v1/employees');
// WHEN
$dto = PaginationDto::create(
page: 1,
pageSize: 10,
totalItems: 15,
baseUri: $baseUri,
);
// THEN
expect($dto->links['prev'])->toBeNull()
->and($dto->links['next'])->toBe('http://localhost/api/v1/employees?page=2&pageSize=10');
});
});