kipchak

O que kipchak faz?

O Kipchak é um kit de desenvolvimento de API para PHP 8.4 e posteriores. Ele é baseado no Slim Framework 4 com uma estrutura fixa: uma sequência de inicialização, drivers para serviços externos, middlewares e convenções para rotas, controladores, objetos de transferência de dados (DTOs) e OpenAPI. Ele é executado no FrankenPHP em modo worker. Documentação: https://kipchak.dev; índice para modelos de linguagem: https://kipchak.dev/llms.txt.

Kipchak não é Laravel ou Symfony. Não existem facades, helpers globais, provedores de serviços, Eloquent, Blade, controladores injetados automaticamente ou convenções ocultas. Tudo o que um endpoint faz está visível no código do próprio projeto. Não escreva request(), response()->json(), config('...'), app(), Route::get(), DB::, Cache:: ou qualquer outro helper do framework: nenhum deles existe aqui.

Reconhecer um projeto Kipchak

O composer.json requer kipchak/core, e o projeto possui estas pastas. Se o projeto tiver um AGENTS.md, leia-o primeiro: ele descreve aquele projeto.

Caminho	Contém
routes/	Arquivos de rota. Cada arquivo .php nele, em qualquer profundidade, é carregado na inicialização. Rotas versionadas vão em routes/v1/.
api/Controllers/	Controladores, namespace Api\Controllers; os versionados em v1/ (Api\Controllers\v1).
api/DataTransferObjects/	DTOs, versionados como os controladores. Eles são o contrato da API.
api/Models/	Lógica de negócio.
api/Entities/Doctrine/<Connection>/	Entidades Doctrine, quando o driver Doctrine é usado.
api/Middlewares/	Middlewares PS-15 próprios do projeto.
api/OpenApi/Definition.php	Título, versão, servidores e respostas compartilhadas do OpenAPI.
api/Utils/	Código compartilhado na API.
config/	Um arquivo PHP por driver ou middleware, retornando um array, nomeado kipchak.<nome>.php.
drivers/drivers.php	Inicializa os drivers, em ordem.
middlewares/middlewares.php	Inicializa os middlewares aplicados a cada requisição: Error::initialise($app) primeiro e último, todo o resto entre eles.
migrations/database/	Migrações SQL puras para o driver Doctrine.
html/index.php	Ponto de entrada do worker FrankenPHP. Raramente editado.
tests/	Testes PHPUnit que inicializam a API e enviam requisições a ela.

Kipchak\Core\Api::boot() constrói a aplicação Slim, então carrega drivers/drivers.php, depois middlewares/middlewares.php, depois cada arquivo de rota, e retorna a aplicação.

Comandos em um projeto criado a partir do starter (composer create-project kipchak/starter my-api):

• composer test: executa os testes. Execute-os após cada alteração.
• composer openapi: escreve o documento OpenAPI em openapi.yaml; falha se o documento tiver algum problema.
• docker compose up --watch: executa a API em http://localhost:8080, reiniciando o worker quando um arquivo mudar.

Regras

1. Inicie todo arquivo PHP em api/ e tests/ com declare(strict_types=1);. Torne as classes final a menos que elas sejam destinadas a ser estendidas. Tipifique toda propriedade, parâmetro e valor de retorno.
2. Controladores são enxutos. Leia a requisição, chame um modelo, retorne uma resposta. A lógica pertence a api/Models/.
3. DTOs são o contrato. Cada formato de requisição e resposta é um DTO final readonly com #[OA\Schema] e um #[OA\Property] (descrição e exemplo) em cada propriedade. Os controladores referenciam esquemas de DTO com ref: '#/components/schemas/Nome' e nunca definem os campos de um DTO inline. O mesmo DTO descreve o corpo da requisição e a resposta.
4. Respostas passam por Kipchak\Core\Components\Http\Response::json($response, $data, $status), que envolve $data no envelope {"code": 200, "status": "OK", "data": ...}.
5. Erros são exceções HTTP do Slim: HttpNotFoundException, HttpBadRequestException, HttpUnauthorizedException, HttpForbiddenException, HttpMethodNotAllowedException. O middleware de erro (kipchak/middleware-error) as transforma no mesmo envelope, por exemplo {"code": 404, "status": "RESOURCE_NOT_FOUND", "data": "Nenhum pedido tem o ID 9."}. Qualquer outra exceção se torna um 500 cuja mensagem o cliente não vê.
6. Modo worker. A API é inicializada uma vez e atende muitas requisições a partir da memória. Nunca mantenha dados de requisição em uma propriedade estática, global ou singleton. Um estático só pode armazenar em cache o que é o mesmo para cada requisição.
7. Use um driver Kipchak para um serviço quando existir um, em vez de uma biblioteca cliente diretamente (veja references/packages.md). Bancos de dados relacionais usam o driver Doctrine.
8. Configuração fica em config/ e variáveis de ambiente. Leia um arquivo de configuração com Kipchak\Driver\Config\Config::get('kipchak.api'), que retorna um array. Leia variáveis de ambiente dentro dos arquivos de configuração com Kipchak\Core\env('NAME', 'default'). Nunca chame getenv() em controladores ou modelos.
9. Logging em um controlador usa $this->logger (Monolog, PSR-3); em outros lugares Kipchak\Driver\Logger\Logger::get().
10. Uma alteração na API é uma alteração no contrato. Atualize o DTO e os atributos do controlador juntos, depois os testes, e verifique se o documento OpenAPI ainda é gerado sem avisos.

Adicionando um endpoint

Siga estes cinco passos. O código completo para cada um está em references/endpoints.md; leia-o antes de escrever um endpoint.

1. DTO em api/DataTransferObjects/v1/.
2. Model em api/Models/: a lógica, retornando DTOs. Mapeie arrays para DTOs com o Valinor: (new MapperBuilder())->mapper()->map(Order::class, Source::array($row)).
3. Método do controlador em api/Controllers/v1/, em uma classe que estende Kipchak\Core\Components\Controllers\Base, com a assinatura (ServerRequestInterface $request, ResponseInterface $response, array $args): ResponseInterface e um atributo #[OA\Get], #[OA\Post] (e assim por diante): caminho, operationId, resumo, tags, parâmetros, corpo da requisição e respostas.
4. Rota em routes/v1/<recurso>.php, dentro de um grupo /v1: $group->get('/orders/{id:[0-9]+}', [Controllers\v1\Orders::class, 'get']);
5. Teste em tests/, estendendo o ApiTestCase do projeto, para as respostas de sucesso e de erro. Se o teste OpenAPI do projeto listar os caminhos esperados, adicione o novo caminho lá.

Referências

Leia a referência que corresponde à tarefa:

• references/endpoints.md: um recurso completo (DTO, modelo, controlador, rota, teste), corpos de requisição e validação, parâmetros de consulta, parâmetros de caminho.
• references/drivers.md: usando drivers, configuração, Doctrine e escrevendo um novo driver.
• references/middleware.md: middlewares globais, de grupo e de rota, sua ordem e escrevendo novos middlewares.
• references/worker-mode.md: o que é seguro em um worker de longa duração, corpos de requisição, conexões e trabalho após a resposta.
• references/packages.md: todos os drivers e middlewares do Kipchak, gratuitos e Enterprise.