Introduction

This page lists all the breaking changes introduced by each major version.

There are multiple ways to mitigate these changes, but the safest is to follow the starter project structure and upgrade step by step.

For versioning information, please see Versioning.

Upgrading from 2.x to 3.x

Upgrading from version 2.x to 3.x is a major release. It adds support for PHP 8.5 while retaining PHP 8.4 compatibility, so the runtime upgrade itself is straightforward — the starter's Dockerfile moves from the PHP 8.4 image to the PHP 8.5 image.

The breaking changes come from bundled dependencies being upgraded to new major versions.

Changes include:

PHP 8.5 support. The starter now runs on the PHP 8.5 FrankenPHP image. PHP 8.4 remains fully supported.
CuyZ Valinor upgraded from 1.x to 2.x. Only affects you if you use Valinor directly (for example in a DTO). The standard mapping flow — (new MapperBuilder())->mapper()->map(...) with Source::array() — is unchanged. Breaking removals: MapperBuilder::alter() (replaced by mapper converters), MapperBuilder::enableFlexibleCasting(), and MapperBuilder::warmup() (renamed to warmupCacheFor()). The Normalizer API moved to a dedicated NormalizerBuilder. See the Valinor upgrade guide.
Zircote Swagger PHP upgraded from 5.x to 6.x. If you document your API with PHP attributes (#[OA\Schema], #[OA\Property], ...) — as the starter does — no changes are needed. The legacy doctrine-annotation style is deprecated in 6.x; migrate any remaining annotations to attributes.
Dependency constraints widened. Core is now 3.0. All drivers and middlewares now accept kipchak/core: ^2 || ^3, so you can adopt core 3.x incrementally.
New: response metadata envelope. Http\Response::json() accepts an optional meta argument for pagination, counts, and similar endpoint metadata. It sits between status and data in the response envelope. This is additive and fully backward compatible.

Breaking driver releases

Three drivers had their underlying SDKs upgraded across breaking major versions and were released as new majors of their own. If you use any of them, bump your constraint to allow the new major (^1 || ^2):

kipchak/driver-http 2.0 — upgraded illuminate/http from 12.x to 13.x. The driver's public API is unchanged.
kipchak/driver-anthropic 2.0 — upgraded anthropic-ai/sdk from 0.6 to 0.36. The driver's max_retries config key and message API are unchanged. If you call raw() to use the SDK directly, review the SDK's changes.
kipchak/driver-openai 2.0 — upgraded openai-php/client from 0.10 to 0.20. The driver API is unchanged. If you call raw(), review the client's changes.

Upgrading from 1.x to 2.x

Upgrading from version 1.x to 2.x is a major release and has breaking changes.

It introduces interfaces for writing Drivers and Middleware and slightly changes the bootstrapping process.

Changes include:

Package name has changed from mamluk/kipchak to kipchak/core
Namespace has changed from Mamluk\Kipchak to Kipchak\Core
The project has been restructured to be more modular and has thus introduced:
- Drivers
- Middleware
Interfaces have been added to make it easier to write drivers and middlewares
The starter repository has been updated to use the new structure
Middlewares and Drivers now initialise with a single method and must be registered in middlewares/middlewares.php and drivers/drivers.php, respectively.
The base controller name has changed from Slim to Base and now ONLY includes the Logger driver.
Bootstrapping has been simplified for faster boot times.
The html/index.php entrypoint now uses FrankenPHP's worker mode.
You will have to update your composer.json file to use just those drivers and middlewares you need, as opposed to everything that was bundled into the core before.
Instead of using $container->get() to now get any dependencies in the container, use Driver::get().

Upgrading from 0.x to 1.x

Upgrading from version 0.x to 1.x is a major release and has breaking changes.

This means:

Support for PHP 8.4.
You will have to manually use the session management middleware as it has been removed from the core.
Zircote Swagger is now part of the core.
Doctrine has been upgraded to version 3.5+. This may result in breaking changes, especially:
- for migrations and if you were using / extending some core Doctrine capabilities without specifying return types.
- for the Doctrine ORM if you use Doctrine proxies (in this case you will need to remove the proxies.sh script from your bin/ folder and remove its execution from your Dockerfile). Proxies are generated automatically in 3.5+ at runtime as needed.
Upgrade to the new Doctrine cli (which is available in the bin/ folder of the starter project) created for Kipchak. The prebuilt cli command was removed in Doctrine 3.5.