All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Hand off a long task.

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

The same job on other stacks

Keep reading