Kipchak Examples

Working examples of the free Kipchak drivers and middleware: one route for each, with its configuration, and a Docker Compose service for each one that needs a server.

To start a new API, use the starter project instead: composer create-project kipchak/starter my-api. Copy what you need from here into it; each package's page on kipchak.dev explains its installation and configuration.

For complete documentation, visit https://kipchak.dev.

Install

git clone https://1x.ax/mamluk/kipchak/examples.git
cd examples
composer install

Running with Docker

This repository ships with a docker-compose.yml that brings up the full stack:

docker compose up

This starts the following services:

Hot-reload is enabled via Docker Compose watch — changes to your code restart the worker automatically.

CouchDB first-run setup

CouchDB requires a _users database on first start. Run once after docker compose up:

curl -X PUT http://api:api@localhost:5984/_users
curl -X PUT http://api:api@localhost:5984/api

Project Structure

├── api/
│   ├── Controllers/        # HTTP request handlers, versioned under v1/, v2/, etc.
│   ├── DataTransferObjects/ # Input/output contracts, versioned alongside controllers
│   ├── Entities/           # Database schema representations (Doctrine ORM, CouchDB)
│   ├── Middlewares/        # Custom per-project middleware
│   └── Models/             # Business logic
├── config/                 # PHP config files (one per driver/middleware)
├── drivers/
│   └── drivers.php         # Driver initialisation order
├── middlewares/
│   └── middlewares.php     # Global middleware registration
├── routes/                 # Route definitions, versioned under v1/, v2/, etc.
└── html/
    ├── index.php           # FrankenPHP worker-mode entry point
    └── index.nonworker.php # Standard PHP entry point

Philosophy

Kipchak has an opinionated view of how API layers should be structured. These definitions follow the natural flow of a request.

• Routes — Entry points into your API. Defined in routes/, versioned by directory (e.g. routes/v1/). They declare the URL, HTTP verb, and which controller handles the request.

• Middlewares — Reusable logic applied before a request reaches a controller or before a response is sent. Global middlewares are registered in middlewares/middlewares.php. Route-level middlewares are applied in the route file itself.

• Controllers — Decide how to process a request. Versioned alongside routes. A controller receives the HTTP request, passes it to a Data Transfer Object for validation, then hands off to a Model.

• Data Transfer Objects (DTOs) — Represent data flowing in and out of your API. DTOs must be versioned — they form the API contract. Validating input here keeps controllers thin.

• Models — Business logic. The layer between your controllers and your data stores or third-party services.

• Entities — Code representations of your data schema. Doctrine entities live in api/Entities/Doctrine/. CouchDB document shapes live in api/Entities/CouchDB/.

• Dependencies — Common classes registered in the DI container so they are instantiated once per request. Drivers are Kipchak's built-in dependency layer, initialised in drivers/drivers.php.

Drivers

Drivers are adapters for external services. They are initialised in drivers/drivers.php and registered into the DI container. Config, Logger, and HTTP are initialised first as other drivers depend on them.

It includes and demonstrates the following drivers:

Core

Data & Messaging

AI

DNS

Middlewares

Middlewares are registered in middlewares/middlewares.php and apply globally to every request.

Authentication middlewares are disabled by default ('enabled' => false) so the demo routes are accessible without credentials. Set 'enabled' => true in the relevant config file to activate.

It also includes a demo of per-route middleware usage:

Custom per-project middlewares can be added to api/Middlewares/ and registered in middlewares/middlewares.php or applied directly in a route file.

Configuration

All configuration lives in the config/ directory as PHP files returning arrays. The Config driver loads every file in this directory at boot and makes them available via Config::get('filename-without-extension').

Environment variables are read using the env() helper:

env('ENV_VAR_NAME', 'default-value')

Writing Custom Controllers

Controllers extend Kipchak\Core\Components\Controllers\Base, which provides:

• $this->container — the DI container
• $this->logger — the PSR-3 logger

namespace Api\Controllers\v1;

use Kipchak\Core\Components\Controllers;
use Kipchak\Core\Components\Http;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

class Example extends Controllers\Base
{
    public function get(ServerRequestInterface $request, ResponseInterface $response, array $args): ResponseInterface
    {
        return Http\Response::json($response, ['hello' => 'world'], 200);
    }
}

Writing Custom Middlewares

Custom middlewares implement __invoke(ServerRequestInterface $request, RequestHandlerInterface $handler) and can be applied globally in middlewares/middlewares.php or to a specific route group.

$app->group('/v1', function (RouteCollectorProxy $group) {
    $group->get('/protected', [Controllers\v1\Example::class, 'get'])
          ->add(new MyCustomMiddleware());
});

Registering Custom Dependencies

Add any class or service to the DI container in drivers/drivers.php:

$container->set('my.service', function (ContainerInterface $c) {
    return new MyService();
});

Retrieve it anywhere you have access to the container:

$service = $this->container->get('my.service');