Moving to Kipchak

Moving to Kipchak

Move a JSON API to Kipchak from Laravel, Slim or FastAPI

Choose your framework

Each guide takes one small API, a bookshelf, as a developer of that framework would write it, and moves it to Kipchak one part at a time: routes, validation, the database, responses, errors, the OpenAPI document, tests and running it.

You have an API inReadWhat the move is
LaravelMoving to Kipchak from LaravelFrom Eloquent, form requests and API resources, to Doctrine and one DTO
Slim 4Moving to Kipchak from SlimKipchak is built on Slim 4: your routes and middleware carry over, and Kipchak adds the rest
FastAPIMoving to Kipchak from FastAPIFrom Python to PHP: Pydantic and SQLModel to DTOs and Doctrine

Both versions of the bookshelf in each guide pass the same suite of 47 checks over HTTP, and every statement about the other framework links its documentation for the version used and was checked against it running.

What Kipchak gives you

Kipchak is built for JSON APIs, with the API's contract at the centre of the code. Each guide shows these from the bookshelf, with the commands and their output:

  • The contract in one class. A DTO's Field rules are enforced on request bodies and written into the OpenAPI document, so the two cannot drift apart.
  • A document you can check. kipchak openapi:validate --strict checks the document against the OpenAPI specification and against the routes, and can gate a release in CI.
  • One shape for every response. Successes and errors alike arrive as {"code", "status", "data"}, with each field's problems in meta.errors for an invalid body.
  • A whole resource in one command. kipchak make:resource writes the DTO, model, controller, routes and tests, which pass, and whose operations are in the document.
  • Drivers and middleware, configured and in order. kipchak add installs a driver or middleware, such as JWT validation or rate limiting, copies its configuration and initialises it in the right place.
  • Worker mode from the start. FrankenPHP keeps the API in memory and each worker serves many requests.
  • Your assistant knows the conventions. The starter's AGENTS.md and the Kipchak agent skill.

What changes for your clients, whichever framework you come from

Each guide also has a table of what your API's clients will notice. Four rows appear in all three:

  • Every response is in Kipchak's envelope: {"code": 200, "status": "OK", "data": ...}, and every error {"code", "status", "data"}.
  • An invalid body is 400, not 422, with each field's problems in meta.errors.
  • Types are strict: a number sent as a string, such as "year": "1871", is refused.
  • CORS headers: none until you list the browser applications' origins in CORS_ALLOWED_ORIGINS; the starter then answers their preflight requests. See CORS.

The paths, the methods, the fields and their rules, and the success and 404 statuses stay as they are. If your clients cannot change when you move, tell them which shapes change, or bring the change in under a new version of the API (see Versioning).

Before you start

  • Create the project from the starter project, and read Getting started.
  • Kipchak runs on FrankenPHP in worker mode: the API boots once and serves many requests, so nothing that belongs to one request may stay in a static property or a long-lived service.
  • The Kipchak CLI adds drivers and middleware, and make:resource writes a resource in the starter's conventions.
Previous
Consumer Identity