kipchak

Que fait kipchak ?

Kipchak est un kit de développement d'API pour PHP 8.4 et versions ultérieures. Il s'agit de Slim Framework 4 avec une structure fixe : une séquence d'amorçage, des pilotes pour les services externes, des middleware, et des conventions pour les routes, les contrôleurs, les objets de transfert de données (DTO) et OpenAPI. Il fonctionne sur FrankenPHP en mode worker. Documentation : https://kipchak.dev ; index pour les modèles de langage : https://kipchak.dev/llms.txt.

Kipchak n'est ni Laravel ni Symfony. Il n'y a pas de facades, de helpers globaux, de fournisseurs de services, d'Eloquent, de Blade, de contrôleurs auto-câblés ou de conventions cachées. Tout ce qu'un point de terminaison fait est visible dans le code propre du projet. N'écrivez pas request(), response()->json(), config('...'), app(), Route::get(), DB::, Cache:: ou tout autre helper de framework : aucun d'entre eux n'existe ici.

Reconnaître un projet Kipchak

Le fichier composer.json nécessite kipchak/core, et le projet possède ces dossiers. Si le projet a un fichier AGENTS.md, lisez-le en premier : il décrit ce projet.

Chemin	Contenu
routes/	Fichiers de routes. Chaque fichier .php qu'il contient, à n'importe quelle profondeur, est chargé au démarrage. Les routes versionnées vont dans routes/v1/.
api/Controllers/	Contrôleurs, namespace Api\Controllers ; les versionnés dans v1/ (Api\Controllers\v1).
api/DataTransferObjects/	DTO, versionnés comme les contrôleurs. Ils constituent le contrat de l'API.
api/Models/	Logique métier.
api/Entities/Doctrine/<Connection>/	Entités Doctrine, lorsque le pilote Doctrine est utilisé.
api/Middlewares/	Middleware PSR-15 propres au projet.
api/OpenApi/Definition.php	Titre, version, serveurs et réponses partagées de l'OpenAPI.
api/Utils/	Code partagé dans toute l'API.
config/	Un fichier PHP par pilote ou middleware, retournant un tableau, nommé kipchak.<nom>.php.
drivers/drivers.php	Initialise les pilotes, dans l'ordre.
middlewares/middlewares.php	Initialise les middleware appliqués à chaque requête : Error::initialise($app) en premier et en dernier, tout le reste entre les deux.
migrations/database/	Migrations SQL brutes pour le pilote Doctrine.
html/index.php	Point d'entrée du worker FrankenPHP. Rarement modifié.
tests/	Tests PHPUnit qui amorcent l'API et envoient des requêtes.

Kipchak\Core\Api::boot() construit l'application Slim, puis charge drivers/drivers.php, puis middlewares/middlewares.php, puis chaque fichier de route, et retourne l'application.

Commandes dans un projet créé depuis le starter (composer create-project kipchak/starter mon-api) :

• composer test : exécuter les tests. Exécutez-les après chaque modification.
• composer openapi : écrire le document OpenAPI dans openapi.yaml ; échoue si le document a un problème.
• docker compose up --watch : lancer l'API sur http://localhost:8080, redémarrant le worker lorsqu'un fichier change.

Règles

1. Commencez chaque fichier PHP dans api/ et tests/ par declare(strict_types=1);. Rendez les classes final sauf si elles sont destinées à être étendues. Tapez chaque propriété, paramètre et valeur de retour.
2. Les contrôleurs sont légers. Lisez la requête, appelez un modèle, retournez une réponse. La logique appartient à api/Models/.
3. Les DTO sont le contrat. Chaque forme de requête et de réponse est un DTO final readonly avec #[OA\Schema] et une #[OA\Property] (description et exemple) sur chaque propriété. Les contrôleurs référencent les schémas DTO avec ref: '#/components/schemas/Nom' et ne définissent jamais les champs d'un DTO en ligne. Le même DTO décrit le corps de la requête et la réponse.
4. Les réponses passent par Kipchak\Core\Components\Http\Response::json($response, $data, $status), qui encapsule $data dans l'enveloppe {"code": 200, "status": "OK", "data": ...}.
5. Les erreurs sont les exceptions HTTP de Slim : HttpNotFoundException, HttpBadRequestException, HttpUnauthorizedException, HttpForbiddenException, HttpMethodNotAllowedException. Le middleware Error (kipchak/middleware-error) les transforme dans la même enveloppe, par exemple {"code": 404, "status": "RESOURCE_NOT_FOUND", "data": "Aucune commande n'a l'ID 9."}. Toute autre exception devient une 500 dont le message n'est pas visible par le client.
6. Mode worker. L'API est amorcée une seule fois et sert de nombreuses requêtes depuis la mémoire. Ne conservez jamais de données de requête dans une propriété statique, une globale ou un singleton. Une statique ne peut mettre en cache que ce qui est identique pour chaque requête.
7. Utilisez un pilote Kipchak pour un service lorsqu'il en existe un, plutôt qu'une bibliothèque cliente directement (voir references/packages.md). Les bases de données relationnelles utilisent le pilote Doctrine.
8. La configuration se trouve dans config/ et les variables d'environnement. Lisez un fichier de configuration avec Kipchak\Driver\Config\Config::get('kipchak.api'), qui retourne un tableau. Lisez les variables d'environnement à l'intérieur des fichiers de configuration avec Kipchak\Core\env('NOM', 'default'). N'appelez jamais getenv() dans les contrôleurs ou les modèles.
9. La journalisation dans un contrôleur utilise $this->logger (Monolog, PSR-3) ; ailleurs Kipchak\Driver\Logger\Logger::get().
10. Un changement d'API est un changement de contrat. Mettez à jour simultanément le DTO et les attributs du contrôleur, puis les tests, et vérifiez que le document OpenAPI se génère toujours sans avertissements.

Ajouter un point de terminaison

Suivez ces cinq étapes. Le code complet pour chacune se trouve dans references/endpoints.md ; lisez-le avant d'écrire un point de terminaison.

1. DTO dans api/DataTransferObjects/v1/.
2. Modèle dans api/Models/ : la logique, retournant des DTO. Mappez les tableaux aux DTO avec Valinor : (new MapperBuilder())->mapper()->map(Order::class, Source::array($ligne)).
3. Méthode du contrôleur dans api/Controllers/v1/, sur une classe étendant Kipchak\Core\Components\Controllers\Base, avec la signature (ServerRequestInterface $request, ResponseInterface $response, array $args): ResponseInterface et un attribut #[OA\Get], #[OA\Post] (etc.) : chemin, operationId, résumé, tags, paramètres, corps de la requête et réponses.
4. Route dans routes/v1/<ressource>.php, à l'intérieur d'un groupe /v1 : $group->get('/orders/{id:[0-9]+}', [Controllers\v1\Orders::class, 'get']);
5. Test dans tests/, étendant le ApiTestCase du projet, pour les réponses de succès et d'erreur. Si le test OpenAPI du projet liste les chemins attendus, ajoutez le nouveau chemin là.

Références

Lisez la référence qui correspond à la tâche :

• references/endpoints.md : une ressource complète (DTO, modèle, contrôleur, route, test), corps de requêtes et validation, paramètres de requête, paramètres de chemin.
• references/drivers.md : utilisation des pilotes, configuration, Doctrine, et rédaction d'un nouveau pilote.
• references/middleware.md : middleware globaux, de groupe et de route, leur ordre, et rédaction d'un nouveau middleware.
• references/worker-mode.md : ce qui est sûr dans un worker à longue durée de vie, corps de requêtes, connexions, et travail après la réponse.
• references/packages.md : chaque pilote et middleware Kipchak, gratuit et Enterprise.