Api

Reference for the Api module: every class and function, with its full signature, parameters and return type. A declarative, build-once registry of API endpoints under /api/{Module}/{version}/{path}, and the engine that serves them. Modules declare their endpoints at load time; the site calls one function to serve the whole registry. The wire contract has no envelope: on success the response body is the handler's data; on error it is the HTTP status plus a short plain-text message.

This page is a pure reference. For how the framework fits together, see the Guide.

Classes

Api - serves every declared endpoint under /api; called once from the site route layer.
ApiConfig - the declarative, build-once registry of API endpoints, and the engine that serves them.
ApiContext - per-request context passed to a handler: the decoded input and guard-loaded resources.
ApiErrorConfig - global mapping from a thrown exception type to a wire error, applied to every endpoint.
ApiInputConfig - declares an endpoint's input fields, each with a validator run before the handler.
ApiErrorException - a known API error: an HTTP status code plus a short human message, thrown directly.

Api

Dispatch and introspection for the declarative API. Modules declare their endpoints at load time with ApiConfig::Module; this class serves the whole registry.

Functions

Route

Api::Route(): void

Serve every ApiConfig-declared endpoint under /api. Call once, from the site route layer.

Returns void

ApiConfig

The declarative, build-once registry of API endpoints, and the engine that serves them. A module declares its endpoints in a closure that runs once at load and only records data; per request the engine decodes and validates inputs, runs guards in order, calls the handler, applies an optional output encoder, and emits. Thrown exceptions are mapped to an HTTP status by type.

Properties

Property	Type	Description
`ApiConfig::$modules`	`array`	The registry: one record per Module() call, holding module, version and endpoints.

Functions

AddInput Delete Error ErrorRecord Get Guard GuardLoad Handler Module Post Put WireAll

AddInput

ApiConfig::AddInput(object $inputRecord): void

Record a declared input field on the current endpoint. Called by ApiInputConfig from inside an endpoint closure.

Name	Type	Description
`$inputRecord`	`object`	The input field record to add.

Returns void

Delete

ApiConfig::Delete(string $path, callable|string $declareOrHandler): void

Declare a DELETE endpoint on the current module. Pass a handler directly, or a declaration closure carrying the whole contract.

Name	Type	Description
`$path`	`string`	The endpoint path segment.
`$declareOrHandler`	`callable\|string`	A handler, or a declaration closure that records inputs, guards, handler and errors.

Returns void

Error

ApiConfig::Error(string $exceptionClass, int $httpStatus, string $message = '', ?bool $log = null): void

Map an exception type to an HTTP status and message for this endpoint only, checked before the global ApiErrorConfig entries.

Name	Type	Description
`$exceptionClass`	`string`	The exception class to match.
`$httpStatus`	`int`	The HTTP status to emit.
`$message`	`string`	The short plain-text message body.
`$log`	`?bool`	Whether to log; null defaults to logging when the status is 500 or more.

Returns void

ErrorRecord

ApiConfig::ErrorRecord(string $exceptionClass, int $httpStatus, string $message, ?bool $log, ?string $source = null): object

Build the shared error-record shape mapping an exception type to a status and message. When log is null it defaults to logging when the status is 500 or more.

Name	Type	Description
`$exceptionClass`	`string`	The exception class to match.
`$httpStatus`	`int`	The HTTP status to emit.
`$message`	`string`	The short plain-text message body.
`$log`	`?bool`	Whether to log; null defaults to logging when the status is 500 or more.
`$source`	`?string`	The domain or module this error comes from, or null.

Returns object The error record.

Get

ApiConfig::Get(string $path, callable|string $declareOrHandler): void

Declare a GET endpoint on the current module. Pass a handler directly, or a declaration closure carrying the whole contract.

Name	Type	Description
`$path`	`string`	The endpoint path segment.
`$declareOrHandler`	`callable\|string`	A handler, or a declaration closure that records inputs, guards, handler and errors.

Returns void

Guard

ApiConfig::Guard(callable|string $check, string ...$argNames): void

Add a guard check that runs before the handler, in declaration order. Named input fields are passed to the check as arguments.

Name	Type	Description
`$check`	`callable\|string`	The guard check to run.
`...$argNames`	`string`	The names of the input fields passed to the check.

Returns void

GuardLoad

ApiConfig::GuardLoad(string $resourceName, callable|string $loader, string ...$argNames): void

A guard that loads and authorises a resource and stashes it as a context resource, so the handler can reuse it instead of re-querying. A null result is a not-found error.

Name	Type	Description
`$resourceName`	`string`	The name to stash the loaded resource under.
`$loader`	`callable\|string`	The loader that returns the resource, or null when not found.
`...$argNames`	`string`	The names of the input fields passed to the loader.

Returns void

Handler

ApiConfig::Handler(callable|string $handler, callable|string|null $encoder = null): void

Set the handler for the current endpoint, with an optional output encoder that shapes the wire output. The handler receives the decoded input and the context.

Name	Type	Description
`$handler`	`callable\|string`	The handler called with the input and the context.
`$encoder`	`callable\|string\|null`	An optional encoder applied to the handler's result, or null.

Returns void

Module

ApiConfig::Module(string $module, string $version, callable $endpoints): void

Declare a module's endpoints for a version by running a declaration closure once at load. Idempotent for a repeated module and version pair.

Name	Type	Description
`$module`	`string`	The module name, forming the first path segment.
`$version`	`string`	The version, forming the second path segment.
`$endpoints`	`callable`	The closure that declares the module's endpoints.

Returns void

Post

ApiConfig::Post(string $path, callable|string $declareOrHandler): void

Declare a POST endpoint on the current module. Pass a handler directly, or a declaration closure carrying the whole contract.

Name	Type	Description
`$path`	`string`	The endpoint path segment.
`$declareOrHandler`	`callable\|string`	A handler, or a declaration closure that records inputs, guards, handler and errors.

Returns void

Put

ApiConfig::Put(string $path, callable|string $declareOrHandler): void

Declare a PUT endpoint on the current module. Pass a handler directly, or a declaration closure carrying the whole contract.

Name	Type	Description
`$path`	`string`	The endpoint path segment.
`$declareOrHandler`	`callable\|string`	A handler, or a declaration closure that records inputs, guards, handler and errors.

Returns void

WireAll

ApiConfig::WireAll(): void

Wire every declared endpoint into the web router, under its module, version and path. Called by Api::Route.

Returns void

ApiContext

Per-request context passed to API handlers as the second argument. Carries the decoded, validated input and a stash of resources loaded by guards, so a handler can reuse a resource a guard already loaded and authorised.

Properties

Property	Type	Description
`$input`	`object`	The decoded, validated input, also passed as the first handler argument. Read-only.

Functions

__construct Resource SetResource

__construct

ApiContext::__construct(object $input)

Create a context carrying the decoded, validated input.

Name	Type	Description
`$input`	`object`	The decoded, validated input.

Returns ApiContext

Resource

ApiContext::Resource(string $name): mixed

Read a resource loaded by an ApiConfig::GuardLoad. Throws when no resource of that name was loaded.

Name	Type	Description
`$name`	`string`	The resource name.

Returns mixed The loaded resource.

SetResource

ApiContext::SetResource(string $name, mixed $value): void

Stash a loaded resource on the context under a name.

Name	Type	Description
`$name`	`string`	The name to stash the resource under.
`$value`	`mixed`	The resource value.

Returns void

ApiErrorConfig

The global, cross-cutting mapping from a thrown exception type to a wire error. Declared once, it applies to every endpoint everywhere, so a domain-wide error is one line rather than repeated per endpoint. There are no wire codes: the mapping is exception type to HTTP status and short message. It is checked after an endpoint's own errors.

Properties

Property	Type	Description
`ApiErrorConfig::$errors`	`array`	The registered global error records, each holding exception, http, message, log and source.

Functions

Error LoginRequired Match

Error

ApiErrorConfig::Error(string $exceptionClass, int $httpStatus, string $message = '', ?bool $log = null, ?string $source = null): void

Register a global mapping from an exception type to an HTTP status and message. Idempotent, so it is safe to register from multiple modules.

Name	Type	Description
`$exceptionClass`	`string`	The exception class to match.
`$httpStatus`	`int`	The HTTP status to emit.
`$message`	`string`	The short plain-text message body.
`$log`	`?bool`	Whether to log; null defaults to logging when the status is 500 or more.
`$source`	`?string`	The domain or module the error comes from, shown in the admin, or null.

Returns void

LoginRequired

ApiErrorConfig::LoginRequired(string $exceptionClass, string $message = 'Login required', ?string $source = null): void

Map an exception type to HTTP 401 (login required). Registered once, it applies everywhere. Idempotent.

Name	Type	Description
`$exceptionClass`	`string`	The exception class to match.
`$message`	`string`	The short plain-text message body.
`$source`	`?string`	The domain or module the error comes from, or null.

Returns void

Match

ApiErrorConfig::Match(Throwable $ex): ?object

Find the global error record matching a thrown exception. The most-derived matching class wins.

Name	Type	Description
`$ex`	`Throwable`	The thrown exception to match.

Returns ?object The matching error record, or null.

ApiInputConfig

Declares an endpoint's input fields inside an endpoint closure. Each call records a field (name, kind, whether optional) plus a validator the framework runs before the handler; a validator decodes and coerces the raw value and reports an error. Non-optional fields that are missing or blank are a validation error; the Optional variants allow absence and decode to null.

Functions

Arr Bool Email Enum Id Int Object OptionalId OptionalInt OptionalObject OptionalString String

Arr

ApiInputConfig::Arr(string $name): void

Declare a required array field; each element passes through shallowly.

Name	Type	Description
`$name`	`string`	The input field name.

Returns void

Bool

ApiInputConfig::Bool(string $name): void

Declare a boolean field, coerced from common truthy and falsy values.

Name	Type	Description
`$name`	`string`	The input field name.

Returns void

Email

ApiInputConfig::Email(string $name): void

Declare a required field validated as an email address.

Name	Type	Description
`$name`	`string`	The input field name.

Returns void

Enum

ApiInputConfig::Enum(string $name, array $options): void

Declare a required field that must be one of a fixed set of options.

Name	Type	Description
`$name`	`string`	The input field name.
`$options`	`array`	The allowed values.

Returns void

Id

ApiInputConfig::Id(string $name): void

Declare a required positive integer id field.

Name	Type	Description
`$name`	`string`	The input field name.

Returns void

Int

ApiInputConfig::Int(string $name): void

Declare a required integer field.

Name	Type	Description
`$name`	`string`	The input field name.

Returns void

Object

ApiInputConfig::Object(string $name, callable|string|null $optionalDecoder = null): void

Declare a required structured field (JSON object or array). When a decoder is given it is applied to the raw value to produce a typed object; otherwise the raw value passes through.

Name	Type	Description
`$name`	`string`	The input field name.
`$optionalDecoder`	`callable\|string\|null`	A decoder applied to the raw value, or null to pass through.

Returns void

OptionalId

ApiInputConfig::OptionalId(string $name): void

Declare an optional positive integer id field, decoded to null when absent.

Name	Type	Description
`$name`	`string`	The input field name.

Returns void

OptionalInt

ApiInputConfig::OptionalInt(string $name): void

Declare an optional integer field, decoded to null when absent.

Name	Type	Description
`$name`	`string`	The input field name.

Returns void

OptionalObject

ApiInputConfig::OptionalObject(string $name, callable|string|null $optionalDecoder = null): void

Declare an optional structured field, decoded to null when absent. When a decoder is given it is applied to the raw value; otherwise the raw value passes through.

Name	Type	Description
`$name`	`string`	The input field name.
`$optionalDecoder`	`callable\|string\|null`	A decoder applied to the raw value, or null to pass through.

Returns void

OptionalString

ApiInputConfig::OptionalString(string $name): void

Declare an optional text field, decoded to null when absent.

Name	Type	Description
`$name`	`string`	The input field name.

Returns void

String

ApiInputConfig::String(string $name): void

Declare a required text field.

Name	Type	Description
`$name`	`string`	The input field name.

Returns void

ApiErrorException

A known API error: an HTTP status code plus a short human message. Guards and handlers throw this directly for an immediate error. For domain exceptions a handler throws naturally, map the type to a status and message with ApiConfig::Error or ApiErrorConfig::Error instead. Extends the built-in Exception.

Properties

Property	Type	Description
`$httpStatus`	`int`	The HTTP status code to emit for this error. Read-only.

Functions

__construct

ApiErrorException::__construct(int $httpStatus, string $message)

Create the exception from an HTTP status code and a short message.

Name	Type	Description
`$httpStatus`	`int`	The HTTP status code to emit.
`$message`	`string`	The short plain-text message body.

Returns ApiErrorException