kipchak

Was macht kipchak?

Kipchak ist ein API-Entwicklungskit für PHP 8.4 und höher. Es basiert auf Slim Framework 4 mit einer festen Struktur: einer Boot-Reihenfolge, Treibern für externe Dienste, Middleware sowie Konventionen für Routen, Controller, Datenübertragungsobjekte (DTOs) und OpenAPI. Es läuft auf FrankenPHP im Worker-Modus. Dokumentation: https://kipchak.dev; Index für Sprachmodelle: https://kipchak.dev/llms.txt.

Kipchak ist nicht Laravel oder Symfony. Es gibt keine Fassaden, globalen Hilfsfunktionen, Service Provider, Eloquent, Blade, automatisch verdrahtete Controller oder versteckte Konventionen. Alles, was ein Endpunkt tut, ist im eigenen Code des Projekts sichtbar. Verwenden Sie nicht request(), response()->json(), config('...'), app(), Route::get(), DB::, Cache:: oder irgendwelche anderen Framework-Hilfsfunktionen: Keine davon existiert hier.

Erkennen eines Kipchak-Projekts

composer.json erfordert kipchak/core, und das Projekt hat diese Ordner. Falls das Projekt eine AGENTS.md besitzt, lesen Sie diese zuerst: Sie beschreibt das Projekt.

Pfad	Enthält
routes/	Routendateien. Jede .php-Datei darin wird, unabhängig von der Tiefe, beim Booten geladen. Versionierte Routen liegen in routes/v1/.
api/Controllers/	Controller, Namespace Api\Controllers; versionierte in v1/ (Api\Controllers\v1).
api/DataTransferObjects/	DTOs, versioniert wie die Controller. Sie sind der API-Vertrag.
api/Models/	Geschäftslogik.
api/Entities/Doctrine/<Connection>/	Doctrine-Entitäten, wenn der Doctrine-Treiber verwendet wird.
api/Middlewares/	Die eigenen PSR-15-Middleware des Projekts.
api/OpenApi/Definition.php	OpenAPI-Titel, -Version, -Server und geteilte Antworten.
api/Utils/	Code, der über die API hinweg gemeinsam genutzt wird.
config/	Eine PHP-Datei pro Treiber oder Middleware, die ein Array zurückgibt und kipchak.<name>.php heißt.
drivers/drivers.php	Initialisiert die Treiber in der richtigen Reihenfolge.
middlewares/middlewares.php	Initialisiert die Middleware, die auf jede Anfrage angewendet wird: zuerst und zuletzt Error::initialise($app), alles andere dazwischen.
migrations/database/	Reine SQL-Migrationen für den Doctrine-Treiber.
html/index.php	Der Einstiegspunkt des FrankenPHP-Workers. Wird selten bearbeitet.
tests/	PHPUnit-Tests, die die API booten und Anfragen an sie senden.

Kipchak\Core\Api::boot() erstellt die Slim-Anwendung, lädt dann drivers/drivers.php, dann middlewares/middlewares.php, dann jede Routendatei und gibt die Anwendung zurück.

Befehle in einem Projekt, das aus dem Starter erstellt wurde (composer create-project kipchak/starter my-api):

• composer test: führt die Tests aus. Führen Sie sie nach jeder Änderung aus.
• composer openapi: schreibt das OpenAPI-Dokument in openapi.yaml; schlägt fehl, wenn das Dokument ein Problem hat.
• docker compose up --watch: startet die API unter http://localhost:8080 und startet den Worker neu, wenn sich eine Datei ändert.

Regeln

1. Beginnen Sie jede PHP-Datei in api/ und tests/ mit declare(strict_types=1);. Machen Sie Klassen final, es sei denn, sie sollen erweitert werden. Geben Sie jeden Parameter, jede Eigenschaft und jeden Rückgabewert mit einem Typ an.
2. Controller sind dünn. Lesen Sie die Anfrage, rufen Sie ein Modell auf, geben Sie eine Antwort zurück. Die Logik gehört in api/Models/.
3. DTOs sind der Vertrag. Jede Anfrage- und Antwortstruktur ist ein final readonly DTO mit #[OA\Schema] und einer #[OA\Property] (Beschreibung und Beispiel) auf jeder Eigenschaft. Controller referenzieren DTO-Schemas mit ref: '#/components/schemas/Name' und definieren die Felder eines DTOs niemals inline. Das gleiche DTO beschreibt den Anforderungskörper und die Antwort.
4. Antworten gehen durch Kipchak\Core\Components\Http\Response::json($response, $data, $status), das $data in das Envelope {"code": 200, "status": "OK", "data": ...} verpackt.
5. Fehler sind Slims HTTP-Exceptions: HttpNotFoundException, HttpBadRequestException, HttpUnauthorizedException, HttpForbiddenException, HttpMethodNotAllowedException. Die Error-Middleware (kipchak/middleware-error) wandelt sie in das gleiche Envelope um, z.B. {"code": 404, "status": "RESOURCE_NOT_FOUND", "data": "No order has the ID 9."}. Jede andere Exception wird zu einem 500er, dessen Nachricht der Client nicht sieht.
6. Worker-Modus. Die API wird einmal gebootet und bedient viele Anfragen aus dem Speicher. Halten Sie Anfragedaten niemals in einer statischen Eigenschaft, einem Globalen oder einem Singleton. Ein Static darf nur das zwischenspeichern, was für jede Anfrage gleich ist.
7. Verwenden Sie einen Kipchak-Treiber für einen Dienst, wenn einer existiert, anstatt direkt eine Client-Bibliothek zu nutzen (siehe references/packages.md). Relationale Datenbanken verwenden den Doctrine-Treiber.
8. Konfiguration lebt in config/ und Umgebungsvariablen. Lesen Sie eine Konfigurationsdatei mit Kipchak\Driver\Config\Config::get('kipchak.api'), was ein Array zurückgibt. Lesen Sie Umgebungsvariablen innerhalb von Konfigurationsdateien mit Kipchak\Core\env('NAME', 'default'). Rufen Sie niemals getenv() in Controllern oder Modellen auf.
9. Logging in einem Controller verwendet $this->logger (Monolog, PSR-3); ansonsten Kipchak\Driver\Logger\Logger::get().
10. Eine API-Änderung ist eine Vertragsänderung. Aktualisieren Sie das DTO und die Attribute des Controllers zusammen, dann die Tests, und überprüfen Sie, ob das OpenAPI-Dokument immer noch ohne Warnungen generiert wird.

Hinzufügen eines Endpunkts

Befolgen Sie diese fünf Schritte. Den vollständigen Code für jeden Schritt finden Sie in references/endpoints.md; lesen Sie ihn, bevor Sie einen Endpunkt schreiben.

1. DTO in api/DataTransferObjects/v1/.
2. Modell in api/Models/: die Logik, die DTOs zurückgibt. Bilden Sie Arrays mit Valinor auf DTOs ab: (new MapperBuilder())->mapper()->map(Order::class, Source::array($row)).
3. Controller-Methode in api/Controllers/v1/, in einer Klasse, die Kipchak\Core\Components\Controllers\Base erweitert, mit der Signatur (ServerRequestInterface $request, ResponseInterface $response, array $args): ResponseInterface und einem #[OA\Get], #[OA\Post] (usw.)-Attribut: Pfad, operationId, Zusammenfassung, Tags, Parameter, Anforderungskörper und Antworten.
4. Route in routes/v1/<resource>.php, innerhalb einer /v1-Gruppe: $group->get('/orders/{id:[0-9]+}', [Controllers\v1\Orders::class, 'get']);
5. Test in tests/, der die ApiTestCase-Klasse des Projekts erweitert, für die Erfolgs- und die Fehlerantworten. Falls der OpenAPI-Test des Projekts die erwarteten Pfade auflistet, fügen Sie den neuen Pfad dort hinzu.

Referenzen

Lesen Sie die Referenz, die zur Aufgabe passt:

• references/endpoints.md: eine vollständige Ressource (DTO, Modell, Controller, Route, Test), Anforderungskörper und Validierung, Abfrageparameter, Pfadparameter.
• references/drivers.md: Verwendung von Treibern, Konfiguration, Doctrine und Schreiben eines neuen Treibers.
• references/middleware.md: globale, Gruppen- und Routen-Middleware, ihre Reihenfolge und Schreiben neuer Middleware.
• references/worker-mode.md: was in einem langlebigen Worker sicher ist, Anforderungskörper, Verbindungen und Arbeiten nach der Antwort.
• references/packages.md: jeder Kipchak-Treiber und jede Middleware, kostenlos und Enterprise.