ClamavController
Base MVC controller for PhalconKit applications.
The class keeps Phalcon's native controller behavior and adds typed injectable properties used throughout the framework. Application controllers can extend it when they want direct access to the PhalconKit DI helper surface without re-declaring those service properties.
- Full name:
\PhalconKit\Modules\Api\Controllers\ClamavController - Parent class:
\PhalconKit\Mvc\Controller\Rest
Inherited 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:
| Parameter | Type | Description |
|---|---|---|
$code | int | HTTP status code to expose in the response and payload. |
$status | string|null | Optional status text; when null, the status is |
| resolved from the current response or {@see \PhalconKit\Http\StatusCode}. | ||
$response | mixed | Response body stored under the REST response |
| envelope key. |
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:
| Parameter | Type | Description |
|---|---|---|
$response | mixed | |
$code | ?int | |
$status | ?string | |
$jsonOptions | int | |
$depth | int |
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:
| Parameter | Type | Description |
|---|---|---|
$key | string | |
$value | mixed |
setRestViewVars
Set several public view fields for the REST response payload.
protected setRestViewVars(array<string,mixed> $vars, bool $merge = true): void
Parameters:
| Parameter | Type | Description |
|---|---|---|
$vars | array | View fields to expose under the response |
envelope's view key. | ||
$merge | bool | Whether to merge with existing view variables. This |
matches Phalcon's setVars() default behavior used by legacy actions. |
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:
| Parameter | Type | Description |
|---|---|---|
$response | mixed | |
$code | int | |
$status | string |
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:
| Parameter | Type | Description |
|---|---|---|
$messages | mixed | A Phalcon messages collection, iterable list, |
| single message, or any legacy message payload returned by model/action | ||
| code. | ||
$emptyStatusCode | int | Status code used when no message payload is |
| available. | ||
$defaultStatusCode | int | Status code used when messages exist but no |
| explicit HTTP status code is attached. |
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:
| Parameter | Type | Description |
|---|---|---|
$messages | mixed |
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:
| Parameter | Type | Description |
|---|---|---|
$messages | mixed | A Phalcon messages collection, iterable list, |
| single message, or any legacy message payload returned by model/action | ||
| code. | ||
$response | mixed | Response body stored under the REST response |
envelope key. Standard framework actions usually pass false. | ||
$emptyStatusCode | int | Status code used when no message payload is |
| available. | ||
$defaultStatusCode | int | Status code used when messages exist but no |
| explicit HTTP status code is attached. |
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:
| Parameter | Type | Description |
|---|---|---|
$message | mixed | Candidate message value from a model/action failure. |
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:
| Parameter | Type | Description |
|---|---|---|
$payload | array | |
$code | int |
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:
| Parameter | Type | Description |
|---|---|---|
$isAuthenticated | bool|null | Indicates if the request is authenticated; |
| defaults to checking the current identity. |
getDebugInfo
Gather debug context.
public getDebugInfo(): array
afterExecuteRoute
Update the Dispatcher after executing the route.
public afterExecuteRoute(\Phalcon\Mvc\Dispatcher $dispatcher): void
Parameters:
| Parameter | Type | Description |
|---|---|---|
$dispatcher | \Phalcon\Mvc\Dispatcher | The Dispatcher instance. |
getParam
Retrieve a specific parameter value by key.
public getParam(string $key, array|string|null $filters = null, mixed|null $default = null, array|null $params = null): mixed
Parameters:
| Parameter | Type | Description |
|---|---|---|
$key | string | |
$filters | array|string|null | |
$default | mixed|null | |
$params | array|null |
Throws:
When request parameter filtering fails. - Exception
hasParam
Check if a given key exists in the parameter array.
public hasParam(string $key, array|null $params = null, bool $cached = true): bool
Parameters:
| Parameter | Type | Description |
|---|---|---|
$key | string | |
$params | array|null | |
$cached | bool |
getParams
Retrieve specific or all request parameters.
public getParams(array|null $fields = null, bool $cached = true, bool $deep = true): array<array-key,mixed>
Usage examples: - getParams() -> all params - getParams(['email', 'password']) -> only those keys - getParams(['email' => [Filter::TRIM], 'password']) -> filtered subset
Parameters:
| Parameter | Type | Description |
|---|---|---|
$fields | array|null | Keys or key=>filters to extract. |
$cached | bool | Whether to reuse cached raw parameters. |
$deep | bool | Whether to apply deep sanitization. |
Throws:
When request parameter filtering fails. - Exception
getAllParams
Retrieve all request parameters, optionally applying filters and caching results.
public getAllParams(array|null $filters = null, bool $cached = true, bool $deep = true): array<array-key,mixed>
Parameters:
| Parameter | Type | Description |
|---|---|---|
$filters | array|null | Temporary filters to apply. |
$cached | bool | Whether to reuse previously loaded parameters. |
$deep | bool | Whether to apply filters recursively. |
Throws:
When request parameter filtering fails. - Exception
collectRequestParams
Collect parameters from one request source based on the HTTP method.
private collectRequestParams(): array<array-key,mixed>
Body methods prefer an explicitly JSON request body and otherwise use the matching form body. Query parameters are intentionally not merged into body payloads so save endpoints cannot accidentally persist route/query controls such as with, filters, or order.
collectBodyParams
Collect body parameters from JSON or the method-specific form payload.
private collectBodyParams(mixed $formParams): array<array-key,mixed>
Parameters:
| Parameter | Type | Description |
|---|---|---|
$formParams | mixed | Method-specific form payload from Phalcon. |
collectJsonRequestParams
Collect JSON request parameters when a body request explicitly sends JSON.
private collectJsonRequestParams(): array<array-key,mixed>|null
hasJsonContentType
Return true for standard JSON and vendor JSON request content types.
private hasJsonContentType(): bool
normalizeRequestParams
Normalize Phalcon request accessor output into a parameter array.
private normalizeRequestParams(mixed $params): array<array-key,mixed>
Parameters:
| Parameter | Type | Description |
|---|---|---|
$params | mixed |
applyFilters
Apply filters to parameters (recursively if $deep is true).
public applyFilters(array<array-key,mixed> $params, array<string,array|string> $filters, bool $deep = true): array<array-key,mixed>
Parameters:
| Parameter | Type | Description |
|---|---|---|
$params | array | |
$filters | array | |
$deep | bool |
Throws:
When request parameter filtering fails. - Exception
deepSanitize
Recursively sanitize nested arrays.
private deepSanitize(mixed $value, array|string $filters): mixed
Parameters:
| Parameter | Type | Description |
|---|---|---|
$value | mixed | |
$filters | array|string |
Throws:
When request parameter filtering fails. - Exception
setDefaultFilters
Sets default filters, replacing any previously defined.
public setDefaultFilters(array<string,array|string> $filters): static
Parameters:
| Parameter | Type | Description |
|---|---|---|
$filters | array |
addDefaultFilters
Adds or merges new default filters to existing ones.
public addDefaultFilters(array<string,array|string> $filters): static
Parameters:
| Parameter | Type | Description |
|---|---|---|
$filters | array |
removeFilters
Remove one or many default filters by key.
public removeFilters(string|array<int,string> $keys): static
Parameters:
| Parameter | Type | Description |
|---|---|---|
$keys | string|array |
clearDefaultFilters
Clears all default filters.
public clearDefaultFilters(): static
getDefaultFilters
Get currently active default filters.
public getDefaultFilters(): array<string,array|string>
getRawParams
Retrieves the raw parameters from the request. If caching is enabled, it returns the cached parameters.
public getRawParams(bool $cached = true): array<array-key,mixed>
Parameters:
| Parameter | Type | Description |
|---|---|---|
$cached | bool | Determines whether to use cached parameters. Defaults to true. |
Return Value:
The raw request parameters.
getFractalManager
Get the Fractal Manager object.
public getFractalManager(): \PhalconKit\Fractal\Manager
This method returns the Fractal Manager object used for transforming data. If the Fractal Manager object is not already created, it will be created and initialized with the Fractal Serializer before being returned.
Return Value:
The Fractal Manager object.
setFractalManager
Set the Fractal Manager for the class.
public setFractalManager(\PhalconKit\Fractal\Manager|null $manager): void
Parameters:
| Parameter | Type | Description |
|---|---|---|
$manager | \PhalconKit\Fractal\Manager|null | The Fractal Manager to be set. If null, the Fractal Manager will be unset. |
getFractalSerializer
Get the fractal serializer for the class.
public getFractalSerializer(): \League\Fractal\Serializer\SerializerAbstract
Return Value:
The fractal serializer instance.
setFractalSerializer
Set the Fractal serializer for the class.
public setFractalSerializer(\League\Fractal\Serializer\SerializerAbstract $serializer): void
Parameters:
| Parameter | Type | Description |
|---|---|---|
$serializer | \League\Fractal\Serializer\SerializerAbstract | The Fractal serializer to be set. |
getTransformer
Get the transformer for the class.
public getTransformer(): \League\Fractal\TransformerAbstract
If the transformer has not been set, a new instance of ModelTransformer will be created.
Return Value:
The transformer for the class.
setTransformer
Set the transformer for the class.
public setTransformer(\League\Fractal\TransformerAbstract|null $transformer = null): void
Parameters:
| Parameter | Type | Description |
|---|---|---|
$transformer | \League\Fractal\TransformerAbstract|null | The transformer to be set. If null, the transformer will be unset. |
hasTransformer
Determine if a default transformer has been set for the fractal manager
public hasTransformer(): bool
Return Value:
Returns true if a default transformer has been set, false otherwise
transformModel
Transform a model using a transformer and optionally a fractal manager.
public transformModel(\Phalcon\Mvc\ModelInterface $model, \League\Fractal\TransformerAbstract|null $transformer = null, \PhalconKit\Fractal\Manager|null $fractalManager = null): array|null
Parameters:
| Parameter | Type | Description |
|---|---|---|
$model | \Phalcon\Mvc\ModelInterface | The model to transform. |
$transformer | \League\Fractal\TransformerAbstract|null | The transformer to use. If not provided, the default transformer will be used. |
$fractalManager | \PhalconKit\Fractal\Manager|null | The fractal manager to use. If not provided, the default fractal manager will be used. |
Return Value:
The transformed model as an array, or null if the transformation fails.
transformResultset
Transforms a resultset using the provided transformer and fractal manager.
public transformResultset(\Phalcon\Mvc\Model\ResultsetInterface $resultset, \League\Fractal\TransformerAbstract|null $transformer = null, \PhalconKit\Fractal\Manager|null $fractalManager = null): array|null
Parameters:
| Parameter | Type | Description |
|---|---|---|
$resultset | \Phalcon\Mvc\Model\ResultsetInterface | The resultset to be transformed. |
$transformer | \League\Fractal\TransformerAbstract|null | The transformer instance to be used for transformation (optional). |
$fractalManager | \PhalconKit\Fractal\Manager|null | The fractal manager instance to be used for transformation (optional). |
Return Value:
The transformed resultset as an array, or null if the transformation failed.
transformItem
Transform an item using the specified transformer and Fractal manager
public transformItem(mixed $data, \League\Fractal\TransformerAbstract|null $transformer = null, \PhalconKit\Fractal\Manager|null $fractalManager = null): array|null
Parameters:
| Parameter | Type | Description |
|---|---|---|
$data | mixed | The data to transform |
$transformer | \League\Fractal\TransformerAbstract|null | The transformer to use (optional, default is null) |
$fractalManager | \PhalconKit\Fractal\Manager|null | The Fractal manager to use (optional, default is null) |
Return Value:
The transformed item as an array
transformCollection
Transform a collection of data using a specified transformer and Fractal manager.
public transformCollection(mixed $data, \League\Fractal\TransformerAbstract|null $transformer = null, \PhalconKit\Fractal\Manager|null $fractalManager = null): array|null
Parameters:
| Parameter | Type | Description |
|---|---|---|
$data | mixed | The collection of data to be transformed. |
$transformer | \League\Fractal\TransformerAbstract|null | The transformer to be used. If not provided, the default transformer will be used. |
$fractalManager | \PhalconKit\Fractal\Manager|null | The Fractal manager to be used. If not provided, the default Fractal manager will be used. |
Return Value:
The transformed data as an array.
isDebugEnabled
Returns whether debug mode is enabled.
public isDebugEnabled(): bool
Return Value:
True if debug mode is enabled, false otherwise.
beforeExecuteRoute
public beforeExecuteRoute(): void
attachBehavior
Attach a behavior to the object.
public attachBehavior(string $eventClass, string|null $eventType = null, int|null $priority = null): void
Parameters:
| Parameter | Type | Description |
|---|---|---|
$eventClass | string | The behavior to attach. |
$eventType | string|null | The event type to attach the behavior to. If null, the behavior will be attached to the default event type. |
$priority | int|null | The priority of the behavior. If null, the behavior will be attached with the default priority. |
attachBehaviors
Attach multiple behaviors to the object.
public attachBehaviors(array $behaviors = [], string|null $eventType = null, int|null $priority = null): void
Parameters:
| Parameter | Type | Description |
|---|---|---|
$behaviors | array | An array of behaviors to attach. |
$eventType | string|null | The event type to attach the behaviors to. If null, the behaviors will be attached to all event types. |
$priority | int|null | The priority of the behaviors. If null, the behaviors will be attached with the default priority. |
getOrCreateEventsManager
protected getOrCreateEventsManager(): \Phalcon\Contracts\Events\Manager
attachConfiguredBehaviors
Attach legacy, non-action-scoped behavior config for this controller/model.
private attachConfiguredBehaviors(array<string|int,mixed> $behaviorsContext, array<int,string> $handlerCandidates, ?string $modelName): void
Parameters:
| Parameter | Type | Description |
|---|---|---|
$behaviorsContext | array | Permission behavior map. |
$handlerCandidates | array | Controller class/name aliases. |
$modelName | ?string |
attachConfiguredActionBehaviors
Attach action-scoped controller/model behavior config for this request.
private attachConfiguredActionBehaviors(array<string|int,mixed> $behaviorActionsContext, array<int,string> $handlerCandidates, array<int,string> $actionCandidates, ?string $modelName): void
Parameters:
| Parameter | Type | Description |
|---|---|---|
$behaviorActionsContext | array | Action behavior map. |
$handlerCandidates | array | Controller class/name aliases. |
$actionCandidates | array | Current action aliases. |
$modelName | ?string |
getBehaviorHandlerCandidates
private getBehaviorHandlerCandidates(): array<int,string>
getBehaviorActionCandidates
private getBehaviorActionCandidates(): array<int,string>
getBehaviorDispatcher
private getBehaviorDispatcher(): ?\Phalcon\Dispatcher\AbstractDispatcher
usesControllerAttributes
Determine whether controller attributes should augment permission config.
private usesControllerAttributes(): bool
indexAction
public indexAction(): void
scanAction
public scanAction(?string $filePath = null): bool
Parameters:
| Parameter | Type | Description |
|---|---|---|
$filePath | ?string |
pingAction
public pingAction(): bool
versionAction
public versionAction(): bool
statsAction
public statsAction(): bool
reloadAction
public reloadAction(): bool