Kipchak は何をしますか？
Kipchak は PHP 8.4 以降向けの API 開発キットです。Slim Framework 4 をベースに、固定構造（ブートシーケンス、外部サービス用ドライバー、ミドルウェア、ルート、コントローラー、データ転送オブジェクト (DTO)、OpenAPI の規約）を提供します。FrankenPHP のワーカーモードで動作します。ドキュメント: https://kipchak.dev、言語モデル向けインデックス: https://kipchak.dev/llms.txt。
Kipchak は Laravel や Symfony ではありません。 ファサード、グローバルヘルパー、サービスプロバイダー、Eloquent、Blade、自動ワイヤリングされたコントローラー、隠れた規約は一切ありません。エンドポイントが行う処理はすべてプロジェクト自身のコードに明示されています。request()、response()->json()、config('...')、app()、Route::get()、DB::、Cache:: などのフレームワークヘルパーは記述しないでください。これらはここには存在しません。
Kipchak プロジェクトの認識
composer.json に kipchak/core が必要で、プロジェクトに以下のフォルダがあることを確認します。プロジェクトに AGENTS.md がある場合は、まずそれを読んでください。そのプロジェクトについて説明されています。
| パス | 内容 |
|---|---|
routes/ | ルートファイル。この中のすべての .php ファイル（深さ問わず）がブート時に読み込まれます。バージョン管理されたルートは routes/v1/ に配置します。 |
api/Controllers/ | コントローラー。名前空間 Api\Controllers。バージョン管理されたものは v1/ 内（Api\Controllers\v1）。 |
api/DataTransferObjects/ | DTO。コントローラーと同様にバージョン管理されます。これらが API コントラクトです。 |
api/Models/ | ビジネスロジック。 |
api/Entities/Doctrine/<Connection>/ | Doctrine エンティティ（Doctrine ドライバー使用時）。 |
api/Middlewares/ | プロジェクト独自の PSR-15 ミドルウェア。 |
api/OpenApi/Definition.php | OpenAPI のタイトル、バージョン、サーバー、共有レスポンス。 |
api/Utils/ | API 全体で共有されるコード。 |
config/ | ドライバーまたはミドルウェアごとに 1 つの PHP ファイル。配列を返し、kipchak.<name>.php という名前。 |
drivers/drivers.php | ドライバーを順に初期化します。 |
middlewares/middlewares.php | すべてのリクエストに適用されるミドルウェアを初期化します。最初と最後に Error::initialise($app)、その間に他のミドルウェアを配置します。 |
migrations/database/ | Doctrine ドライバー用のプレーンな SQL マイグレーション。 |
html/index.php | FrankenPHP ワーカーのエントリポイント。ほとんど編集しません。 |
tests/ | API をブートしてリクエストを送信する PHPUnit テスト。 |
Kipchak\Core\Api::boot() は Slim アプリケーションを構築し、drivers/drivers.php、middlewares/middlewares.php、すべてのルートファイルを順に読み込み、アプリケーションを返します。
スターターから作成されたプロジェクト（composer create-project kipchak/starter my-api）でのコマンド:
composer test: テストを実行します。変更後は毎回実行してください。composer openapi: OpenAPI ドキュメントをopenapi.yamlに書き出します。ドキュメントに問題があると失敗します。docker compose up --watch: API を http://localhost:8080 で実行し、ファイルが変更されるとワーカーを再起動します。
ルール
api/とtests/のすべての PHP ファイルはdeclare(strict_types=1);で始めてください。拡張が意図されていない限り、クラスはfinalにします。すべてのプロパティ、パラメータ、戻り値に型を指定します。- コントローラーは薄く保ちます。 リクエストを読み取り、モデルを呼び出し、レスポンスを返します。ロジックは
api/Models/に属します。 - DTO がコントラクトです。 すべてのリクエストとレスポンスの形状は、
#[OA\Schema]と各プロパティに#[OA\Property]（description と example）を持つfinal readonlyな DTO です。コントローラーはref: '#/components/schemas/Name'で DTO スキーマを参照し、DTO のフィールドをインラインで定義しません。同じ DTO がリクエストボディとレスポンスの両方を記述します。 - レスポンス は
Kipchak\Core\Components\Http\Response::json($response, $data, $status)を経由します。これにより$dataがエンベロープ{"code": 200, "status": "OK", "data": ...}でラップされます。 - エラー は Slim の HTTP 例外:
HttpNotFoundException、HttpBadRequestException、HttpUnauthorizedException、HttpForbiddenException、HttpMethodNotAllowedExceptionを使用します。Error ミドルウェア（kipchak/middleware-error）はこれらを同じエンベロープに変換します。例:{"code": 404, "status": "RESOURCE_NOT_FOUND", "data": "No order has the ID 9."}。その他の例外は 500 になり、クライアントにはメッセージが表示されません。 - ワーカーモード。 API は一度だけブートされ、メモリから多数のリクエストを処理します。リクエストデータを static プロパティ、グローバル、シングルトンに保持しないでください。static はすべてのリクエストで同じもののみをキャッシュできます。
- Kipchak ドライバー が存在するサービスには、クライアントライブラリを直接使用するのではなく、そのドライバーを使用してください（references/packages.md を参照）。リレーショナルデータベースには Doctrine ドライバーを使用します。
- 設定 は
config/と環境変数にあります。設定ファイルはKipchak\Driver\Config\Config::get('kipchak.api')で読み取ります。配列を返します。設定ファイル内で環境変数を読み取るにはKipchak\Core\env('NAME', 'default')を使用します。コントローラーやモデルでgetenv()を呼び出さないでください。 - ログ はコントローラー内では
$this->logger（Monolog、PSR-3）を使用します。それ以外の場所ではKipchak\Driver\Logger\Logger::get()を使用します。 - API の変更はコントラクトの変更です。 DTO とコントローラーの属性を一緒に更新し、次にテストを更新し、OpenAPI ドキュメントが警告なしで生成されることを確認します。
エンドポイントの追加
以下の 5 つの手順に従います。各手順の完全なコードは references/endpoints.md にあります。エンドポイントを作成する前に読んでください。
- DTO を
api/DataTransferObjects/v1/に作成します。 - モデル を
api/Models/に作成します。ロジックを記述し、DTO を返します。配列から DTO へのマッピングには Valinor を使用します:(new MapperBuilder())->mapper()->map(Order::class, Source::array($row))。 - コントローラーメソッド を
api/Controllers/v1/に作成します。Kipchak\Core\Components\Controllers\Baseを継承したクラス上に、シグネチャ(ServerRequestInterface $request, ResponseInterface $response, array $args): ResponseInterfaceと#[OA\Get]、#[OA\Post]などの属性（path、operationId、summary、tags、parameters、request body、responses）を指定します。 - ルート を
routes/v1/<resource>.phpに作成します。/v1グループ内で:$group->get('/orders/{id:[0-9]+}', [Controllers\v1\Orders::class, 'get']); - テスト を
tests/に作成します。プロジェクトのApiTestCaseを継承し、成功レスポンスとエラーレスポンスの両方をテストします。プロジェクトの OpenAPI テストが期待するパスをリストしている場合は、新しいパスを追加します。
参考資料
タスクに該当する参考資料を読んでください:
- references/endpoints.md: 完全なリソース（DTO、モデル、コントローラー、ルート、テスト）、リクエストボディとバリデーション、クエリパラメータ、パスパラメータ。
- references/drivers.md: ドライバーの使用、設定、Doctrine、新しいドライバーの作成。
- references/middleware.md: グローバル、グループ、ルートミドルウェア、その順序、新しいミドルウェアの作成。
- references/worker-mode.md: 長時間稼働するワーカーで安全なもの、リクエストボディ、接続、レスポンス後の処理。
- references/packages.md: すべての Kipchak ドライバーとミドルウェア（無料版および Enterprise 版）。