# Add Pagination to a Slim 4 List Endpoint

Yes. An agent adds page and per-page query parameters to your Slim 4 list action, validates them, extends the repository, updates the PHPUnit tests, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-pagination/slim/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the endpoint from the route to the repository. In an app laid out like slimphp/Slim-Skeleton, `app/routes.php` mounts `ListUsersAction` at `GET /users` inside a `/users` group, next to `ViewUserAction` at `/{id}`. `src/Application/Actions/User/ListUsersAction.php` is four lines of work: it calls `$this->userRepository->findAll()`, logs "Users list was viewed." and returns `respondWithData($users)`, which the base `Action` class wraps in an `ActionPayload` of `statusCode` and `data` and serialises with `JSON_PRETTY_PRINT`. `src/Domain/User/UserRepository.php` is an interface with `findAll(): array` and `findUserOfId(int $id): User`, bound in `app/repositories.php` to `InMemoryUserRepository`, which holds five users keyed by id and returns `array_values` of them. The base `Action` already has `resolveArg` for route arguments and throws `HttpBadRequestException` for a missing one, but nothing reads query parameters. `tests/Application/Actions/User/ListUserActionTest.php` prophesies `findAll()` once and compares the whole JSON body to an expected `ActionPayload`.

The change starts at the interface, since the in-memory repository is the stand-in for a database one. `UserRepository` gains `findPage(int $offset, int $limit): array` and `countAll(): int`, with `findAll()` left in place because nothing else should break. `InMemoryUserRepository` implements them with `array_slice` over `array_values($this->users)` and `count`. `ListUsersAction` reads `page` and `per_page` from `$this->request->getQueryParams()`, defaulting to 1 and 20, and refuses anything that is not a positive integer, or a `per_page` above 100, with the same `HttpBadRequestException` the base class already uses, which `HttpErrorHandler` turns into the skeleton's JSON error shape with a 400. The response keeps `statusCode` and `data` and adds, inside `data`, `items`, `page`, `perPage` and `total`, so a client that read a bare array before has one key to change and a client that wants the next page can compute it.

The agent keeps the skeleton's conventions where they exist. `declare(strict_types=1)` stays at the top of every file, the new interface methods carry the same docblocks as the old ones, and the action's log line gains the page number. It does not add a pagination library: the skeleton has no database, and a `LIMIT`/`OFFSET` pair is the whole contract a database repository will need to implement later.

The check is the existing suite plus the cases the change creates. The agent updates `ListUserActionTest` to prophesy `findPage(0, 20)` and `countAll()`, adds tests for `?page=2&per_page=2` against the five default users, for `page=0`, `per_page=abc` and `per_page=500` returning 400, and adds `findPage` cases to `InMemoryUserRepositoryTest`. It runs `vendor/bin/phpunit`, `vendor/bin/phpcs` against the PSR-12 ruleset in `phpcs.xml`, and `vendor/bin/phpstan` at the level 4 set in `phpstan.neon.dist`, the three commands `.github/workflows/tests.yml` runs, and quotes all three in the pull request.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add pagination to the GET /users endpoint of this Slim 4 app. Read app/routes.php, src/Application/Actions/Action.php, src/Application/Actions/User/ListUsersAction.php, src/Domain/User/UserRepository.php, src/Infrastructure/Persistence/User/InMemoryUserRepository.php, src/Application/Handlers/HttpErrorHandler.php, the tests under tests/ and .github/workflows/tests.yml first. Add findPage(int $offset, int $limit): array and countAll(): int to the UserRepository interface and implement them in InMemoryUserRepository with array_slice and count, keeping findAll. In ListUsersAction read page and per_page from the query string with defaults 1 and 20, reject non-positive or non-integer values and per_page above 100 with HttpBadRequestException, and respond with data containing items, page, perPage and total. Update ListUserActionTest for the new repository calls, add tests for a second page and for each rejected value, and add findPage tests to InMemoryUserRepositoryTest. Run vendor/bin/phpunit, vendor/bin/phpcs and vendor/bin/phpstan and fix anything they report. Open a pull request that quotes all three outputs and shows the new response shape.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `UserRepository.php`, `InMemoryUserRepository.php`, `ListUsersAction.php`, `ListUserActionTest.php` and `InMemoryUserRepositoryTest.php`, and touches no route, middleware or container wiring. Its description shows one response body for `GET /users?page=2&per_page=2` with the `items`, `page`, `perPage` and `total` keys, one 400 body for `per_page=abc`, and the `phpunit`, `phpcs` and `phpstan` output.

A reviewer checks the defaults and the cap against what their clients send, confirms the error path returns the skeleton's `ActionError` shape rather than a bare message, and decides whether the old `findAll()` should stay on the interface. If the project has a database repository, the reviewer sees the two methods it must implement, with the in-memory version as the reference.

Clients get the same `statusCode` and `data` envelope, a bounded page of users under `items`, and enough in the response to build the next request without a second call.

## Run it on every Linear issue labelled api-pagination

An automation on the Project with a `linear` trigger on `linear.issue.labeled` and the label `api-pagination` starts a read-only run that reads the issue and posts a plan as a comment on it: which action, which repository methods, which tests. The change itself starts from the reader's own server, which sends this body to `POST /o/{org}/sessions` with the issue's URL in `resources` beside the repository, so the issue text is in the prompt, and a `request_id` that is a UUID v5 of the issue id, so a retried call returns the run it already started.

Each run reads that app's own list action, so an endpoint backed by PDO gets `LIMIT` and `OFFSET` in its query and a `COUNT(*)` beside it, while one on an in-memory repository gets `array_slice`, with the same query parameters and the same response shape across the two.

## Why run it on Rush?

Pagination touches an interface, its implementations, an action and the tests that pin its JSON byte for byte, and the skeleton's CI runs three tools that each reject a different kind of mistake. The agent makes the change and runs PHPUnit, PHP_CodeSniffer and PHPStan in its own sandbox with the project's own configuration, and keeps the output with the pull request, so the review is about the contract and not about whether the build passes.

List endpoints that return whole tables are usually found several at a time. The same request runs across every service at once, each in its own sandbox, each getting parameters and a response shape that match that service's conventions, and each with the proof that its own suite still passes.

## Frequently asked questions

### Does the response shape change for existing clients?

The envelope of `statusCode` and `data` stays. What was a bare array under `data` becomes an object with `items`, `page`, `perPage` and `total`, so a client reads `data.items` where it read `data`. The pull request shows one full body so the change is visible before merging.

### Why extend the interface instead of slicing in the action?

Slicing in the action would work for the in-memory repository and load the whole table from a database one. `findPage` and `countAll` give a database implementation a `LIMIT`, an `OFFSET` and a `COUNT` to run, and the action stays the same whichever repository is bound in `app/repositories.php`.

### What happens with page=0 or per_page=500?

Both get a 400 through the `HttpBadRequestException` the base `Action` already uses, which `HttpErrorHandler` renders in the skeleton's JSON error shape. The cap of 100 is a constant in the action and the pull request names it.

### Will phpstan and phpcs still pass?

The agent runs both with the project's own `phpstan.neon.dist` and `phpcs.xml`, the same way `.github/workflows/tests.yml` does, and fixes what they report before opening the pull request. The output is quoted in the description.

## More Slim jobs

- [Add Prometheus Metrics to a Slim 4 App](https://getrush.ai/run/add-prometheus-metrics/slim/)
- [Add Rate Limiting to a Slim 4 App](https://getrush.ai/run/add-rate-limiting/slim/)
- [Add Request ID Logging to a Slim App](https://getrush.ai/run/add-request-id-logging/slim/)

## The same job on other stacks

- [Add Message History Pagination to a Socket.IO Chat](https://getrush.ai/run/add-pagination/socket-io/)
- [Add Pagination to a Wagtail Blog Index](https://getrush.ai/run/add-pagination/wagtail/)
- [Add Pagination to an aiohttp App](https://getrush.ai/run/add-pagination/aiohttp/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
