Phalcon Adr

ADR\Application

ADR composition root. Owns (or accepts) a container, exposes a small registration surface that hides the container’s definition API, configures the convention router, and handles the request through the ADR flow.

When no container is supplied one is created with the ADR defaults (AdrProvider) registered. Type-hinted dependencies autowire; only scalar parameters need to be declared via define().

Uses Closure · Phalcon\ADR\Container\AdrProvider · Phalcon\ADR\Events\Event · Phalcon\ADR\Exceptions\RouteNotFound · Phalcon\Container\Container · Phalcon\Container\ContainerFactory · Phalcon\Contracts\ADR\ADRTypes · Phalcon\Contracts\ADR\Application · Phalcon\Contracts\ADR\Dispatcher · Phalcon\Contracts\ADR\Router\AttributeFilter · Phalcon\Contracts\ADR\Router\Router · Phalcon\Contracts\Events\Manager · Phalcon\Contracts\Http\AttributeRequest · Phalcon\Http\Response · Phalcon\Http\ResponseInterface

Method Summary

Properties

Methods

__construct()

public function __construct( Container|null $container = null );

bind()

public function bind(
    string $interfaceName,
    string $concrete
): static;

Bind an interface to a concrete class.

define()

public function define(
    string $className,
    array $parameters = []
): static;

Register a class together with explicit values for its constructor parameters. Type-hinted dependencies autowire; only the supplied (usually scalar) parameters are declared. Lazy values (e.g. new Phalcon\Container\Resolver\Lazy\Env(...)) may be passed as values.

extend()

public function extend(
    string $name,
    Closure $extender
): static;

Register a post-build extender (decorator) for a service.

factory()

public function factory(
    string $name,
    Closure $factory
): static;

Register a factory closure for a service.

getContainer()

public function getContainer(): Container;

Returns the underlying container for definition-level access.

handle()

public function handle( AttributeRequest $request ): ResponseInterface;

Routes the request, writes the matched attributes onto it, dispatches the Action and returns the response. A single try/catch routes any error through the error responder; if that itself fails, a bare 500 is returned so nothing escapes uncaught.

secureWith()

public function secureWith(
    string $guard,
    string $prefix
): static;

Attach a guard (middleware) to every Action under a namespace prefix.

set()

public function set(
    string $name,
    mixed $definition
): static;

Register a service with a raw definition (class-string, closure or value).

setActionDirectory()

public function setActionDirectory( string $actionDirectory ): static;

Set the filesystem root that backs the base namespace.

setBaseNamespace()

public function setBaseNamespace( string $baseNamespace ): static;

Set the base namespace the convention router derives Actions from.

setWordSeparator()

public function setWordSeparator( string $wordSeparator ): static;

Set the single delimiter between words in a path segment.

ADR\Container\AdrProvider

Registers the ADR seams in the container; concretes autowire.

Used instead of Phalcon\Container\Provider\Web for ADR applications. It shares the short aliases (request/response/router/eventsManager) but binds the ADR contracts behind them.

Uses Phalcon\ADR\Dispatcher · Phalcon\ADR\Emitter\SapiEmitter · Phalcon\ADR\Responder\JsonResponder · Phalcon\ADR\Router\AttributeFilter · Phalcon\ADR\Router\Router · Phalcon\Contracts\ADR\Dispatcher · Phalcon\Contracts\ADR\Emitter\Emitter · Phalcon\Contracts\ADR\Responder\Responder · Phalcon\Contracts\ADR\Router\AttributeFilter · Phalcon\Contracts\ADR\Router\Router · Phalcon\Contracts\Container\Service\Collection · Phalcon\Contracts\Container\Service\Provider · Phalcon\Contracts\Events\Manager · Phalcon\Contracts\Http\AttributeRequest · Phalcon\Contracts\Logger\Logger · Phalcon\Events\Manager · Phalcon\Html\Escaper · Phalcon\Html\Escaper\EscaperInterface · Phalcon\Html\TagFactory · Phalcon\Http\Request · Phalcon\Http\Response · Phalcon\Http\ResponseInterface · Phalcon\Logger\Adapter\Noop · Phalcon\Logger\Logger

Method Summary

Methods

provide()

public function provide( Collection $services ): void;

ADR\Dispatcher

Resolves the Action (and middleware) through the container, wraps it in the pipeline and runs it, firing the pipeline:* events. Global middleware is resolved once and cached; only route middleware resolves per request.

The container resolution is the one deliberate Service Locator: it uses the resolve-only IocContainer contract, so a container swap is a two-method adapter. Everything else is constructor-injected.

Uses Phalcon\ADR\Events\Event · Phalcon\ADR\Exceptions\NotAnAction · Phalcon\Contracts\ADR\ADRTypes · Phalcon\Contracts\ADR\Action · Phalcon\Contracts\ADR\Dispatcher · Phalcon\Contracts\ADR\Middleware · Phalcon\Contracts\Container\Ioc\IocContainer · Phalcon\Contracts\Events\Manager · Phalcon\Contracts\Http\AttributeRequest · Phalcon\Http\ResponseInterface

Method Summary

Properties

Methods

__construct()

public function __construct(
    IocContainer $container,
    Manager $events,
    array $globalMiddleware = []
);

dispatch()

public function dispatch(
    string $actionClass,
    AttributeRequest $request,
    array $routeMiddleware = []
): ResponseInterface;

resolveAll()

protected function resolveAll( array $classes ): array;

resolveGlobal()

protected function resolveGlobal(): array;

ADR\Emitter\SapiEmitter

Emits a response through the SAPI (headers + body via Response::send()). Refuses to emit once headers have already been sent.

Uses Phalcon\ADR\Exceptions\HeadersAlreadySent · Phalcon\Contracts\ADR\Emitter\Emitter · Phalcon\Http\ResponseInterface

Method Summary

Methods

emit()

public function emit( ResponseInterface $response ): void;

ADR\ErrorResponder

Turns a thrown exception into a response through the responder chain.

The full diagnostic (class, message, file:line and the exception itself) goes to the log with a correlation reference; the client receives only a generic message plus that same reference, unless debug mode is on. Exceptions are mapped to statuses deterministically: an exact class match first, then the ancestor chain, so map ordering never matters.

Uses Phalcon\ADR\Exceptions\MethodNotAllowed · Phalcon\ADR\Exceptions\RouteNotFound · Phalcon\ADR\Payload\Payload · Phalcon\ADR\Payload\Status · Phalcon\Contracts\ADR\ADRTypes · Phalcon\Contracts\ADR\Responder\Responder · Phalcon\Contracts\Logger\Logger · Phalcon\Http\RequestInterface · Phalcon\Http\ResponseInterface · Throwable

Method Summary

Properties

Methods

__construct()

public function __construct(
    Responder $chain,
    Logger $logger,
    bool $debug = false,
    array $exceptionMap = []
);

handle()

public function handle(
    RequestInterface $request,
    ResponseInterface $response,
    Throwable $exception
): ResponseInterface;

correlationId()

protected function correlationId( RequestInterface $request ): string;

defaultMap()

protected function defaultMap(): array;

details()

protected function details(
    Throwable $exception,
    string $ref,
    string $status = Status::ERROR
): array;

reason()

protected function reason( string $status ): string;

The message that goes with the status. Reporting Internal Server Error next to a 404 tells the client the opposite of what happened.

ADR\EventfulHandler

The terminal handler of the pipeline: fires the adr:* events around the Action’s execution.

Uses Phalcon\ADR\Events\Event · Phalcon\Contracts\ADR\Action · Phalcon\Contracts\ADR\Handler · Phalcon\Contracts\Events\Manager · Phalcon\Contracts\Http\AttributeRequest · Phalcon\Http\ResponseInterface

Method Summary

Properties

Methods

__construct()

public function __construct(
    Action $action,
    Manager $events
);

__invoke()

public function __invoke( AttributeRequest $request ): ResponseInterface;

ADR\Events\Event

The ADR event vocabulary, fired through the native events manager.

Constants

ADR\Exceptions\ActionDirectoryNotSet

Thrown when the router is asked to match without an action directory; the convention cannot resolve sub-namespaces without one.

Method Summary

Methods

__construct()

public function __construct();

ADR\Exceptions\Exception

Generic exception for the ADR component, and the base for every typed ADR exception.

Uses Exception · Phalcon\Contracts\ADR\Exceptions\ADRThrowable

ADR\Exceptions\HeadersAlreadySent

Thrown when the emitter is asked to send a response after headers have already been sent.

Method Summary

Methods

__construct()

public function __construct();

ADR\Exceptions\MethodNotAllowed

Thrown when a route matches the path but not the request method.

Method Summary

Methods

__construct()

public function __construct();

ADR\Exceptions\NotAnAction

Thrown when the dispatcher resolves a class that is not an ADR Action.

Method Summary

Methods

__construct()

public function __construct( string $className = "" );

ADR\Exceptions\OutputAlreadySent

Thrown when the emitter is asked to send a response after output has already been sent.

Method Summary

Methods

__construct()

public function __construct();

ADR\Exceptions\RouteNotFound

Thrown when no route matches the request.

Method Summary

Methods

__construct()

public function __construct();

ADR\Front\AbstractHttpFront

Boots a container, builds the Application, handles the request and emits the response. Userland front controllers override loadEnvironment(), registerProviders() and optionally getApplication(); bootstrap is exit((new AppFront(dirname(__DIR__)))->run());.

Uses Phalcon\ADR\Application · Phalcon\ADR\Container\AdrProvider · Phalcon\Container\Container · Phalcon\Contracts\ADR\Application · Phalcon\Contracts\ADR\Emitter\Emitter · Phalcon\Contracts\Front\FrontController · Phalcon\Contracts\Http\AttributeRequest · Throwable

Method Summary

Properties

Methods

__construct()

public function __construct( string $projectRoot );

boot()

final public function boot(): Container;

Builds the container, loads the environment and registers the providers, returning the container for consumers that need it before (or instead of) run(). The container is built once and cached, so calling boot() and then run() reuses the same instance.

run()

final public function run(): int;

buildContainer()

protected function buildContainer(): Container;

getApplication()

protected function getApplication( Container $container ): ApplicationInterface;

Builds the Application the front will hand the request to. Override to configure it (setBaseNamespace()/secureWith()) or to wire a different Phalcon\Contracts\ADR\Application implementation.

handleBootError()

protected function handleBootError( \Throwable $exception ): int;

loadEnvironment()

protected function loadEnvironment( Container $container ): void;

registerProviders()

protected function registerProviders( Container $container ): void;

ADR\Front\HttpFront

Concrete default HTTP front controller. Boots the ADR provider and runs the application with the framework defaults; subclass to override loadEnvironment() or registerProviders().

ADR\Input\Input

Generic, string-keyed input bag for an Action.

fromRequest() merges the request query, parsed body and route attributes into a single bag (later sources win). Extend it to build a typed, per-domain input value object: the factories use late static binding, so a subclass’s fromRequest() / fromArray() return that subclass.

Uses Phalcon\Contracts\ADR\ADRTypes · Phalcon\Contracts\Http\AttributeRequest

Method Summary

Properties

Methods

__construct()

public function __construct( array $data = [] );

fromArray()

public static function fromArray( array $data ): static;

fromRequest()

public static function fromRequest( AttributeRequest $request ): static;

get()

public function get(
    string $key,
    mixed $defaultValue = null
): mixed;

has()

public function has( string $key ): bool;

toArray()

public function toArray(): array;

ADR\Middleware\CorsMiddleware

CORS middleware. Inert by default: it emits nothing until an origin allowlist is configured, and only for requests whose Origin is on it. The allowed origin is always echoed back explicitly, so credentials are never paired with a wildcard origin. Preflight OPTIONS requests are answered directly.

Uses Phalcon\Contracts\ADR\ADRTypes · Phalcon\Contracts\ADR\Handler · Phalcon\Contracts\ADR\Middleware · Phalcon\Contracts\Http\AttributeRequest · Phalcon\Http\Response · Phalcon\Http\ResponseInterface · Phalcon\Traits\Support\Helper\Arr\GetTrait

Method Summary

Properties

Methods

__construct()

public function __construct( array $config = [] );

__invoke()

public function __invoke(
    AttributeRequest $request,
    Handler $next
): ResponseInterface;

applyHeaders()

protected function applyHeaders(
    ResponseInterface $response,
    string $origin
): void;

isAllowed()

protected function isAllowed( string $origin ): bool;

ADR\Middleware\MethodOverrideMiddleware

Thin enabler for the native _method override.

Request::getMethod() already honors X-HTTP-Method-Override and, when the parameter-override flag is on, the _method field. This middleware only turns that flag on, and only for a POST request whose _method names a safe verb (PUT/PATCH/DELETE), so _method cannot spoof an arbitrary method.

The flag lives on Phalcon\Http\Request, not on the request contract, so a request implementation that does not carry it is simply passed through.

Uses Phalcon\Contracts\ADR\ADRTypes · Phalcon\Contracts\ADR\Handler · Phalcon\Contracts\ADR\Middleware · Phalcon\Contracts\Http\AttributeRequest · Phalcon\Http\ResponseInterface

Method Summary

Properties

Methods

__invoke()

public function __invoke(
    AttributeRequest $request,
    Handler $next
): ResponseInterface;

ADR\Middleware\RequestIdMiddleware

Ensures every request carries an X-Request-Id, reusing an incoming one or generating it, exposing it on the request attributes and the response.

Uses Phalcon\Contracts\ADR\Handler · Phalcon\Contracts\ADR\Middleware · Phalcon\Contracts\Http\AttributeRequest · Phalcon\Http\ResponseInterface

Method Summary

Methods

__invoke()

public function __invoke(
    AttributeRequest $request,
    Handler $next
): ResponseInterface;

ADR\Middleware\TimingMiddleware

Adds an X-Response-Time header measuring how long the rest of the pipeline took to produce the response.

Uses Phalcon\Contracts\ADR\Handler · Phalcon\Contracts\ADR\Middleware · Phalcon\Contracts\Http\AttributeRequest · Phalcon\Http\ResponseInterface

Method Summary

Methods

__invoke()

public function __invoke(
    AttributeRequest $request,
    Handler $next
): ResponseInterface;

ADR\Payload\Payload

Immutable payload produced by the domain layer.

Every with*() method returns a new instance, leaving the receiver unchanged. Named factories provide a concise way to create a payload for the commonly used statuses.

Uses Phalcon\Contracts\ADR\Payload\Payload · Throwable

Method Summary

Properties

Methods

accepted()

public static function accepted( mixed $result = null ): PayloadContract;

Creates a payload with the ACCEPTED status.

authenticated()

public static function authenticated( mixed $result = null ): PayloadContract;

Creates a payload with the AUTHENTICATED status.

authorized()

public static function authorized( mixed $result = null ): PayloadContract;

Creates a payload with the AUTHORIZED status.

created()

public static function created( mixed $result = null ): PayloadContract;

Creates a payload with the CREATED status.

deleted()

public static function deleted( mixed $result = null ): PayloadContract;

Creates a payload with the DELETED status.

error()

public static function error( mixed $messages = null ): PayloadContract;

Creates a payload with the ERROR status.

forbidden()

public static function forbidden( mixed $messages = null ): PayloadContract;

Creates a payload with the NOT_AUTHORIZED status (authenticated but not allowed - HTTP 403).

found()

public static function found( mixed $result = null ): PayloadContract;

Creates a payload with the FOUND status.

getException()

public function getException(): Throwable|null;

Gets the exception thrown in the domain layer, if any.

getExtras()

public function getExtras(): mixed;

Gets the arbitrary extra domain information.

getInput()

public function getInput(): mixed;

Gets the domain input.

getMessages()

public function getMessages(): mixed;

Gets the domain messages.

getResult()

public function getResult(): mixed;

Gets the domain result.

getStatus()

public function getStatus(): mixed;

Gets the payload status.

invalid()

public static function invalid( mixed $messages = null ): PayloadContract;

Creates a payload with the NOT_VALID status.

notAccepted()

public static function notAccepted( mixed $messages = null ): PayloadContract;

Creates a payload with the NOT_ACCEPTED status.

notCreated()

public static function notCreated( mixed $messages = null ): PayloadContract;

Creates a payload with the NOT_CREATED status.

notDeleted()

public static function notDeleted( mixed $messages = null ): PayloadContract;

Creates a payload with the NOT_DELETED status.

notFound()

public static function notFound( mixed $messages = null ): PayloadContract;

Creates a payload with the NOT_FOUND status.

notUpdated()

public static function notUpdated( mixed $messages = null ): PayloadContract;

Creates a payload with the NOT_UPDATED status.

processing()

public static function processing( mixed $result = null ): PayloadContract;

Creates a payload with the PROCESSING status.

success()

public static function success( mixed $result = null ): PayloadContract;

Creates a payload with the SUCCESS status.

unauthenticated()

public static function unauthenticated( mixed $messages = null ): PayloadContract;

Creates a payload with the NOT_AUTHENTICATED status (identity not established - HTTP 401).

updated()

public static function updated( mixed $result = null ): PayloadContract;

Creates a payload with the UPDATED status.

valid()

public static function valid( mixed $result = null ): PayloadContract;

Creates a payload with the VALID status.

withException()

public function withException( Throwable $exception ): PayloadContract;

Returns a copy of the payload with the given exception.

withExtras()

public function withExtras( mixed $extras ): PayloadContract;

Returns a copy of the payload with the given extras.

withInput()

public function withInput( mixed $input ): PayloadContract;

Returns a copy of the payload with the given input.

withMessages()

public function withMessages( mixed $messages ): PayloadContract;

Returns a copy of the payload with the given messages.

withResult()

public function withResult( mixed $result ): PayloadContract;

Returns a copy of the payload with the given result.

withStatus()

public function withStatus( mixed $status ): PayloadContract;

Returns a copy of the payload with the given status.

ADR\Payload\PayloadFactory

Thin, injectable factory mirroring the Payload named factories.

It exists so that payload creation can be registered as a service in the DI container and substituted in tests, rather than calling the static factories directly.

Uses Phalcon\Contracts\ADR\Payload\Payload

Method Summary

Methods

accepted()

public function accepted( mixed $result = null ): PayloadInterface;

Creates a payload with the ACCEPTED status.

authenticated()

public function authenticated( mixed $result = null ): PayloadInterface;

Creates a payload with the AUTHENTICATED status.

authorized()

public function authorized( mixed $result = null ): PayloadInterface;

Creates a payload with the AUTHORIZED status.

created()

public function created( mixed $result = null ): PayloadInterface;

Creates a payload with the CREATED status.

deleted()

public function deleted( mixed $result = null ): PayloadInterface;

Creates a payload with the DELETED status.

error()

public function error( mixed $messages = null ): PayloadInterface;

Creates a payload with the ERROR status.

forbidden()

public function forbidden( mixed $messages = null ): PayloadInterface;

Creates a payload with the NOT_AUTHORIZED status (HTTP 403).

found()

public function found( mixed $result = null ): PayloadInterface;

Creates a payload with the FOUND status.

invalid()

public function invalid( mixed $messages = null ): PayloadInterface;

Creates a payload with the NOT_VALID status.

notAccepted()

public function notAccepted( mixed $messages = null ): PayloadInterface;

Creates a payload with the NOT_ACCEPTED status.

notCreated()

public function notCreated( mixed $messages = null ): PayloadInterface;

Creates a payload with the NOT_CREATED status.

notDeleted()

public function notDeleted( mixed $messages = null ): PayloadInterface;

Creates a payload with the NOT_DELETED status.

notFound()

public function notFound( mixed $messages = null ): PayloadInterface;

Creates a payload with the NOT_FOUND status.

notUpdated()

public function notUpdated( mixed $messages = null ): PayloadInterface;

Creates a payload with the NOT_UPDATED status.

processing()

public function processing( mixed $result = null ): PayloadInterface;

Creates a payload with the PROCESSING status.

success()

public function success( mixed $result = null ): PayloadInterface;

Creates a payload with the SUCCESS status.

unauthenticated()

public function unauthenticated( mixed $messages = null ): PayloadInterface;

Creates a payload with the NOT_AUTHENTICATED status (HTTP 401).

updated()

public function updated( mixed $result = null ): PayloadInterface;

Creates a payload with the UPDATED status.

valid()

public function valid( mixed $result = null ): PayloadInterface;

Creates a payload with the VALID status.

ADR\Payload\Status

Holds the status codes for the payload.

The two failure-related statuses are distinct, following the Aura.Payload lineage:

• ERROR means an exception was raised while the domain layer was running. By convention, Payload::withException() pairs with the ERROR status.
• FAILURE means the domain layer ran to completion but declined the request (for example, a business rule was not satisfied); no exception was raised.

@see Payload

Constants

ADR\Pipeline

Self-recursive middleware runner. It is itself a Handler: it carries an index and hands a new Pipeline (advanced by one) forward as the next handler, so next is always a real Handler - no anonymous classes or callables.

When the middleware is exhausted it invokes the terminal handler (the Action).

Uses Phalcon\Contracts\ADR\Handler · Phalcon\Contracts\ADR\Middleware · Phalcon\Contracts\Http\AttributeRequest · Phalcon\Http\ResponseInterface

Method Summary

Properties

Methods

__construct()

public function __construct(
    array $middleware,
    Handler $terminal,
    int $index = 0
);

__invoke()

public function __invoke( AttributeRequest $request ): ResponseInterface;

ADR\Responder\AbstractFormattedResponder

Base for content-type responders: composes Status, Redirect and Format responders into a chain. Subclasses bind the formatter(s).

Uses Phalcon\Contracts\ADR\Responder\Formatter\Formatter

Method Summary

Methods

__construct()

public function __construct( array $formatters = [] );

ADR\Responder\ChainResponder

Composes single-purpose responders. Each link receives the request, the response threaded so far, and the payload, and returns the response.

Uses Phalcon\Contracts\ADR\Payload\Payload · Phalcon\Contracts\ADR\Responder\Responder · Phalcon\Http\RequestInterface · Phalcon\Http\ResponseInterface

Method Summary

Properties

Methods

__construct()

public function __construct( array $links = [] );

__invoke()

public function __invoke(
    RequestInterface $request,
    ResponseInterface $response,
    Payload $payload
): ResponseInterface;

with()

public function with( Responder $link ): ChainResponder;

ADR\Responder\FormatResponder

Negotiates a formatter against the request Accept header and renders the payload as the response body + content type.

If no formatter accepts the header it falls back to the first (default) formatter, so the content type and body are never left unset.

Uses Phalcon\Contracts\ADR\Payload\Payload · Phalcon\Contracts\ADR\Responder\Formatter\Formatter · Phalcon\Contracts\ADR\Responder\Responder · Phalcon\Http\RequestInterface · Phalcon\Http\ResponseInterface

Method Summary

Properties

Methods

__construct()

public function __construct( array $formatters = [] );

__invoke()

public function __invoke(
    RequestInterface $request,
    ResponseInterface $response,
    Payload $payload
): ResponseInterface;

ADR\Responder\Formatter\JsonFormatter

Renders a payload as JSON.

Uses Phalcon\Contracts\ADR\Payload\Payload · Phalcon\Contracts\ADR\Responder\Formatter\Formatter

Method Summary

Methods

accepts()

public function accepts( string $acceptHeader ): bool;

contentType()

public function contentType(): string;

format()

public function format( Payload $payload ): string;

ADR\Responder\Formatter\TextFormatter

Renders a payload as plain text.

The payload is untyped, so anything that cannot be expressed as a string - an object without __toString(), for instance - renders as an empty body.

Uses Phalcon\Contracts\ADR\Payload\Payload · Phalcon\Contracts\ADR\Responder\Formatter\Formatter · Stringable

Method Summary

Methods

accepts()

public function accepts( string $acceptHeader ): bool;

contentType()

public function contentType(): string;

format()

public function format( Payload $payload ): string;

ADR\Responder\JsonResponder

A formatted responder bound to the JSON formatter.

Uses Phalcon\ADR\Responder\Formatter\JsonFormatter

Method Summary

Methods

__construct()

public function __construct();

ADR\Responder\Redirect

Value object describing a redirect. An Action sets it on the payload; the RedirectResponder turns it into a Location header and status code.

Method Summary

Properties

Methods

__construct()

public function __construct(
    string $url,
    int $status = 302,
    bool $external = false
);

external()

public function external(): bool;

Whether the target is an explicit external redirect. Internal (the default) redirects refuse an absolute or protocol-relative target so a request-derived value cannot become an open redirect (CWE-601).

permanent()

public static function permanent( string $url ): Redirect;

seeOther()

public static function seeOther( string $url ): Redirect;

status()

public function status(): int;

temporary()

public static function temporary( string $url ): Redirect;

url()

public function url(): string;

ADR\Responder\RedirectResponder

Applies a Redirect value object carried on the payload result: sets the status code and the Location header. A no-op when the result is not a redirect.

Uses Phalcon\Contracts\ADR\Payload\Payload · Phalcon\Contracts\ADR\Responder\Responder · Phalcon\Http\RequestInterface · Phalcon\Http\ResponseInterface

Method Summary

Methods

__invoke()

public function __invoke(
    RequestInterface $request,
    ResponseInterface $response,
    Payload $payload
): ResponseInterface;

ADR\Responder\StatusMapper

Maps a domain Status to an HTTP status code.

Status is the single source of truth: the default map covers every Status constant. Any status that is not mapped resolves to 500, never a silent 200. Every entry can be overridden through the constructor.

Uses Phalcon\ADR\Payload\Status · Phalcon\Contracts\ADR\ADRTypes

Method Summary

Properties

Methods

__construct()

public function __construct( array $overrides = [] );

toHttpCode()

public function toHttpCode( string $status ): int;

Returns the HTTP status code for the given domain status.

An unmapped status resolves to 500 (server error), never a silent 200.

ADR\Responder\StatusResponder

Sets the response HTTP status code from the payload status, via StatusMapper.

The payload status is untyped, so anything that cannot be expressed as a string - an array, an object - leaves the response status code untouched.

Uses Phalcon\Contracts\ADR\Payload\Payload · Phalcon\Contracts\ADR\Responder\Responder · Phalcon\Http\RequestInterface · Phalcon\Http\ResponseInterface

Method Summary

Properties

Methods

__construct()

public function __construct( StatusMapper|null $mapper = null );

__invoke()

public function __invoke(
    RequestInterface $request,
    ResponseInterface $response,
    Payload $payload
): ResponseInterface;

ADR\Responder\TextResponder

A formatted responder bound to the text formatter.

Uses Phalcon\ADR\Responder\Formatter\TextFormatter

Method Summary

Methods

__construct()

public function __construct();

ADR\Responder\ViewResponder

Renders a template from the payload and returns it as an HTML response.

The HTML sibling of JsonResponder: serialization is swapped for rendering, the status mapping and the Responder contract stay the same. It depends on the neutral Renderer contract only, so the ADR component never imports the MVC view.

Uses Phalcon\Contracts\ADR\ADRTypes · Phalcon\Contracts\ADR\Payload\Payload · Phalcon\Contracts\ADR\Responder\Responder · Phalcon\Contracts\View\Renderer · Phalcon\Http\RequestInterface · Phalcon\Http\ResponseInterface

Method Summary

Properties

Methods

__construct()

public function __construct(
    Renderer $renderer,
    StatusMapper $statusMapper,
    string $template = ""
);

__invoke()

public function __invoke(
    RequestInterface $request,
    ResponseInterface $response,
    Payload $payload
): ResponseInterface;

withTemplate()

public function withTemplate( string $template ): static;

Returns a copy of the responder bound to the given template. The action names the view; the payload stays free of presentation concerns.

viewData()

protected function viewData( Payload $payload ): array;

Flattens the payload into the variables handed to the template. The extras travel as they are, so an action can hand the view whatever the result should not carry.

ADR\Router\AttributeFilter

Reads an Action’s optional static params() declaration and transforms the router’s positional tail segments: regex match (miss => RouteNotFound), cast to a scalar type, then an optional converter closure. Declaration order names the attributes; a declared parameter with no segment is skipped; surplus segments pass through under their positional keys. An Action without params() is returned unchanged.

Uses Phalcon\ADR\Exceptions\RouteNotFound · Phalcon\Contracts\ADR\ADRTypes · Phalcon\Contracts\ADR\Router\AttributeFilter

Method Summary

Methods

filter()

public function filter(
    string $actionClass,
    array $attributes
): array;

cast()

protected function cast(
    string $value,
    string $type
): float|int|string;

ADR\Router\Router

Convention router. method + static path -> Action class; the path tail becomes positional request attributes. Middleware is resolved from a namespace-prefix map (group semantics); global middleware stays on the pipeline. No route table.

The convention

Every static path segment is a namespace segment, and the class name is the verb followed by all of those segments concatenated:

GET / -> Get GET /profiles -> Profiles\GetProfiles GET /company/all -> Company\All\GetCompanyAll GET /company/all/7 -> Company\All\GetCompanyAll with [“7”] POST /session/forgot-password -> Session\ForgotPassword\PostSessionForgotPassword

Guarantees

• One path names exactly one class; that class names exactly one path.
• The derived name must equal the declared class name byte for byte. A class that only resolves case-insensitively is not a match.
• classFor() and pathFor() are pure functions of their input. Neither touches the filesystem, and neither consults any Action but the one it was given, so adding or deleting an Action can never move another one’s URL.
• There is no candidate list and no first-that-exists. Nothing can be shadowed.

Constraints - these are load-bearing, not style

• Arguments always trail the static path. /album/edit/1, never /album/1/edit. A class name encodes which segments exist, not where a value sits among them; putting an argument in the middle would require consulting some other Action to find the boundary, and that is exactly the coupling this convention exists to avoid.
• params() never affects routing. It constrains, casts and converts attributes after a match. A wrong declaration is a validation bug, never a 404.
• No route table, no compile step, no cache. Resolution is a string derivation plus one class_exists. In PHP’s shared-nothing model a table must be rebuilt or reloaded on every request, and that cost dominates matching - which is why this router is faster in practice than a cached table-driven one.
• Nothing may be layered onto the naming convention to express argument position, arity or ordering. Any such declaration is a path template in disguise, and a path template belongs in a declared-route router, not here.

The cost of all of this is /album/edit/1 rather than /album/1/edit. That is a spelling difference, not a capability one - and it is not a deviation from any standard. REST is Fielding’s dissertation, not an RFC; RFC 3986 and RFC 9110 both leave path structure entirely to the origin server.

Uses Phalcon\ADR\Exceptions\ActionDirectoryNotSet · Phalcon\ADR\Exceptions\MethodNotAllowed · Phalcon\Contracts\ADR\ADRTypes · Phalcon\Contracts\ADR\Router\Router · Phalcon\Contracts\ADR\Router\RouterMatch · Phalcon\Http\RequestInterface · ReflectionClass

Method Summary

Properties

Methods

candidatesFor()

public function candidatesFor(
    string $method,
    string $path
): array;

Every Action class this router would try for the given method and path, in the order it tries them. The first that exists wins at match time. Namespace descent consults the filesystem, so the list depends on the action directory.

The names are derived, not resolved: a candidate is what the convention would call the class, whether or not that class exists.

classFor()

public function classFor(
    string $method,
    string $path
): string;

The class this convention names for a fully static path, derived without consulting the filesystem.

candidatesFor() cannot answer this. It walks the action directory to find where static segments end, so a path whose directories do not exist yet yields nothing - and a generator needs the name precisely in order to create them. Every static segment is a namespace segment, so the answer is unambiguous and pathFor() inverts it exactly.

Placeholders are the caller’s concern: pass the static prefix only.

match()

public function match( RequestInterface $request ): RouterMatchInterface|null;

methodFor()

public function methodFor( string $className ): string|null;

pathFor()

public function pathFor( string $className ): string|null;

setActionDirectory()

public function setActionDirectory( string $actionDirectory ): RouterInterface;

setBaseNamespace()

public function setBaseNamespace( string $baseNamespace ): RouterInterface;

setMiddlewareMap()

public function setMiddlewareMap( array $middlewareMap ): RouterInterface;

setWordSeparator()

public function setWordSeparator( string $wordSeparator ): RouterInterface;

actionParams()

protected function actionParams( string $className ): array;

An Action’s declared positional parameters, or an empty array when it declares none.

This is what lets an argument sit between two static segments: the walk needs to know how many segments a level consumes before it can carry on matching. params() is static and already exists for filtering and casting, so nothing new is asked of an Action - but declaring it now decides routing, not just validation.

camelize()

protected function camelize( string $segment ): string;

decamelize()

protected function decamelize( string $part ): string;

deriveCandidates()

protected function deriveCandidates(
    string $method,
    string $path
): array;

The single derivation of the routing convention.

Every static path segment becomes a namespace segment, and the class name is the verb followed by all of those segments concatenated - so /company/all is Company\All\GetCompanyAll and nothing else. One path yields exactly one class, and pathFor() inverts it exactly.

Segments are consumed while the matching directory exists; whatever remains is a dynamic argument. That walk decides where static ends and dynamic begins - it no longer chooses between competing class shapes, because there is only one.

hasSubNamespace()

protected function hasSubNamespace( string $subNamespace ): bool;

locate()

protected function locate(
    string $method,
    string $path
): array|null;

The first derived candidate whose class actually exists, together with the segments the walk did not consume.

middlewareFor()

protected function middlewareFor( string $className ): array;

verbOf()

protected function verbOf( string $className ): string|null;

The class-name-form verb the given Action class carries, or null when the class is not one this convention would have produced.

The class name is the verb followed by every namespace segment, so the namespace alone reconstructs the static path and the class name only has to agree with it. Anything that does not agree is not a class this convention would ever have produced.

Shared by pathFor() and methodFor() so that rule is stated once.

verbs()

protected function verbs(): array;

The HTTP verbs the convention recognizes, in class-name form.

ADR\Router\RouterMatch

Immutable result of a successful route match.

Uses Phalcon\Contracts\ADR\ADRTypes · Phalcon\Contracts\ADR\Router\RouterMatch

Method Summary

Properties

Methods

__construct()

public function __construct(
    string $action,
    array $attributes = [],
    array $middleware = [],
    string|null $name = null
);

getAction()

public function getAction(): string;

getAttributes()

public function getAttributes(): array;

getMiddleware()

public function getMiddleware(): array;

getName()

public function getName(): string|null;