kipchak

¿Qué hace kipchak?

Kipchak es un kit de desarrollo de API para PHP 8.4 y versiones posteriores. Está basado en Slim Framework 4 con una estructura fija: una secuencia de arranque, controladores para servicios externos, middleware y convenciones para rutas, controladores, objetos de transferencia de datos (DTO) y OpenAPI. Funciona en FrankenPHP en modo worker. Documentación: https://kipchak.dev; índice para modelos de lenguaje: https://kipchak.dev/llms.txt.

Kipchak no es Laravel ni Symfony. No hay fachadas, helpers globales, service providers, Eloquent, Blade, controladores autoinyectados ni convenciones ocultas. Todo lo que un endpoint hace es visible en el código propio del proyecto. No escribas request(), response()->json(), config('...'), app(), Route::get(), DB::, Cache:: ni ningún otro helper del framework: ninguno de ellos existe aquí.

Reconocer un proyecto Kipchak

composer.json requiere kipchak/core, y el proyecto tiene estas carpetas. Si el proyecto tiene un AGENTS.md, léelo primero: describe ese proyecto.

Ruta	Contenido
routes/	Archivos de rutas. Cada archivo .php en ella, a cualquier profundidad, se carga al arrancar. Las rutas versionadas van en routes/v1/.
api/Controllers/	Controladores, espacio de nombres Api\Controllers; los versionados en v1/ (Api\Controllers\v1).
api/DataTransferObjects/	DTOs, versionados como los controladores. Son el contrato de la API.
api/Models/	Lógica de negocio.
api/Entities/Doctrine/<Connection>/	Entidades de Doctrine, cuando se usa el controlador Doctrine.
api/Middlewares/	Middleware PSR-15 propio del proyecto.
api/OpenApi/Definition.php	Título, versión, servidores y respuestas compartidas de OpenAPI.
api/Utils/	Código compartido en toda la API.
config/	Un archivo PHP por controlador o middleware, que devuelve un array, con nombre kipchak.<nombre>.php.
drivers/drivers.php	Inicializa los controladores, en orden.
middlewares/middlewares.php	Inicializa el middleware aplicado a cada solicitud: Error::initialise($app) primero y último, todo lo demás entre medio.
migrations/database/	Migraciones SQL simples para el controlador Doctrine.
html/index.php	Punto de entrada del worker de FrankenPHP. Raramente editado.
tests/	Pruebas PHPUnit que arrancan la API y envían solicitudes.

Kipchak\Core\Api::boot() construye la aplicación Slim, luego carga drivers/drivers.php, luego middlewares/middlewares.php, luego cada archivo de rutas, y devuelve la aplicación.

Comandos en un proyecto creado desde el iniciador (composer create-project kipchak/starter my-api):

• composer test: ejecuta las pruebas. Ejecútalas después de cada cambio.
• composer openapi: escribe el documento OpenAPI en openapi.yaml; falla si el documento tiene un problema.
• docker compose up --watch: ejecuta la API en http://localhost:8080, reiniciando el worker cuando un archivo cambia.

Reglas

1. Inicia cada archivo PHP en api/ y tests/ con declare(strict_types=1);. Haz las clases final a menos que estén pensadas para ser extendidas. Escribe el tipo de cada propiedad, parámetro y valor de retorno.
2. Los controladores son delgados. Lee la solicitud, llama a un modelo, devuelve una respuesta. La lógica pertenece a api/Models/.
3. Los DTOs son el contrato. Cada forma de solicitud y respuesta es un DTO final readonly con #[OA\Schema] y un #[OA\Property] (descripción y ejemplo) en cada propiedad. Los controladores referencian esquemas DTO con ref: '#/components/schemas/Nombre' y nunca definen los campos de un DTO en línea. El mismo DTO describe el cuerpo de la solicitud y la respuesta.
4. Respuestas pasan por Kipchak\Core\Components\Http\Response::json($response, $data, $status), que envuelve $data en el envoltorio {"code": 200, "status": "OK", "data": ...}.
5. Errores son excepciones HTTP de Slim: HttpNotFoundException, HttpBadRequestException, HttpUnauthorizedException, HttpForbiddenException, HttpMethodNotAllowedException. El middleware Error (kipchak/middleware-error) las convierte en el mismo envoltorio, por ejemplo {"code": 404, "status": "RESOURCE_NOT_FOUND", "data": "No hay un pedido con el ID 9."}. Cualquier otra excepción se convierte en un 500 cuyo mensaje el cliente no ve.
6. Modo worker. La API se arranca una vez y sirve muchas solicitudes desde la memoria. Nunca guardes datos de la solicitud en una propiedad estática, un global o un singleton. Un estático solo puede cachear lo que es igual para cada solicitud.
7. Usa un controlador Kipchak para un servicio cuando exista uno, en lugar de una librería cliente directamente (ver references/packages.md). Las bases de datos relacionales usan el controlador Doctrine.
8. Configuración vive en config/ y variables de entorno. Lee un archivo de configuración con Kipchak\Driver\Config\Config::get('kipchak.api'), que devuelve un array. Lee variables de entorno dentro de los archivos de configuración con Kipchak\Core\env('NOMBRE', 'default'). Nunca llames a getenv() en controladores o modelos.
9. Registro en un controlador usa $this->logger (Monolog, PSR-3); en otros lugares Kipchak\Driver\Logger\Logger::get().
10. Un cambio en la API es un cambio en el contrato. Actualiza el DTO y los atributos del controlador juntos, luego las pruebas, y verifica que el documento OpenAPI aún se genera sin advertencias.

Añadir un endpoint

Sigue estos cinco pasos. El código completo de cada uno está en references/endpoints.md; léelo antes de escribir un endpoint.

1. DTO en api/DataTransferObjects/v1/.
2. Modelo en api/Models/: la lógica, devolviendo DTOs. Mapea arrays a DTOs con Valinor: (new MapperBuilder())->mapper()->map(Pedido::class, Source::array($fila)).
3. Método del controlador en api/Controllers/v1/, en una clase que extienda Kipchak\Core\Components\Controllers\Base, con la firma (ServerRequestInterface $request, ResponseInterface $response, array $args): ResponseInterface y un atributo #[OA\Get], #[OA\Post] (y así sucesivamente): ruta, operationId, resumen, tags, parámetros, cuerpo de solicitud y respuestas.
4. Ruta en routes/v1/<recurso>.php, dentro de un grupo /v1: $group->get('/orders/{id:[0-9]+}', [Controllers\v1\Orders::class, 'get']);
5. Prueba en tests/, extendiendo el ApiTestCase del proyecto, para las respuestas exitosas y de error. Si la prueba de OpenAPI del proyecto lista las rutas esperadas, añade la nueva ruta allí.

Referencias

Lee la referencia que coincida con la tarea:

• references/endpoints.md: un recurso completo (DTO, modelo, controlador, ruta, prueba), cuerpos de solicitud y validación, parámetros de consulta, parámetros de ruta.
• references/drivers.md: uso de controladores, configuración, Doctrine, y escritura de un nuevo controlador.
• references/middleware.md: middleware global, de grupo y de ruta, su orden, y escritura de nuevo middleware.
• references/worker-mode.md: qué es seguro en un worker de larga duración, cuerpos de solicitud, conexiones y trabajo después de la respuesta.
• references/packages.md: cada controlador y middleware de Kipchak, gratuitos y Enterprise.