RestResponse

• Full name: \PhalconKit\Mvc\Controller\Traits\RestResponse

Methods

setRestErrorResponse

Return a normalized REST error response.

public setRestErrorResponse(int $code = 400, string|null $status = null, mixed $response = null): \Phalcon\Http\ResponseInterface

This is the preferred exit path for controller failures that should use the standard JSON envelope but carry a non-2xx HTTP status. The response body remains caller-controlled so legacy actions can keep returning false, null, or a custom payload while the envelope status and code are still set consistently by

• See: \PhalconKit\Mvc\Controller\Traits\setRestResponse().

Parameters:

Return Value:

The finalized Phalcon response instance.

setRestResponse

Sending rest response as a http response.

public setRestResponse(mixed $response = null, ?int $code = null, ?string $status = null, int $jsonOptions = 0, int $depth = 512): \Phalcon\Http\ResponseInterface

The JSON envelope is intentionally centralized here so REST actions can focus on setting named view fields through

• See: \PhalconKit\Mvc\Controller\Traits\setRestViewVar() and

• See: \PhalconKit\Mvc\Controller\Traits\setRestViewVars(). The envelope keys are public constants because they are part of the API contract exposed to clients.

Parameters:

setRestViewVar

Set one public view field for the REST response payload.

protected setRestViewVar(string $key, mixed $value): void

The field is later serialized under the top-level view envelope key by

• See: \PhalconKit\Mvc\Controller\Traits\setRestResponse(). Standard framework actions should use the REST_VIEW_* constants instead of repeating string literals so response contracts remain discoverable and consistent.

Parameters:

setRestViewVars

Set several public view fields for the REST response payload.

protected setRestViewVars(array<string,mixed> $vars, bool $merge = true): void

Parameters:

getRestViewVars

Return view fields that are safe to serialize in a REST response.

protected getRestViewVars(): array<string,mixed>

Phalcon keeps internal render data under _; that key is deliberately stripped so controller actions cannot accidentally leak framework internals through the public JSON envelope.

buildRestPayload

Build the normalized REST JSON envelope.

protected buildRestPayload(mixed $response, int $code, string $status): array<string,mixed>

The shape is intentionally stable for backward compatibility: timestamp, status, code, response, and view are always present, while debug is added only when debug mode is enabled.

Parameters:

getRestActionFailureStatusCode

Resolve an HTTP status code for REST action failures carrying messages.

protected getRestActionFailureStatusCode(mixed $messages, int $emptyStatusCode = 400, int $defaultStatusCode = 422): int

Model, validation, and domain-rule failures normally include messages and map to 422 Unprocessable Entity. Framework-generated REST failures can attach explicit client-error codes to Phalcon messages; those 4xx codes are preserved so actions do not collapse invalid request intent, missing targets, forbidden operations, or conflicts into generic validation responses. Server errors stay owned by thrown exceptions or explicit controller calls to

• See: \PhalconKit\Mvc\Controller\Traits\setRestErrorResponse().

A failure without messages is treated as malformed input by default. The defaults can be overridden for actions that need a different legacy or protocol-specific response.

Parameters:

hasRestActionMessages

Determine whether a REST action failure carried any message payload.

protected hasRestActionMessages(mixed $messages): bool

PHP objects are never empty for empty(), even when they implement Countable and contain zero messages. Phalcon validation returns Phalcon\Messages\Messages, so status resolution must check the collection count instead of relying on PHP object truthiness.

Parameters:

setRestActionFailureResponse

Return a normalized REST error response for an action failure.

protected setRestActionFailureResponse(mixed $messages, mixed $response = false, int $emptyStatusCode = 400, int $defaultStatusCode = 422): \Phalcon\Http\ResponseInterface

This helper keeps REST actions from pre-mutating the response status and then relying on

• See: \PhalconKit\Mvc\Controller\Traits\setRestResponse() to pick that status back up. The action still owns its public view fields; this method only resolves the HTTP failure code from explicit message metadata and delegates the final envelope to
• See: \PhalconKit\Mvc\Controller\Traits\setRestErrorResponse().

Parameters:

Return Value:

The finalized Phalcon response instance.

getRestActionMessageStatusCode

Extract an explicit HTTP status code from one REST action message.

protected getRestActionMessageStatusCode(mixed $message): int|null

Only Phalcon message codes in the HTTP client-error range are considered. Normal validation messages often carry no code, or a non-HTTP code, and server-error responses should come from exceptions or explicit controller error handling instead of model/domain message metadata.

Parameters:

Return Value:

Explicit 4xx HTTP status code when present and valid; otherwise null.

applyCacheHeaders

Applies automatic, safe Cache-Control and ETag headers.

protected applyCacheHeaders(array $payload, int $code): void

Logic: - Only cache "GET" 200 responses. - Authenticated requests → private cache. - Unauthenticated requests → public cache. - Everything else → no-store.

Parameters:

setVaryHeaders

Sets the "Vary" HTTP header to assist caching proxies in varying responses based on specific headers, particularly authentication-related headers.

public setVaryHeaders(bool|null $isAuthenticated = null): void

Logic: - Retrieves the default list of headers from configuration. - If the user is authenticated, adds the authorization header. - Ensures the "Vary" header is set with all relevant headers, avoiding duplicates.

Parameters:

getDebugInfo

Gather debug context.

public getDebugInfo(): array

afterExecuteRoute

Update the Dispatcher after executing the route.

public afterExecuteRoute(\Phalcon\Mvc\Dispatcher $dispatcher): void

Parameters: