bad_cluster / runway-api-platform
API platform for Runway: endpoints as router routes, argument validation, JSON errors, authorization, CORS and the OpenAPI spec
Requires
- php: >=8.4
- ext-dom: *
- ext-mbstring: *
- ext-simplexml: *
- ext-zip: *
- bad_cluster/runway: ^2.0.1
Requires (Dev)
- ext-pdo_sqlite: *
- infection/infection: ^0.35
- phpstan/phpstan: ^2.3
- phpunit/phpunit: ^13.4
- roave/security-advisories: dev-latest
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-02 15:07:10 UTC
README
API platform for Runway.
composer require bad_cluster/runway-api-platform:^2.0
PHP 8.4+, Runway 2 (bad_cluster/runway:^2.0.1).
The changes of the versions are in CHANGELOG.md.
Endpoints
An endpoint is a public method of a service with the api_endpoint_collection tag. The method has an endpoint
attribute: Get, Post, Put, Patch, Delete (or Endpoint with any method). The path is a template relative to
the API prefix (api_path_prefix parameter, /api by default) and to the class Prefix:
use ApiPlatform\Attribute as Api; #[Api\Prefix('chats/{chatId}')] class Chat { #[Api\Get] // GET /api/chats/42 public function get(int $chatId): ChatDTO {} #[Api\Get('chunks/{index}')] // GET /api/chats/42/chunks/3 public function chunk(int $chatId, int $index): ChunkDTO {} #[Api\Get('messages')] // GET /api/chats/42/messages?number=10 public function messages(int $chatId, #[Api\Query] ?int $number = null): MessagesDTO {} #[Api\Patch('messages/{messageId}/meta')] public function updateMeta(int $chatId, int $messageId, #[Api\Body] array $meta): MetaDTO {} }
services: App\Endpoint\Chat: tags: - name: api_endpoint_collection
The endpoints are the routes of the Runway router, so the router rules apply:
- If several endpoints match the path, the most specific one wins: a static segment beats a placeholder
(
chats/{chatId}/messages/latestbeatschats/{chatId}/messages/{messageId}). - If the path matches, but the method does not, the response is
405 Method Not Allowedwith theAllowheader. AnOPTIONSrequest gets the allowed methods (and the CORS headers). - Two endpoints with the same path and method are an error.
Arguments
- Path: an argument with the name of a placeholder gets its value. An
int,floatorboolargument limits the placeholder to such values (/api/chats/abcis not found). Another regexp can be set inline:{slug<[a-z-]+>}.#[Api\Path('name')]takes a placeholder with another name. - Query, body, file:
#[Api\Query],#[Api\Body],#[Api\File], optionally with the name in the request. A query parameter is taken from the query string whatever the method (e.g.DELETE files?path=...), and from the form fields of a request with a form too. - File: an
ApiEndpointArgumentFileDTOargument gets the uploaded file (only an uploaded one: not any file of the server). An optional file (with a default value) can be left empty in the form. - An argument without a source gets its default value.
- The values are checked by the argument types (
int,float,bool,string,array) and the assertions (#[Assert\NotEmpty],#[Assert\Length],#[Assert\Range]): the errors of all the arguments are in one400response.
The mistakes (a placeholder without an argument, an argument without a source, etc.) are reported when the endpoints are collected, not when the endpoint is called.
Authorization
One user: its login and password hash (Argon2id) are in the options table, set them with IAuth::setCredentials()
(e.g. by a console command of the project), it ends all the sessions.
POST auth/loginstarts a session: a browser gets it in the cookie (HttpOnly,SameSite=Strict,Secureover HTTPS), a script (useCookie: false) gets the token for theAPI_TOKEN_HEADERheader. Only the hash of the token is stored (thetokenstable). A session lasts 30 days.POST auth/logoutends it,GET auth/statustells whether the client is logged in.GET auth/checkresponds with 204 or 401: for the web server, e.g. nginxauth_requestserves the static files only to the logged-in clients.- The failed logins (the
login_attemptstable) are limited: 5 per IP address and 50 in total for 15 minutes, then the response is 429. - A change (not
GET,HEADorOPTIONS) made by a page of another site is rejected (403), unless the site is allowed (API_ALLOW_ORIGIN) and the request has no session cookie: the browser adds the cookie, and the web server can let the request in by the IP address or the cached basic auth (CSRF). A script sends noOriginheader, a page cannot send the token header without CORS.
The tables (with the project prefix): options (id, name, value), tokens (id, token, generated, valid_until, last_active, ip, user_agent, server_info, expired, active), login_attempts (id, ip, attempted).
Configuration
The ENV variables (see .env, override them in the project):
API_AUTH_ENABLED:falsemakes every endpoint public, e.g. when the access is limited by the web server (by IP, basic auth, etc.). Thenauth/loginresponds with 404. Only an explicitfalse(0,off,no) opens the API: an empty or invalid value keeps the authorization.API_TOKEN_HEADER: the header of the session token for the scripts,X-Tokenby default.API_ALLOW_ORIGIN: comma-separated origins allowed to call the API from a browser on another site (CORS),*for any site. Empty by default: only the pages of the API site itself can call it.api_path_prefixparameter:/apiby default;api_session_cookie: the session cookie,api_sessionby default;api_title,api_description: the title and the description of the OpenAPI spec (GET schema).
The errors of the API paths (including 404 and 405) are JSON. The responses have the X-Request-Id,
X-Content-Type-Options: nosniff and Cache-Control: no-store headers (an endpoint response can set its own). The
details of the internal errors (5xx: the message, the file, the trace) are shown only with APP_DEBUG=true; the client
errors (4xx) are logged at the info level, the internal ones at the error level, without the arguments of the calls.
Development
composer test # PHPUnit: the unit, integration and E2E tests composer test:unit # the classes one by one composer test:integration # the container in the process, SQLite in memory composer test:e2e # HTTP requests to the PHP built-in server composer phpstan # PHPStan, the max level composer infection # mutation testing of the unit tests (pcov or Xdebug)
The tests need the pdo_sqlite extension. The CI runs them on Linux, macOS and Windows with PHP 8.4 and 8.5.