# Add Cursor Pagination to a Slim 4 API

Yes. An agent adds keyset pagination to your Slim 4 list action: a limit and an opaque cursor on the query string, a next cursor in the payload.

[Run this on Rush](https://cloud.getrush.ai/run/add-cursor-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 action, the repository and the payload class before changing any of them, because in a Slim app built on the skeleton the list route is three small classes. In an API laid out like slimphp/Slim-Skeleton, `app/routes.php` groups `/users` with `ListUsersAction` on `GET /users` and `ViewUserAction` on `GET /users/{id}`; `ListUsersAction::action()` calls `$this->userRepository->findAll()` and hands the array to `respondWithData`, which wraps it in an `ActionPayload` with `statusCode` and `data` and writes it as pretty-printed JSON. `UserRepository` in `src/Domain/User/` is an interface with `findAll()` and `findUserOfId()`, `app/repositories.php` autowires it to `InMemoryUserRepository`, whose constructor holds five users keyed by id, and `composer.json` pins `slim/slim` 4.12, `php-di` 6.4, `monolog` 2.9, PHPUnit 9.6, phpstan and phpcs on PHP 7.4 to 8.x. The tests in `tests/Application/Actions/User/` build the real app through `TestCase::getAppInstance()`, prophesize the repository and compare the JSON body to a serialised `ActionPayload`.

It extends the interface rather than adding a sibling: `findPage(int $limit, ?int $afterId): array` on `UserRepository`, implemented in `InMemoryUserRepository` by sorting the users by id, keeping those above `$afterId` and slicing `$limit + 1` so the action can tell whether a next page exists without a second query. `findAll()` stays for `ViewUserAction`'s neighbours and any other caller. `ListUsersAction` reads `limit` and `after` from `$this->request->getQueryParams()`: `limit` defaults to 20 and is capped at 100, anything that is not a positive integer throws the `HttpBadRequestException` the base `Action` already uses for a bad argument, and `after` is an opaque base64url string that decodes to the last id of the previous page. A cursor that does not decode is the same 400.

The payload gains the cursor without breaking the shape clients read today. `ActionPayload` gets an optional `meta` array that `jsonSerialize()` emits only when it is set, so `GET /users` still answers `{"statusCode": 200, "data": [...]}` and a paged response adds `"meta": {"nextCursor": "..."}` on every page but the last. The agent documents in the pull request why the cursor is on `id`: it is the key the in-memory store and `findUserOfId` already use, and a database-backed implementation of the same interface can translate it to `WHERE id > :after ORDER BY id LIMIT :n` without changing the action.

It writes the tests the way the existing ones are written: `ListUserActionTest` gains cases that prophesize `findPage(2, null)` and `findPage(2, 2)` and assert the `meta.nextCursor` on the first page and its absence on the last, a case for `limit=500` capped to 100, and one for a bad `after` expecting a 400 from the app's `HttpErrorHandler`; `InMemoryUserRepositoryTest` gains ordering and boundary cases. Then it runs what `.github/workflows/tests.yml` runs, `vendor/bin/phpcs`, `vendor/bin/phpstan` and `vendor/bin/phpunit`, fixes any PSR-12 or level issue it introduced, starts the app with `composer start` and pastes a walk through `/users?limit=2` into the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add cursor pagination to the users list in this Slim 4 API. Read composer.json, app/routes.php, app/repositories.php, src/Application/Actions/Action.php, src/Application/Actions/ActionPayload.php, src/Application/Actions/User/ListUsersAction.php, src/Domain/User/UserRepository.php, src/Infrastructure/Persistence/User/InMemoryUserRepository.php, tests/TestCase.php, tests/Application/Actions/User/ListUserActionTest.php and .github/workflows/tests.yml first. Add findPage(int $limit, ?int $afterId): array to the UserRepository interface and implement it in InMemoryUserRepository, sorted by id and returning limit plus one rows; keep findAll. Make ListUsersAction read limit (default 20, max 100) and after (an opaque base64url cursor holding the last id) from the query string, throwing HttpBadRequestException on anything invalid, and give ActionPayload an optional meta array emitted only when set, carrying nextCursor when another page exists. Keep the existing response shape otherwise. Add PHPUnit cases in the existing style for the first and last page, the cap and a bad cursor, and repository cases for ordering and boundaries. Run phpcs, phpstan and phpunit as the workflow does, start the app with composer start, walk /users?limit=2 to the end and paste the responses into the pull request. Change nothing in ViewUserAction.",
  "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` and `ActionPayload.php`, and adds cases to `ListUserActionTest.php` and `InMemoryUserRepositoryTest.php`. Its description quotes the `phpunit` summary, the `phpstan` and `phpcs` results, and three consecutive responses to `/users?limit=2` showing `meta.nextCursor` on the first two and only `data` on the third.

`ViewUserAction`, the routes and the error handler are untouched, and an unpaged `GET /users` now answers the first 20 users by id with a cursor rather than all of them, which the description names as the one visible change. The interface change means any other `UserRepository` implementation in a real project needs `findPage`, which the description also calls out.

Before merging, a reviewer settles the default page size, decides whether `meta` is the right place for the cursor in their API conventions, and plans the database-backed `findPage` for the repository implementation they use in production.

## Run it on every list route without a limit

An engineer who noticed the list growing starts this from the terminal with this body and goes back to their work. The run reads the real action, interface and payload class, so the change follows the skeleton's own pattern, an interface method, an action and a payload field, rather than bolting a query-string parser onto the route closure.

Send a `request_id`, a UUID, with the body so a retried start returns the run it already began. The pull request link is on the run's `GET /o/{org}/sessions/{id}` answer once it is open, and a key with a `webhook_url` hears `run.completed` when the turn ends. A team with several Slim services sends one body per repository, each with its own `resources` URL.

## Why run it on Rush?

A pagination change in a Slim skeleton touches an interface, an action, a payload class and the tests that compare serialised payloads, and phpstan and phpcs run on every push, so a change that is right in spirit still fails CI on a missing return type or a PSR-12 line. The agent runs the three tools in its own sandbox the way the workflow does, fixes what it introduced, and starts the app to walk the pages, so the pull request arrives with the same checks already green and the responses pasted.

The transcript keeps each tool run and each request, so the reviewer reads what phpstan said and what the third page returned without checking out the branch. Several services can be paginated at once, each in its own sandbox, and nothing merges until a person reads the diff.

## Frequently asked questions

### Why put the cursor in meta and not in a header?

The skeleton already wraps every response in `ActionPayload`, and its tests compare the whole serialised payload, so a `meta` key that appears only when set is the smallest change that fits the existing shape and the existing tests. A `Link` header is equally valid; the pull request names the two places to change if the team prefers it.

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

Because `ListUsersAction` only sees what `UserRepository` returns. Slicing `findAll()` in the action would still load every row, which defeats the purpose on a database-backed repository. A `findPage` method lets the in-memory implementation slice and a SQL implementation write `WHERE id > :after ORDER BY id LIMIT :n`, with the action unchanged.

### What does an invalid limit or cursor return?

A 400 through the app's existing `HttpErrorHandler`, because the action throws `HttpBadRequestException`, the same exception the base `Action` uses for a missing route argument. The error body keeps the `ActionPayload` shape with an `error` block, and a test asserts it.

### Does it change ViewUserAction or the routes?

No. `ViewUserAction` keeps calling `findUserOfId`, `app/routes.php` is untouched, and the diff is limited to the list action, the repository interface and implementation, the payload class and the tests, as the prompt asks.

### Will phpstan and phpcs still pass?

The agent runs both at the versions `composer.json` pins before opening the pull request and fixes anything it introduced, since `tests.yml` runs them on PHP 8.1 alongside PHPUnit on 7.4 to 8.2. The new code uses only typed parameters and return types that PHP 7.4 accepts, so the matrix stays as it is.

## More Slim jobs

- [Add Database Migrations to a Slim 4 App](https://getrush.ai/run/add-database-migrations/slim/)
- [Add a Dockerfile to a Slim 4 App](https://getrush.ai/run/add-dockerfile/slim/)
- [Add a Health Check Endpoint to a Slim 4 App](https://getrush.ai/run/add-health-checks/slim/)

## The same job on other stacks

- [Add Cursor Pagination to a SQLAlchemy API](https://getrush.ai/run/add-cursor-pagination/sqlalchemy/)
- [Add Cursor Pagination to sqlc Queries](https://getrush.ai/run/add-cursor-pagination/sqlc/)
- [Add Cursor Pagination to a SQLModel API](https://getrush.ai/run/add-cursor-pagination/sqlmodel/)

## 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/)
