Starter Project

The starter project lays out the structure of a working API and demonstrates the use of Drivers and Middleware.

You can use it to get started, simply remove from composer.jsom, the config directory, the routes directory and from the api/Controllers directory what you don't need.

The structure of your API

Here's how the starter project is laid out:

|-- api
|   |-- Controllers // Sample Controllers that demonstrate use of Middlewares and Drivers
|   |   |-- Info.php
|   |   |-- Status.php
|   |   `-- v1
|   |       |-- Authenticated.php // Demonstrates use the JWKS and API Key Middlewares
|   |       |-- Cache.php // Demonstrates use of the Memcached and Filecache Drivers
|   |       |-- Couch.php // Demonstrates use of the CouchDB Driver
|   |       |-- Doctrine.php // Demonstrates use of the Doctrine Driver
|   |       `-- Sultans.php // Demonstrates use of DTOs within Kipchak
|   |-- DataTransferObjects // Sample DTOs to help you get started
|   |   `-- v1
|   |       `-- MamlukSultan.php
|   |-- Drivers // A directory to place any drivers you code inside your project
|   |-- Entities 
|   |   |-- CouchDB // A directory to place any CouchDB related JSON Entities to use with DTOs
|   |   `-- Doctrine 
|   |       `-- Primary // This folder should contain any Doctrine Entities for the 'Primary' Entity Manager'
|   |-- Middlewares // A directory to place any middleware you code inside your project
|   `-- Models // A directory to place any models for business logic in your API
|-- bin
|   `-- doctrine // The Doctrine CLI, ready to work with Kipchak's Doctrine driver (compatible with Doctrine 4.x)
|-- composer.json
|-- composer.lock
|-- config
|   |-- kipchak.api.php        // The mandatory configuration file for Kipchak
|   |-- kipchak.auth.jwks.php  // Configuration file for the JWKS Middleware. Only needed if you use the JWKS Middleware
|   |-- kipchak.auth.key.php   // Configuration file for the API Key Middleware. Only needed if you use the API Key Middleware
|   |-- kipchak.couchdb.php    // Configuration file for the CouchDB Driver. Only needed if you use CouchDB Driver
|   |-- kipchak.doctrine.php   // Configuration file for the Doctrine Driver. Only needed if you use Doctrine Driver
|   |-- kipchak.memcached.php  // Configuration file for the Memcached Driver. Only needed if you use Memcached Driver
|   |-- kipchak.rabbitmq.php   // Configuration file for the RabbitMQ Driver. Only needed if you use Rabbit MQ Driver
|   `-- kipchak.subashi.php    // Configuration file for the Subashi WAF Middleware. Only needed if you use the Subashi WAF Middleware
|-- docker-compose.yml
|-- Dockerfile
|-- drivers
|   `-- drivers.php             // A file to initialise the drivers. Any other .php file in this directory will also be loaded when Kipchak bootstraps
|-- etc
|   |-- caddy
|   |   `-- Caddyfile           // The Caddy / FrankenPHP configuration file for your API
|   |-- rabbitmq
|   |   `-- rabbitmq.conf       // Rabbit MQ Config, only needed if you use Rabbit MQ
|   `-- unit
|-- html
|   `-- index.php               // The entrypoint for your API
|-- LICENSE
|-- middlewares
|   `-- middlewares.php         // A file to initialise the drivers. Any other .php file in this directory will also be loaded when Kipchak bootstraps
|-- README.md
`-- routes                      // This folder and any subdirectories contain your HTTP endpoints
    |-- info.php
    |-- status.php
    `-- v1
        |-- authenticated.php
        |-- cache.php
        |-- couch.php
        `-- sultans.php

Lifecycle of a request

When a request comes into your Kipchak API, it follows this lifecycle:

1. Entry Point - The request hits html/index.php, which bootstraps Kipchak
2. ** Bootstrapping** - Kipchak loads what is in the drivers, middlewares and routes directories.
3. Routing - Kipchak matches the request URI and HTTP method to a route definition in the routes directory
4. Middleware Execution - Any global middleware or middleware attached to the route runs in order, validating authentication, checking rate limits, or performing other pre-processing
5. Controller Invocation - If middleware allows, the route's controller method is called
6. Driver Usage - The controller can use drivers (database, cache, message queues), models, entities, DTOs, etc. to perform business logic
7. Response - The controller returns a response, which Kipchak serializes and sends back to the client

Kipchak handles all the underlying HTTP mechanics, letting you focus on implementing your API's logic.

The api Directory

The api directory contains the core application code for your API:

• Controllers - Classes that handle requests and return responses. Each controller method corresponds to a route endpoint
• DataTransferObjects - DTOs that define the structure of data flowing through your API, providing validation and type safety
• Drivers - Custom drivers specific to your application
• Entities - Data models for your persistence layer, organized by driver type (Doctrine, CouchDB, etc.)
• Middlewares - Custom middleware specific to your application
• Models - Business logic classes that sit between controllers and data access, keeping controllers thin and logic reusable

This structure follows a clean separation of concerns, making your codebase maintainable and testable.

The drivers Directory

The drivers directory at the project root contains the drivers.php file, which is automatically loaded during Kipchak's bootstrap process. This is where you initialize drivers that will be used across your API.

Any additional .php files you create in this directory will also be automatically loaded, allowing you to organize driver initialization across multiple files if needed. For example:

• drivers.php - Main driver initialisation
• database.php - Database drivers initialisation e

The middlewares Directory

The middlewares directory at the project root contains the middlewares.php file, which is automatically loaded during Kipchak's bootstrap process. This is where you initialize and register middleware that will be used across your API.

Any additional .php files you create in this directory will also be automatically loaded, allowing you to organize middleware initialization across multiple files if needed. For example:

• middlewares.php - Main middleware initialisation
• auth.php - Authentication middleware setup
• validation.php - Custom validation middleware

Installed middleware like JWKS authentication and API Key authentication are configured here, as well as any custom middleware you create in the api/Middlewares directory.

The config Directory

The config directory contains configuration files for Kipchak and its drivers/middleware. Each configuration file follows the naming convention kipchak.<feature>.php:

• kipchak.api.php - Core API configuration (required) - defines CORS settings, error handling, and general API behavior
• kipchak.auth.jwks.php - JWKS authentication middleware configuration (optional) - defines token validation rules and JWKS endpoints
• kipchak.auth.key.php - API key authentication middleware configuration (optional) - defines valid API keys and permissions
• kipchak.couchdb.php - CouchDB driver configuration (optional) - database connections and settings
• kipchak.doctrine.php - Doctrine ORM configuration (optional) - entity managers, database connections, and mapping
• kipchak.memcached.php - Memcached driver configuration (optional) - cache server connections
• kipchak.rabbitmq.php - RabbitMQ driver configuration (optional) - message queue connections and exchanges
• kipchak.subashi.php - Subashi WAF middleware configuration (optional) - web application firewall rules

Only include configuration files for the features you're actually using. Kipchak will only load configurations for active drivers and middleware.

Running the API

Make sure you have any environment variables you need set up in your .env file or the docker-compose.yml file. Then all you need to is run:

docker compose up --build --watch

This will start the API and automatically rebuild it when you make changes to the source code.