---
title: "Phalcon Contracts"
version: "5.20"
---
> Documentation Index
> Fetch the complete documentation index at: https://docs.phalcon.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Phalcon Contracts
:::info[NOTE]
All classes are prefixed with `Phalcon`
:::
## Contracts\ADR\ADRTypes
Interface
Central registry of the array shapes used across the ADR namespace.
This is a type registry, not a contract. It declares no members and must
not be implemented; it exists only so that every shape below has a single
definition, imported where it is needed with a phpstan-import-type tag
naming this interface as the source.
Alias names are prefixed with `adr_` because PHPStan resolves imported
type names per file and has no namespacing for them: the prefix is what
keeps generic names such as `middleware_map` from clashing with an alias
imported from another namespace into the same file.
- **`Phalcon\Contracts\ADR\ADRTypes`**
## Contracts\ADR\Action
Interface
Marker contract for a per-endpoint Action. An Action is a Handler:
`__invoke(request): response`.
- [`Phalcon\Contracts\ADR\Handler`](#contractsadrhandler)
- **`Phalcon\Contracts\ADR\Action`**
## Contracts\ADR\Application
Interface
Handles a request end to end: routes it, dispatches the Action and returns
the response, routing any error through the error responder.
- **`Phalcon\Contracts\ADR\Application`**
`Phalcon\Contracts\Http\AttributeRequest` · `Phalcon\Http\ResponseInterface`
### Method Summary
### Methods
handle()
```php
public function handle( AttributeRequest $request ): ResponseInterface;
```
## Contracts\ADR\Dispatcher
Interface
Resolves an Action by class name, builds the middleware pipeline around it and
runs it to produce a response.
- **`Phalcon\Contracts\ADR\Dispatcher`**
`Phalcon\Contracts\Http\AttributeRequest` · `Phalcon\Http\ResponseInterface`
### Method Summary
### Methods
dispatch()
```php
public function dispatch(
string $actionClass,
AttributeRequest $request,
array $routeMiddleware = []
): ResponseInterface;
```
## Contracts\ADR\Emitter\Emitter
Interface
Sends a response to the client. Called by the front controller only.
- **`Phalcon\Contracts\ADR\Emitter\Emitter`**
`Phalcon\Http\ResponseInterface`
### Method Summary
### Methods
emit()
```php
public function emit( ResponseInterface $response ): void;
```
## Contracts\ADR\Exceptions\ADRThrowable
Interface
Base throwable contract for the ADR component. Every ADR exception implements
it, so callers can catch all ADR errors with a single type.
- `\Throwable`
- **`Phalcon\Contracts\ADR\Exceptions\ADRThrowable`**
## Contracts\ADR\Handler
Interface
Receives the request and returns a response. The terminal handler in the
pipeline is the Action.
- **`Phalcon\Contracts\ADR\Handler`**
- [`Phalcon\Contracts\ADR\Action`](#contractsadraction)
`Phalcon\Contracts\Http\AttributeRequest` · `Phalcon\Http\ResponseInterface`
### Method Summary
### Methods
__invoke()
```php
public function __invoke( AttributeRequest $request ): ResponseInterface;
```
## Contracts\ADR\Middleware
Interface
Wraps the handler chain. Middleware may pass the request through to the next
handler, decorate the response, short-circuit by returning its own response,
or throw to route through the error responder.
- **`Phalcon\Contracts\ADR\Middleware`**
`Phalcon\Contracts\Http\AttributeRequest` · `Phalcon\Http\ResponseInterface`
### Method Summary
### Methods
__invoke()
```php
public function __invoke(
AttributeRequest $request,
Handler $next
): ResponseInterface;
```
## Contracts\ADR\Payload\Payload
Interface
Contract for the immutable payload produced by the domain layer.
- **`Phalcon\Contracts\ADR\Payload\Payload`**
`Throwable`
### Method Summary
Gets the exception thrown in the domain layer, if any.
Gets the arbitrary extra domain information.
Gets the domain input.
Gets the domain messages.
Gets the domain result.
Gets the payload status.
Returns a copy of the payload with the given exception.
Returns a copy of the payload with the given extras.
Returns a copy of the payload with the given input.
Returns a copy of the payload with the given messages.
Returns a copy of the payload with the given result.
Returns a copy of the payload with the given status.
### Methods
getException()
```php
public function getException(): Throwable|null;
```
Gets the exception thrown in the domain layer, if any.
```php
public function getExtras(): mixed;
```
Gets the arbitrary extra domain information.
```php
public function getInput(): mixed;
```
Gets the domain input.
getMessages()
```php
public function getMessages(): mixed;
```
Gets the domain messages.
getResult()
```php
public function getResult(): mixed;
```
Gets the domain result.
getStatus()
```php
public function getStatus(): mixed;
```
Gets the payload status.
withException()
```php
public function withException( Throwable $exception ): Payload;
```
Returns a copy of the payload with the given exception.
```php
public function withExtras( mixed $extras ): Payload;
```
Returns a copy of the payload with the given extras.
```php
public function withInput( mixed $input ): Payload;
```
Returns a copy of the payload with the given input.
withMessages()
```php
public function withMessages( mixed $messages ): Payload;
```
Returns a copy of the payload with the given messages.
withResult()
```php
public function withResult( mixed $result ): Payload;
```
Returns a copy of the payload with the given result.
withStatus()
```php
public function withStatus( mixed $status ): Payload;
```
Returns a copy of the payload with the given status.
## Contracts\ADR\Responder\Formatter\Formatter
Interface
Renders a payload into a string for a given content type.
- **`Phalcon\Contracts\ADR\Responder\Formatter\Formatter`**
`Phalcon\Contracts\ADR\Payload\Payload`
### Method Summary
Whether this formatter can satisfy the given `Accept` header.
The content type this formatter produces.
Renders the payload into a string.
### Methods
```php
public function accepts( string $acceptHeader ): bool;
```
Whether this formatter can satisfy the given `Accept` header.
contentType()
```php
public function contentType(): string;
```
The content type this formatter produces.
```php
public function format( Payload $payload ): string;
```
Renders the payload into a string.
## Contracts\ADR\Responder\Responder
Interface
Turns a payload into an HTTP response. The only layer that speaks HTTP.
- **`Phalcon\Contracts\ADR\Responder\Responder`**
`Phalcon\Contracts\ADR\Payload\Payload` · `Phalcon\Http\RequestInterface` · `Phalcon\Http\ResponseInterface`
### Method Summary
### Methods
__invoke()
```php
public function __invoke(
RequestInterface $request,
ResponseInterface $response,
Payload $payload
): ResponseInterface;
```
## Contracts\ADR\Router\AttributeFilter
Interface
Validates, casts and converts a router match's positional tail segments into
named request attributes, driven by the matched Action's optional static
`params()` declaration.
- **`Phalcon\Contracts\ADR\Router\AttributeFilter`**
`Phalcon\Contracts\ADR\ADRTypes`
### Method Summary
### Methods
filter()
```php
public function filter(
string $actionClass,
array $attributes
): array;
```
## Contracts\ADR\Router\Router
Interface
Maps a request to an Action by convention: the HTTP method and the static
path segments identify the class; trailing segments become positional
request attributes. No route table.
- **`Phalcon\Contracts\ADR\Router\Router`**
`Phalcon\Contracts\ADR\ADRTypes` · `Phalcon\Http\RequestInterface`
### Method Summary
Every Action class this router would try for the given method and path,
The class this convention names for a fully static path, derived without
The HTTP method the given Action class answers, uppercased, or null when
The canonical static path the given Action class answers, or null when
The filesystem root that backs the base namespace. The router uses it to
The single delimiter between words in a path segment. Applied
### Methods
candidatesFor()
```php
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.
classFor()
```php
public function classFor(
string $method,
string $path
): string;
```
The class this convention names for a fully static path, derived without
consulting the filesystem - the exact inverse of pathFor().
For tooling that needs the name before the code exists: generators,
linters, documentation and "no action found; expected X" diagnostics.
Pass the static prefix only; placeholders are the caller's concern.
match()
```php
public function match( RequestInterface $request ): RouterMatch|null;
```
methodFor()
```php
public function methodFor( string $className ): string|null;
```
The HTTP method the given Action class answers, uppercased, or null when
the class is not one this convention would have produced.
The counterpart to pathFor(): same argument, same null semantics, so a
caller that accepts one answer accepts the other. Together they are the
whole inverse of classFor().
pathFor()
```php
public function pathFor( string $className ): string|null;
```
The canonical static path the given Action class answers, or null when
the class is not derivable from the base namespace. Positional
attributes are not part of the canonical path.
setActionDirectory()
```php
public function setActionDirectory( string $actionDirectory ): Router;
```
The filesystem root that backs the base namespace. The router uses it to
decide whether a path segment names a sub-namespace.
setBaseNamespace()
```php
public function setBaseNamespace( string $baseNamespace ): Router;
```
setMiddlewareMap()
```php
public function setMiddlewareMap( array $middlewareMap ): Router;
```
setWordSeparator()
```php
public function setWordSeparator( string $wordSeparator ): Router;
```
The single delimiter between words in a path segment. Applied
symmetrically when deriving a class name from a path and a path from a
class name. Any other character is literal.
## Contracts\ADR\Router\RouterMatch
Interface
The result of matching a request against the router: the Action class, the
extracted route attributes, the route's middleware and its optional name.
- **`Phalcon\Contracts\ADR\Router\RouterMatch`**
`Phalcon\Contracts\ADR\ADRTypes`
### Method Summary
### Methods
getAction()
```php
public function getAction(): string;
```
getAttributes()
```php
public function getAttributes(): array;
```
getMiddleware()
```php
public function getMiddleware(): array;
```
getName()
```php
public function getName(): string|null;
```
## Contracts\Acl\AclTypes
Interface
Central registry of the array shapes used across the Acl namespace.
- **`Phalcon\Contracts\Acl\AclTypes`**
`Phalcon\Acl\ComponentAwareInterface` · `Phalcon\Acl\ComponentInterface` · `Phalcon\Acl\RoleAwareInterface` · `Phalcon\Acl\RoleInterface`
## Contracts\Acl\Adapter\Adapter
Interface
Canonical contract for Phalcon\Acl adapters
- **`Phalcon\Contracts\Acl\Adapter\Adapter`**
- [`Phalcon\Acl\Adapter\AdapterInterface`](/5.20/api/phalcon_acl/#acladapteradapterinterface)
`Phalcon\Acl\ComponentInterface` · `Phalcon\Acl\RoleInterface` · `Phalcon\Contracts\Acl\AclTypes`
### Method Summary
Adds a component to the ACL list
Adds access to components
Do a role inherit from another existing role
Adds a role to the ACL list. Second parameter lets to inherit access data
Allow access to a role on a component
Deny access to a role on a component
Removes access from a component
Returns the access which the list is checking if some role can access it
Returns the component which the list is checking if some role can access
Returns the role which the list is checking if it's allowed to certain
Return an array with every component registered in the list
Returns the default ACL access level
Returns the inherited roles for a passed role name. If no role name
Returns the default ACL access level for no arguments provided in
Return an array with every role registered in the list
Check whether a role is allowed to access an action from a component
Check whether component exist in the components list
Check whether role exist in the roles list
Sets the default access level (Phalcon\Acl\Enum::ALLOW or Phalcon\Acl\Enum::DENY)
Sets the default access level (Phalcon\Acl\Enum::ALLOW or Phalcon\Acl\Enum::DENY)
### Methods
addComponent()
```php
public function addComponent(
mixed $componentValue,
mixed $accessList
): bool;
```
Adds a component to the ACL list
Access names can be a particular action, by example
search, update, delete, etc. or a list of them
addComponentAccess()
```php
public function addComponentAccess(
string $componentName,
mixed $accessList
): bool;
```
Adds access to components
addInherit()
```php
public function addInherit(
string $roleName,
mixed $roleToInherits
): bool;
```
Do a role inherit from another existing role
addRole()
```php
public function addRole(
mixed $role,
mixed $accessInherits = null
): bool;
```
Adds a role to the ACL list. Second parameter lets to inherit access data
from other existing role
allow()
```php
public function allow(
string $roleName,
string $componentName,
mixed $access,
mixed $func = null
): void;
```
Allow access to a role on a component
deny()
```php
public function deny(
string $roleName,
string $componentName,
mixed $access,
mixed $func = null
): void;
```
Deny access to a role on a component
dropComponentAccess()
```php
public function dropComponentAccess(
string $componentName,
mixed $accessList
): void;
```
Removes access from a component
getActiveAccess()
```php
public function getActiveAccess(): null|string;
```
Returns the access which the list is checking if some role can access it
getActiveComponent()
```php
public function getActiveComponent(): null|string;
```
Returns the component which the list is checking if some role can access
it
getActiveRole()
```php
public function getActiveRole(): null|string;
```
Returns the role which the list is checking if it's allowed to certain
component/access
getComponents()
```php
public function getComponents(): ComponentInterface[];
```
Return an array with every component registered in the list
getDefaultAction()
```php
public function getDefaultAction(): int;
```
Returns the default ACL access level
getInheritedRoles()
```php
public function getInheritedRoles( string $roleName = "" ): array;
```
Returns the inherited roles for a passed role name. If no role name
has been specified it will return the whole array. If the role has not
been found it returns an empty array
getNoArgumentsDefaultAction()
```php
public function getNoArgumentsDefaultAction(): int;
```
Returns the default ACL access level for no arguments provided in
isAllowed action if there exists func for accessKey
getRoles()
```php
public function getRoles(): RoleInterface[];
```
Return an array with every role registered in the list
isAllowed()
```php
public function isAllowed(
mixed $roleName,
mixed $componentName,
string $access,
array|null $parameters = null
): bool;
```
Check whether a role is allowed to access an action from a component
isComponent()
```php
public function isComponent( string $componentName ): bool;
```
Check whether component exist in the components list
isRole()
```php
public function isRole( string $roleName ): bool;
```
Check whether role exist in the roles list
setDefaultAction()
```php
public function setDefaultAction( int $defaultAccess ): void;
```
Sets the default access level (Phalcon\Acl\Enum::ALLOW or Phalcon\Acl\Enum::DENY)
setNoArgumentsDefaultAction()
```php
public function setNoArgumentsDefaultAction( int $defaultAccess ): void;
```
Sets the default access level (Phalcon\Acl\Enum::ALLOW or Phalcon\Acl\Enum::DENY)
for no arguments provided in isAllowed action if there exists func for
accessKey
## Contracts\Acl\Adapter\Persistable
Interface
Contract for ACL adapters that persist their policy to a backing store as a
whole-policy snapshot (coarse granularity).
NOTE: callable (closure) rules registered via allow()/deny() are NOT
persisted - closures are not serializable. Re-register them in code after
load(). The static rule set and role inheritance are persisted in full.
- **`Phalcon\Contracts\Acl\Adapter\Persistable`**
### Method Summary
Loads the policy snapshot from the backing store, replacing current
Persists the current policy snapshot to the backing store.
### Methods
load()
```php
public function load(): bool;
```
Loads the policy snapshot from the backing store, replacing current
in-memory state. Returns false if no snapshot was found.
save()
```php
public function save(): bool;
```
Persists the current policy snapshot to the backing store.
## Contracts\Acl\Component
Interface
Canonical contract for an ACL component entity.
- **`Phalcon\Contracts\Acl\Component`**
- [`Phalcon\Acl\ComponentInterface`](/5.20/api/phalcon_acl/#aclcomponentinterface)
### Method Summary
Magic method __toString
Returns component description
Returns the component name
### Methods
__toString()
```php
public function __toString(): string;
```
Magic method __toString
getDescription()
```php
public function getDescription(): string|null;
```
Returns component description
getName()
```php
public function getName(): string;
```
Returns the component name
## Contracts\Acl\ComponentAware
Interface
Canonical contract for ACL component-aware objects.
- **`Phalcon\Contracts\Acl\ComponentAware`**
- [`Phalcon\Acl\ComponentAwareInterface`](/5.20/api/phalcon_acl/#aclcomponentawareinterface)
### Method Summary
Returns component name
### Methods
getComponentName()
```php
public function getComponentName(): string;
```
Returns component name
## Contracts\Acl\Role
Interface
Canonical contract for an ACL role entity.
- **`Phalcon\Contracts\Acl\Role`**
- [`Phalcon\Acl\RoleInterface`](/5.20/api/phalcon_acl/#aclroleinterface)
### Method Summary
Magic method __toString
Returns role description
Returns the role name
### Methods
__toString()
```php
public function __toString(): string;
```
Magic method __toString
getDescription()
```php
public function getDescription(): string|null;
```
Returns role description
getName()
```php
public function getName(): string;
```
Returns the role name
## Contracts\Acl\RoleAware
Interface
Canonical contract for ACL role-aware objects.
- **`Phalcon\Contracts\Acl\RoleAware`**
- [`Phalcon\Acl\RoleAwareInterface`](/5.20/api/phalcon_acl/#aclroleawareinterface)
### Method Summary
Returns role name
### Methods
getRoleName()
```php
public function getRoleName(): string;
```
Returns role name
## Contracts\Application\ApplicationTypes
Interface
Central registry of the array shapes used across the Application namespace.
- **`Phalcon\Contracts\Application\ApplicationTypes`**
`Closure`
## Contracts\Assets\Asset
Interface
Canonical contract for Phalcon\Assets\Asset.
Covers collection membership: an asset's key, type, HTML attributes, and
filter flag. The file-output pipeline (Phalcon\Assets\Manager::output())
requires the concrete Phalcon\Assets\Asset class.
- **`Phalcon\Contracts\Assets\Asset`**
- [`Phalcon\Assets\AssetInterface`](/5.20/api/phalcon_assets/#assetsassetinterface)
### Method Summary
Gets the asset's key.
Gets extra HTML attributes.
Gets if the asset must be filtered or not.
Gets the asset's type.
Sets extra HTML attributes.
Sets if the asset must be filtered or not.
Sets the asset's type.
### Methods
getAssetKey()
```php
public function getAssetKey(): string;
```
Gets the asset's key.
getAttributes()
```php
public function getAttributes(): array|null;
```
Gets extra HTML attributes.
getFilter()
```php
public function getFilter(): bool;
```
Gets if the asset must be filtered or not.
getType()
```php
public function getType(): string;
```
Gets the asset's type.
setAttributes()
```php
public function setAttributes( array $attributes ): Asset;
```
Sets extra HTML attributes.
setFilter()
```php
public function setFilter( bool $filter ): Asset;
```
Sets if the asset must be filtered or not.
setType()
```php
public function setType( string $type ): Asset;
```
Sets the asset's type.
## Contracts\Assets\AssetsTypes
Interface
Central registry of the array shapes used across the Assets namespace.
- **`Phalcon\Contracts\Assets\AssetsTypes`**
`Phalcon\Assets\AssetInterface` · `Phalcon\Assets\Collection` · `Phalcon\Assets\FilterInterface` · `Phalcon\Assets\Manager`
## Contracts\Assets\Filter
Interface
Canonical contract for Phalcon\Assets filters (Cssmin, Jsmin, None, and
custom user filters).
- **`Phalcon\Contracts\Assets\Filter`**
- [`Phalcon\Assets\FilterInterface`](/5.20/api/phalcon_assets/#assetsfilterinterface)
### Method Summary
Filters the content returning a string with the filtered content
### Methods
filter()
```php
public function filter( string $content ): string;
```
Filters the content returning a string with the filtered content
## Contracts\Auth\Access\Access
Interface
Access gates are Specifications: policies that decide whether the current
identity may run the given action. The enforcement point passes the
identity (the guard) and the request context on every call; gates hold no
reference to the auth manager.
- **`Phalcon\Contracts\Auth\Access\Access`**
`Phalcon\Contracts\Auth\Guard\Guard`
### Method Summary
Whether the identity behind the guard may run the action.
Exempts the listed action names from the gate; every other action is
Restricts the gate to the listed action names.
### Methods
getExceptActions()
```php
public function getExceptActions(): array;
```
getOnlyActions()
```php
public function getOnlyActions(): array;
```
isAllowed()
```php
public function isAllowed(
Guard $guard,
string $actionName,
array $context = []
): bool;
```
Whether the identity behind the guard may run the action.
redirectTo()
```php
public function redirectTo(): array|null;
```
setExceptActions()
```php
public function setExceptActions( array $exceptActions = [] ): void;
```
Exempts the listed action names from the gate; every other action is
checked. See setOnlyActions() for the gate-family divergence note.
setOnlyActions()
```php
public function setOnlyActions( array $onlyActions = [] ): void;
```
Restricts the gate to the listed action names.
Authoritative semantics: the gate applies only to the listed actions; an
action that is not listed passes without a check (and except() is the
inverse - the gate applies to every action except those listed).
NOTE: the implementations currently diverge. The Acl gate follows the
authoritative semantics above, while the binary gates (Auth, Guest)
treat `only` as a whitelist - an unlisted action is denied even when the
base condition holds. The two gate families will be aligned in the next
major version; until then, choose the gate family deliberately, because
for an unlisted action they return opposite answers to the same call.
## Contracts\Auth\Adapter\Adapter
Interface
Authentication adapter contract.
Adapters look users up by credentials or by identifier and verify the
password against the stored hash. The credential payload is intentionally
unsealed: any user-row field may be used as the lookup key, plus an
optional `password` entry that is ignored during the row match and
consumed only by validateCredentials().
- **`Phalcon\Contracts\Auth\Adapter\Adapter`**
- [`Phalcon\Contracts\Auth\Adapter\RememberAdapter`](#contractsauthadapterrememberadapter)
`Phalcon\Contracts\Auth\AuthUser` · `Phalcon\Contracts\Encryption\Security\Security`
### Method Summary
Build an adapter from a flat options map. Used by ManagerFactory to
Find a user matching the given credentials (e.g. ['email' => 'a@b']).
Find a user by their unique identifier.
Validate the provided credentials against the given user.
### Methods
fromOptions()
```php
public static function fromOptions(
Security $hasher,
array $options
): static;
```
Build an adapter from a flat options map. Used by ManagerFactory to
wire adapters from the application config; each implementation is
free to interpret the option keys it cares about.
retrieveByCredentials()
```php
public function retrieveByCredentials( array $credentials ): AuthUser|null;
```
Find a user matching the given credentials (e.g. ['email' => 'a@b']).
The 'password' key, if present, is ignored during the lookup.
Returns null if no user matches.
retrieveById()
```php
public function retrieveById( mixed $id ): AuthUser|null;
```
Find a user by their unique identifier.
validateCredentials()
```php
public function validateCredentials(
AuthUser $user,
array $credentials
): bool;
```
Validate the provided credentials against the given user.
Implementations typically verify the password hash held under the
'password' key.
## Contracts\Auth\Adapter\AdapterConfig
Interface
Authentication adapter configuration contract.
Per-adapter config shape is intentionally adapter-specific (e.g. Stream
exposes getFile(), Memory exposes getUsers()); the only field shared across
all adapters is the optional model class used during user hydration.
- **`Phalcon\Contracts\Auth\Adapter\AdapterConfig`**
### Method Summary
Returns the user-model class name to hydrate, if configured.
### Methods
getModel()
```php
public function getModel(): string|null;
```
Returns the user-model class name to hydrate, if configured.
## Contracts\Auth\Adapter\RememberAdapter
Interface
Capability extension implemented by adapters that support remember-me.
- [`Phalcon\Contracts\Auth\Adapter\Adapter`](#contractsauthadapteradapter)
- **`Phalcon\Contracts\Auth\Adapter\RememberAdapter`**
`Phalcon\Contracts\Auth\AuthUser` · `Phalcon\Contracts\Auth\RememberToken`
### Method Summary
Create and persist a new remember token for the user.
Retrieve a user by the remember-me cookie payload.
### Methods
createRememberToken()
```php
public function createRememberToken( AuthUser $user ): RememberToken;
```
Create and persist a new remember token for the user.
retrieveByToken()
```php
public function retrieveByToken(
mixed $id,
string $token,
string|null $userAgent = null
): AuthUser|null;
```
Retrieve a user by the remember-me cookie payload.
## Contracts\Auth\AuthRemember
Interface
Implemented by authenticatable models that support remember-me tokens.
This is intentionally separate from AuthUser so that adapters which do
not support remember-me are not forced to implement it.
- **`Phalcon\Contracts\Auth\AuthRemember`**
### Method Summary
Persists a new remember token for the user.
Returns the remember token entry matching the given token value,
### Methods
createRememberToken()
```php
public function createRememberToken(
string $token,
string|null $userAgent = null
): RememberToken;
```
Persists a new remember token for the user.
getRememberToken()
```php
public function getRememberToken( string $token ): RememberToken|null;
```
Returns the remember token entry matching the given token value,
or null if not found.
## Contracts\Auth\AuthUser
Interface
Implemented by user models that can be authenticated.
- **`Phalcon\Contracts\Auth\AuthUser`**
### Method Summary
Returns the unique identifier for the authenticatable user
Returns the hashed password for the authenticatable user.
### Methods
getAuthIdentifier()
```php
public function getAuthIdentifier(): int|string;
```
Returns the unique identifier for the authenticatable user
(e.g. the primary key). Implementations MUST return a non-null
scalar; if a record cannot produce one, the implementation should
fail at construction time rather than returning null.
getAuthPassword()
```php
public function getAuthPassword(): string;
```
Returns the hashed password for the authenticatable user.
## Contracts\Auth\Guard\BasicAuth
Interface
- **`Phalcon\Contracts\Auth\Guard\BasicAuth`**
`Phalcon\Contracts\Auth\AuthUser`
### Method Summary
Authenticate against HTTP Basic credentials. Returns true on success.
Like basic() but does not persist; returns the resolved user on success
### Methods
basic()
```php
public function basic(
string $field = "email",
array $extraConditions = []
): bool;
```
Authenticate against HTTP Basic credentials. Returns true on success.
onceBasic()
```php
public function onceBasic(
string $field = "email",
array $extraConditions = []
): false|AuthUser;
```
Like basic() but does not persist; returns the resolved user on success
or false on failure.
## Contracts\Auth\Guard\Guard
Interface
- **`Phalcon\Contracts\Auth\Guard\Guard`**
`Phalcon\Contracts\Auth\Adapter\Adapter` · `Phalcon\Contracts\Auth\AuthUser` · `Phalcon\Contracts\Container\Service\Collection` · `Phalcon\Di\DiInterface`
### Method Summary
Whether the current request is authenticated.
Build a guard from an adapter, the application container, and a flat
Returns the last user the guard tried to authenticate during this
Whether the current request is unauthenticated.
Whether the guard currently holds a resolved user.
Returns the authenticated user's identifier, or null when no
Sets the current user explicitly. Returns $this for fluent chaining.
Returns the resolved user for the current request, or null.
Validates the given credentials without logging in.
### Methods
check()
```php
public function check(): bool;
```
Whether the current request is authenticated.
fromOptions()
```php
public static function fromOptions(
Adapter $adapter,
mixed $container,
array $options
): static;
```
Build a guard from an adapter, the application container, and a flat
options map. Used by ManagerFactory to wire guards from the
application config; each implementation resolves the framework
services it needs from the container.
The container is Container-first: pass a Phalcon\Container\Container.
The legacy Phalcon\Di\Di is also supported with provisions - its
service definitions must be pre-registered (no autowiring).
getLastUserAttempted()
```php
public function getLastUserAttempted(): AuthUser|null;
```
Returns the last user the guard tried to authenticate during this
request, regardless of success.
guest()
```php
public function guest(): bool;
```
Whether the current request is unauthenticated.
hasUser()
```php
public function hasUser(): bool;
```
Whether the guard currently holds a resolved user.
id()
```php
public function id(): int|string|null;
```
Returns the authenticated user's identifier, or null when no
authenticated user is present.
setUser()
```php
public function setUser( AuthUser $user ): static;
```
Sets the current user explicitly. Returns $this for fluent chaining.
user()
```php
public function user(): AuthUser|null;
```
Returns the resolved user for the current request, or null.
validate()
```php
public function validate( array $credentials = [] ): bool;
```
Validates the given credentials without logging in.
## Contracts\Auth\Guard\GuardConfig
Interface
Authentication guard configuration contract.
Per-guard config shape is intentionally guard-specific (e.g. Token exposes
getInputKey()/getStorageKey(); Session has no required config today).
The contract carries no methods of its own - it only marks the type so
AbstractGuard can accept any guard config uniformly.
- **`Phalcon\Contracts\Auth\Guard\GuardConfig`**
## Contracts\Auth\Guard\GuardStateful
Interface
Implemented by guards backed by persistent state (sessions/cookies).
- **`Phalcon\Contracts\Auth\Guard\GuardStateful`**
`Phalcon\Contracts\Auth\Adapter\Adapter` · `Phalcon\Contracts\Auth\AuthUser`
### Method Summary
Attempts to authenticate the user with the given credentials and, on
Logs in the user identified by $id. Returns the resolved user on
### Methods
attempt()
```php
public function attempt(
array $credentials = [],
bool $remember = false
): bool;
```
Attempts to authenticate the user with the given credentials and, on
success, persists the resulting state on the guard.
login()
```php
public function login(
AuthUser $user,
bool $remember = false
): void;
```
loginById()
```php
public function loginById(
mixed $id,
bool $remember = false
): AuthUser|false;
```
Logs in the user identified by $id. Returns the resolved user on
success or false when no user matches the id.
logout()
```php
public function logout(): void;
```
viaRemember()
```php
public function viaRemember(): bool;
```
## Contracts\Auth\Manager
Interface
- **`Phalcon\Contracts\Auth\Manager`**
`Phalcon\Auth\Exception` · `Phalcon\Contracts\Auth\Access\Access` · `Phalcon\Contracts\Auth\Adapter\Adapter` · `Phalcon\Contracts\Auth\Guard\Guard`
### Method Summary
Activates the named access gate for the current request and returns the
Whether the default guard reports the current request as authenticated.
Restricts the active access gate to skip the listed action names.
Returns the active access gate, or null when none has been activated -
Returns the named guard, or the default guard when $name is null.
Returns the authenticated user's identifier from the default guard,
Logs the current user out via the default guard.
Restricts the active access gate to apply only to the listed action names.
Returns the resolved user from the default guard, or null.
Validates the given credentials against the default guard without
### Methods
access()
```php
public function access( string $accessName ): self;
```
Activates the named access gate for the current request and returns the
manager for fluent only()/except() configuration.
Enforcement is opt-in and fail-open: when no access has been activated
(getAccess() returns null) every dispatch is allowed. An activated gate
stays active for subsequent dispatches in the same request (forwards,
nested handlers) until it is replaced. Under classic FPM this is scoped
to a single request; long-running runtimes must reset it per request.
addAccessList()
```php
public function addAccessList( array $accessList ): self;
```
addGuard()
```php
public function addGuard(
string $nameGuard,
Guard $guard,
bool $isDefault = false
): self;
```
attempt()
```php
public function attempt(
array $credentials = [],
bool $remember = false
): bool;
```
check()
```php
public function check(): bool;
```
Whether the default guard reports the current request as authenticated.
except()
```php
public function except( string $actions ): self;
```
Restricts the active access gate to skip the listed action names.
getAccess()
```php
public function getAccess(): Access|null;
```
Returns the active access gate, or null when none has been activated -
in which case listener enforcement is a no-op (see access()).
getAccessList()
```php
public function getAccessList(): array;
```
getDefaultGuard()
```php
public function getDefaultGuard(): Guard|null;
```
getGuards()
```php
public function getGuards(): array;
```
guard()
```php
public function guard( string|null $name = null ): Guard;
```
Returns the named guard, or the default guard when $name is null.
id()
```php
public function id(): int|string|null;
```
Returns the authenticated user's identifier from the default guard,
or null when no authenticated user is present.
logout()
```php
public function logout(): void;
```
Logs the current user out via the default guard.
only()
```php
public function only( string $actions ): self;
```
Restricts the active access gate to apply only to the listed action names.
setAccess()
```php
public function setAccess( Access $access ): self;
```
setDefaultGuard()
```php
public function setDefaultGuard( Guard $guard ): self;
```
user()
```php
public function user(): AuthUser|null;
```
Returns the resolved user from the default guard, or null.
validate()
```php
public function validate( array $credentials = [] ): bool;
```
Validates the given credentials against the default guard without
logging in.
## Contracts\Auth\RememberToken
Interface
A persisted remember-me token row.
- **`Phalcon\Contracts\Auth\RememberToken`**
### Method Summary
Deletes the token from storage.
Returns the token value stored for this remember entry.
Returns the user agent associated with this token, if any.
### Methods
delete()
```php
public function delete(): bool;
```
Deletes the token from storage.
getToken()
```php
public function getToken(): string;
```
Returns the token value stored for this remember entry.
getUserAgent()
```php
public function getUserAgent(): string|null;
```
Returns the user agent associated with this token, if any.
## Contracts\Autoload\AutoloadTypes
Interface
Central registry of the array shapes used across the Autoload namespace.
- **`Phalcon\Contracts\Autoload\AutoloadTypes`**
## Contracts\Cache\Cache
Interface
Canonical contract for Phalcon\Cache\Cache.
- **`Phalcon\Contracts\Cache\Cache`**
- [`Phalcon\Cache\CacheInterface`](/5.20/api/phalcon_cache/#cachecacheinterface)
`DateInterval` · `Phalcon\Cache\Exception\InvalidArgumentException`
### Method Summary
Wipes clean the entire cache's keys.
Delete an item from the cache by its unique key.
Deletes multiple cache items in a single operation.
Fetches a value from the cache.
Obtains multiple cache items by their unique keys.
Determines whether an item is present in the cache.
Persists data in the cache, uniquely referenced by a key with an optional
Persists a set of key => value pairs in the cache, with an optional TTL.
### Methods
clear()
```php
public function clear(): bool;
```
Wipes clean the entire cache's keys.
delete()
```php
public function delete( string $key ): bool;
```
Delete an item from the cache by its unique key.
deleteMultiple()
```php
public function deleteMultiple( mixed $keys ): bool;
```
Deletes multiple cache items in a single operation.
get()
```php
public function get(
string $key,
mixed $defaultValue = null
);
```
Fetches a value from the cache.
getMultiple()
```php
public function getMultiple(
mixed $keys,
mixed $defaultValue = null
);
```
Obtains multiple cache items by their unique keys.
has()
```php
public function has( string $key ): bool;
```
Determines whether an item is present in the cache.
set()
```php
public function set(
string $key,
mixed $value,
mixed $ttl = null
): bool;
```
Persists data in the cache, uniquely referenced by a key with an optional
expiration TTL time.
setMultiple()
```php
public function setMultiple(
mixed $values,
mixed $ttl = null
): bool;
```
Persists a set of key => value pairs in the cache, with an optional TTL.
## Contracts\Cli\CliTypes
Interface
Central registry of the array shapes used across the Cli namespace.
- **`Phalcon\Contracts\Cli\CliTypes`**
`Phalcon\Cli\Router\Route`
## Contracts\Cli\Dispatcher
Interface
Canonical contract for Phalcon\Cli\Dispatcher.
- [`Phalcon\Contracts\Dispatcher\Dispatcher`](#contractsdispatcherdispatcher)
- **`Phalcon\Contracts\Cli\Dispatcher`**
- [`Phalcon\Cli\DispatcherInterface`](/5.20/api/phalcon_cli/#clidispatcherinterface)
`Phalcon\Cli\TaskInterface` · `Phalcon\Contracts\Dispatcher\Dispatcher`
### Method Summary
Returns the active task in the dispatcher
Returns the latest dispatched controller
Get dispatched options
Gets last dispatched task name
Gets default task suffix
Sets the default task name
Set the options to be dispatched
Sets the task name to be dispatched
Sets the default task suffix
### Methods
getActiveTask()
```php
public function getActiveTask(): TaskInterface;
```
Returns the active task in the dispatcher
getLastTask()
```php
public function getLastTask(): TaskInterface;
```
Returns the latest dispatched controller
getOptions()
```php
public function getOptions(): array;
```
Get dispatched options
getTaskName()
```php
public function getTaskName(): string;
```
Gets last dispatched task name
getTaskSuffix()
```php
public function getTaskSuffix(): string;
```
Gets default task suffix
setDefaultTask()
```php
public function setDefaultTask( string $taskName ): void;
```
Sets the default task name
setOptions()
```php
public function setOptions( array $options ): void;
```
Set the options to be dispatched
setTaskName()
```php
public function setTaskName( string $taskName ): void;
```
Sets the task name to be dispatched
setTaskSuffix()
```php
public function setTaskSuffix( string $taskSuffix ): void;
```
Sets the default task suffix
## Contracts\Config\ConfigTypes
Interface
Central registry of the array shapes used across the Config namespace.
- **`Phalcon\Contracts\Config\ConfigTypes`**
`Phalcon\Config\ConfigInterface`
## Contracts\Container\ContainerTypes
Interface
Central registry of the array shapes used across the Container namespace.
- **`Phalcon\Contracts\Container\ContainerTypes`**
`Phalcon\Container\Definition\Processor\Processor` · `Phalcon\Container\Definition\ServiceDefinition` · `Phalcon\Contracts\Container\Service\Provider` · `ReflectionParameter`
## Contracts\Container\Ioc\IocContainer
Interface
[_IocContainer_][] affords obtaining services by name.
- Notes:
- **This interface does not afford service management.** The container
will need to obtain services somehow, e.g. from a [Service-Interop][]
implementation.
- **`Phalcon\Contracts\Container\Ioc\IocContainer`**
- [`Phalcon\Contracts\Container\Service\Collection`](#contractscontainerservicecollection)
### Method Summary
Returns an instance of the `$serviceName`.
Is the container able to return an instance of the `$serviceName`?
### Methods
getService()
```php
public function getService( string $serviceName ): object;
```
Returns an instance of the `$serviceName`.
- Directives:
- Implementations MUST throw [_IocThrowable_][] if the container
cannot return an instance of the `$serviceName`.
- Notes:
- **The logic for this method is expressly unspecified.** Retrieval
may be accomplished via a service management subsystem, or by some
other means.
- **The returned instance may be new or shared.** The retrieval
logic defines the service lifetime, not the container (per se) and
not the caller requesting the service.
hasService()
```php
public function hasService( string $serviceName ): bool;
```
Is the container able to return an instance of the `$serviceName`?
- Notes:
- **The logic for this method is expressly unspecified.** The ability
check may be accomplished by querying a service management subsystem,
or by some other means.
## Contracts\Container\Ioc\IocContainerFactory
Interface
[_IocContainerFactory_][] affords obtaining a new instance of
[_IocContainer_][].
- **`Phalcon\Contracts\Container\Ioc\IocContainerFactory`**
### Method Summary
Returns a new instance of [_IocContainer_][].
### Methods
newContainer()
```php
public function newContainer(): IocContainer;
```
Returns a new instance of [_IocContainer_][].
- Notes:
- **Container instantiation logic is not specified.** Implementations
might use providers, configuration files, attribute or annotation
collection, or some other means to create and populate a container.
Implementations might also choose to return a compiled or otherwise
reconstituted container.
## Contracts\Container\Ioc\IocThrowable
Interface
[_IocThrowable_][] extends [_Throwable_][] to mark an [_Exception_][] as
IOC-related.
It adds no class members.
- `\Throwable`
- **`Phalcon\Contracts\Container\Ioc\IocThrowable`**
- [`Phalcon\Container\Exceptions\ContainerThrowable`](/5.20/api/phalcon_container/#containerexceptionscontainerthrowable)
`Throwable`
## Contracts\Container\Ioc\IocTypeAliases
Interface
- **`Phalcon\Contracts\Container\Ioc\IocTypeAliases`**
## Contracts\Container\Resolver\ReflectionMethodResolver
Interface
- **`Phalcon\Contracts\Container\Resolver\ReflectionMethodResolver`**
`Phalcon\Contracts\Container\Ioc\IocContainer` · `ReflectionMethod`
### Method Summary
### Methods
resolveMethod()
```php
public function resolveMethod(
IocContainer $ioc,
ReflectionMethod $method,
object $instance
): void;
```
## Contracts\Container\Resolver\ReflectionParameterResolver
Interface
- **`Phalcon\Contracts\Container\Resolver\ReflectionParameterResolver`**
- [`Phalcon\Contracts\Container\Resolver\ResolverService`](#contractscontainerresolverresolverservice)
`Phalcon\Contracts\Container\Ioc\IocContainer` · `ReflectionParameter`
### Method Summary
### Methods
resolveParameter()
```php
public function resolveParameter(
IocContainer $ioc,
ReflectionParameter $parameter
): mixed;
```
## Contracts\Container\Resolver\Resolvable
Interface
- **`Phalcon\Contracts\Container\Resolver\Resolvable`**
`Phalcon\Contracts\Container\Ioc\IocContainer`
### Method Summary
### Methods
resolve()
```php
public function resolve( IocContainer $ioc ): mixed;
```
## Contracts\Container\Resolver\ResolverService
Interface
- [`Phalcon\Contracts\Container\Resolver\ReflectionParameterResolver`](#contractscontainerresolverreflectionparameterresolver)
- **`Phalcon\Contracts\Container\Resolver\ResolverService`**
`Phalcon\Contracts\Container\ContainerTypes` · `Phalcon\Contracts\Container\Ioc\IocContainer` · `ReflectionMethod` · `ReflectionParameter` · `ReflectionType`
### Method Summary
### Methods
isResolvableClass()
```php
public function isResolvableClass( string $className ): bool;
```
resolveCall()
```php
public function resolveCall(
IocContainer $ioc,
callable $callableObject,
array $arguments
): mixed;
```
resolveClass()
```php
public function resolveClass(
IocContainer $ioc,
string $className,
array $arguments
): object;
```
resolveMethod()
```php
public function resolveMethod(
IocContainer $ioc,
ReflectionMethod $method,
object $instance
): void;
```
resolveParameters()
```php
public function resolveParameters(
IocContainer $ioc,
array $parameters,
array $arguments
): array;
```
resolveType()
```php
public function resolveType(
IocContainer $ioc,
ReflectionType $type
): mixed;
```
## Contracts\Container\Resolver\ResolverThrowable
Interface
- `\Throwable`
- **`Phalcon\Contracts\Container\Resolver\ResolverThrowable`**
`Throwable`
## Contracts\Container\Service\Collection
Interface
- [`Phalcon\Contracts\Container\Ioc\IocContainer`](#contractscontaineriocioccontainer)
- **`Phalcon\Contracts\Container\Service\Collection`**
`Closure` · `Phalcon\Container\Definition\ServiceDefinition` · `Phalcon\Container\Resolver\Resolver` · `Phalcon\Contracts\Container\ContainerTypes` · `Phalcon\Contracts\Container\Ioc\IocContainer`
### Method Summary
### Methods
bind()
```php
public function bind(
string $interfaceName,
string $concrete
): ServiceDefinition;
```
callableGet()
```php
public function callableGet( string $name ): Closure;
```
callableNew()
```php
public function callableNew( string $name ): Closure;
```
extend()
```php
public function extend(
string $name,
callable $callableObject
): void;
```
get()
```php
public function get( string $name ): mixed;
```
getAlias()
```php
public function getAlias( string $name ): string;
```
getByTag()
```php
public function getByTag( string $tag ): array;
```
getDefinition()
```php
public function getDefinition( string $name ): ServiceDefinition;
```
getInstance()
```php
public function getInstance( string $name ): object;
```
getParameter()
```php
public function getParameter( string $name ): mixed;
```
getResolver()
```php
public function getResolver(): Resolver;
```
has()
```php
public function has( string $name ): bool;
```
hasAlias()
```php
public function hasAlias( string $name ): bool;
```
hasDefinition()
```php
public function hasDefinition( string $name ): bool;
```
hasInstance()
```php
public function hasInstance( string $name ): bool;
```
hasParameter()
```php
public function hasParameter( string $name ): bool;
```
isAutowireEnabled()
```php
public function isAutowireEnabled(): bool;
```
new()
```php
public function new( string $name ): mixed;
```
newDefinition()
```php
public function newDefinition( string $name ): ServiceDefinition;
```
set()
```php
public function set(
string $name,
mixed $definition
): ServiceDefinition;
```
setAlias()
```php
public function setAlias(
string $name,
string $alias
): static;
```
setAutowire()
```php
public function setAutowire( bool $enabled ): static;
```
setDefinition()
```php
public function setDefinition(
string $name,
ServiceDefinition $definition
): static;
```
setInstance()
```php
public function setInstance(
string $name,
object $instance,
string $lifetime
): static;
```
setParameter()
```php
public function setParameter(
string $name,
mixed $value
): static;
```
unsetAlias()
```php
public function unsetAlias( string $name ): void;
```
unsetDefinition()
```php
public function unsetDefinition( string $name ): void;
```
unsetInstance()
```php
public function unsetInstance( string $name ): void;
```
unsetInstances()
```php
public function unsetInstances( string $lifetime ): void;
```
unsetParameter()
```php
public function unsetParameter( string $name ): void;
```
## Contracts\Container\Service\Definition
Interface
- **`Phalcon\Contracts\Container\Service\Definition`**
`Phalcon\Contracts\Container\ContainerTypes` · `Phalcon\Contracts\Container\Ioc\IocContainer`
### Method Summary
### Methods
addExtender()
```php
public function addExtender( callable $extender ): static;
```
buildService()
```php
public function buildService( IocContainer $ioc ): object;
```
getClass()
```php
public function getClass(): string;
```
getExtenders()
```php
public function getExtenders(): array;
```
getFactory()
```php
public function getFactory(): callable;
```
getLifetime()
```php
public function getLifetime(): string;
```
getServiceName()
```php
public function getServiceName(): string;
```
hasClass()
```php
public function hasClass(): bool;
```
hasExtenders()
```php
public function hasExtenders(): bool;
```
hasFactory()
```php
public function hasFactory(): bool;
```
setClass()
```php
public function setClass( string $className ): static;
```
setExtenders()
```php
public function setExtenders( array $extenders ): static;
```
setFactory()
```php
public function setFactory( callable $factory ): static;
```
setLifetime()
```php
public function setLifetime( string $lifetime ): static;
```
unsetClass()
```php
public function unsetClass(): static;
```
unsetExtenders()
```php
public function unsetExtenders(): static;
```
unsetFactory()
```php
public function unsetFactory(): static;
```
## Contracts\Container\Service\Enumerable
Interface
- **`Phalcon\Contracts\Container\Service\Enumerable`**
`Phalcon\Contracts\Container\ContainerTypes`
### Method Summary
Returns the names of every registered service definition. Names that
### Methods
getServiceNames()
```php
public function getServiceNames(): array;
```
Returns the names of every registered service definition. Names that
only exist as an alias, a pre-set instance or a parameter are not
included.
## Contracts\Container\Service\Provider
Interface
- **`Phalcon\Contracts\Container\Service\Provider`**
### Method Summary
### Methods
provide()
```php
public function provide( Collection $services ): void;
```
## Contracts\Container\Service\Throwable
Interface
- `\Throwable`
- **`Phalcon\Contracts\Container\Service\Throwable`**
`Throwable`
## Contracts\Db\Adapter\Adapter
Interface
Canonical contract for Phalcon\Db adapters.
@todo v7 - these will become required interface members. They are
omitted from the v5 line to avoid breaking third-party
implementors:
- addCheck() : bool
- createMaterializedView() : bool
- dropCheck() : bool
- dropMaterializedView() : bool
- onConflictUpdate() : string
- refreshMaterializedView() : bool
- returning() : string
- **`Phalcon\Contracts\Db\Adapter\Adapter`**
- [`Phalcon\Db\Adapter\AdapterInterface`](/5.20/api/phalcon_db/#dbadapteradapterinterface)
`Phalcon\Db\ColumnInterface` · `Phalcon\Db\DialectInterface` · `Phalcon\Db\IndexInterface` · `Phalcon\Db\RawValue` · `Phalcon\Db\ReferenceInterface` · `Phalcon\Db\ResultInterface`
### Method Summary
Adds a column to a table
Adds a foreign key to a table
Adds an index to a table
Adds a primary key to a table
Returns the number of affected rows by the last INSERT/UPDATE/DELETE
Starts a transaction in the connection
Closes active connection returning success. Phalcon automatically closes
Commits the active transaction in the connection
This method is automatically called in \Phalcon\Db\Adapter\Pdo
Creates a new savepoint
Creates a table
Creates a view
Deletes data from a table using custom RDBMS SQL syntax
Returns an array of Phalcon\Db\Column objects describing a table
Lists table indexes
Lists table references
Drops a column from a table
Drops a foreign key from a table
Drop an index from a table
Drops primary key from a table
Drops a table from a schema/database
Drops a view
Escapes a column/table/schema name
Escapes a value to avoid SQL injections
Sends SQL statements to the database server returning the success state.
Dumps the complete result of a query into an array
Returns the n'th field of first row in a SQL query result
Returns the first row in a SQL query result
Returns a SQL modified with a FOR UPDATE clause. The optional `modifier`
Returns the SQL column definition from a column
Gets a list of columns
Gets the active connection unique identifier
Return the default identity value to insert in an identity column
Returns the default value to make the RBDM use the default value declared
Return descriptor used to connect to the active database
Returns internal dialect instance
Returns the name of the dialect used
Return internal PDO handler
Returns the savepoint name to use for nested transactions
Active SQL statement in the object without replace bound parameters
Active SQL statement in the object
Active SQL statement in the object
Active SQL statement in the object
Returns type of database system the adapter is used for
Inserts data into a table using custom RDBMS SQL syntax
Inserts data into a table using custom RBDM SQL syntax
Returns if nested transactions should use savepoints
Checks whether connection is under database transaction
Returns insert id for the auto_increment column inserted in the last SQL
Appends a LIMIT clause to sqlQuery argument
List all tables on a database
List all views on a database
Modifies a table column based on a definition
Sends SQL statements to the database server returning the success state.
Releases given savepoint
Rollbacks the active transaction in the connection
Rollbacks given savepoint
Set if nested transactions should use savepoints
Returns a SQL modified with a shared-lock clause. See the dialect's
Check whether the database system requires a sequence to produce
SQLite does not support the DEFAULT keyword
Generates SQL checking for the existence of a schema.table
Gets creation options from a table
Updates data on a table using custom RDBMS SQL syntax
Updates data on a table using custom RBDM SQL syntax
Check whether the database system requires an explicit value for identity
Generates SQL checking for the existence of a schema.view
### Methods
addColumn()
```php
public function addColumn(
string $tableName,
string $schemaName,
ColumnInterface $column
): bool;
```
Adds a column to a table
addForeignKey()
```php
public function addForeignKey(
string $tableName,
string $schemaName,
ReferenceInterface $reference
): bool;
```
Adds a foreign key to a table
addIndex()
```php
public function addIndex(
string $tableName,
string $schemaName,
IndexInterface $index
): bool;
```
Adds an index to a table
addPrimaryKey()
```php
public function addPrimaryKey(
string $tableName,
string $schemaName,
IndexInterface $index
): bool;
```
Adds a primary key to a table
affectedRows()
```php
public function affectedRows(): int;
```
Returns the number of affected rows by the last INSERT/UPDATE/DELETE
reported by the database system
begin()
```php
public function begin( bool $nesting = true ): bool;
```
Starts a transaction in the connection
close()
```php
public function close(): void;
```
Closes active connection returning success. Phalcon automatically closes
and destroys active connections within Phalcon\Db\Pool
commit()
```php
public function commit( bool $nesting = true ): bool;
```
Commits the active transaction in the connection
connect()
```php
public function connect( array $descriptor = [] ): void;
```
This method is automatically called in \Phalcon\Db\Adapter\Pdo
constructor. Call it when you need to restore a database connection
createSavepoint()
```php
public function createSavepoint( string $name ): bool;
```
Creates a new savepoint
createTable()
```php
public function createTable(
string $tableName,
string $schemaName,
array $definition
): bool;
```
Creates a table
createView()
```php
public function createView(
string $viewName,
array $definition,
string|null $schemaName = null
): bool;
```
Creates a view
delete()
```php
public function delete(
mixed $table,
string|null $whereCondition = null,
array $placeholders = [],
array $dataTypes = []
): bool;
```
Deletes data from a table using custom RDBMS SQL syntax
describeColumns()
```php
public function describeColumns(
string $table,
string|null $schema = null
): ColumnInterface[];
```
Returns an array of Phalcon\Db\Column objects describing a table
describeIndexes()
```php
public function describeIndexes(
string $table,
string|null $schema = null
): IndexInterface[];
```
Lists table indexes
describeReferences()
```php
public function describeReferences(
string $table,
string|null $schema = null
): ReferenceInterface[];
```
Lists table references
dropColumn()
```php
public function dropColumn(
string $tableName,
string $schemaName,
string $columnName
): bool;
```
Drops a column from a table
dropForeignKey()
```php
public function dropForeignKey(
string $tableName,
string $schemaName,
string $referenceName
): bool;
```
Drops a foreign key from a table
dropIndex()
```php
public function dropIndex(
string $tableName,
string $schemaName,
string $indexName
): bool;
```
Drop an index from a table
dropPrimaryKey()
```php
public function dropPrimaryKey(
string $tableName,
string $schemaName
): bool;
```
Drops primary key from a table
dropTable()
```php
public function dropTable(
string $tableName,
string|null $schemaName = null,
bool $ifExists = true
): bool;
```
Drops a table from a schema/database
dropView()
```php
public function dropView(
string $viewName,
string|null $schemaName = null,
bool $ifExists = true
): bool;
```
Drops a view
escapeIdentifier()
```php
public function escapeIdentifier( mixed $identifier ): string;
```
Escapes a column/table/schema name
escapeString()
```php
public function escapeString( string $str ): string;
```
Escapes a value to avoid SQL injections
execute()
```php
public function execute(
string $sqlStatement,
array $bindParams = [],
array $bindTypes = []
): bool;
```
Sends SQL statements to the database server returning the success state.
Use this method only when the SQL statement sent to the server does not
return any rows
fetchAll()
```php
public function fetchAll(
string $sqlQuery,
int $fetchMode = 2,
array $bindParams = [],
array $bindTypes = []
): array;
```
Dumps the complete result of a query into an array
fetchColumn()
```php
public function fetchColumn(
string $sqlQuery,
array $placeholders = [],
mixed $column = 0
): string|bool;
```
Returns the n'th field of first row in a SQL query result
```php
// Getting count of invoices
$invoicesCount = $connection->fetchColumn("SELECT COUNT(*) FROM co_invoices");
print_r($invoicesCount);
// Getting the title of the last created invoice
$invoice = $connection->fetchColumn(
"SELECT inv_id, inv_title FROM co_invoices ORDER BY inv_created_at DESC",
1
);
print_r($invoice);
```
fetchOne()
```php
public function fetchOne(
string $sqlQuery,
int $fetchMode = 2,
array $bindParams = [],
array $bindTypes = []
): array;
```
Returns the first row in a SQL query result
forUpdate()
```php
public function forUpdate(
string $sqlQuery,
string $modifier = ""
): string;
```
Returns a SQL modified with a FOR UPDATE clause. The optional `modifier`
appends a row-lock disposition keyword - pass `Dialect::LOCK_NOWAIT`
or `Dialect::LOCK_SKIP_LOCKED` (or leave as `Dialect::LOCK_NONE`).
getColumnDefinition()
```php
public function getColumnDefinition( ColumnInterface $column ): string;
```
Returns the SQL column definition from a column
getColumnList()
```php
public function getColumnList( mixed $columnList ): string;
```
Gets a list of columns
getConnectionId()
```php
public function getConnectionId(): int;
```
Gets the active connection unique identifier
getDefaultIdValue()
```php
public function getDefaultIdValue(): RawValue;
```
Return the default identity value to insert in an identity column
getDefaultValue()
```php
public function getDefaultValue(): RawValue|null;
```
Returns the default value to make the RBDM use the default value declared
in the table definition
```php
// Inserting a new invoice with a valid default value for the column 'inv_total'
$success = $connection->insert(
"co_invoices",
[
"Test Invoice",
$connection->getDefaultValue()
],
[
"inv_title",
"inv_total",
]
);
```
@todo Return NULL if this is not supported by the adapter
getDescriptor()
```php
public function getDescriptor(): array;
```
Return descriptor used to connect to the active database
getDialect()
```php
public function getDialect(): DialectInterface;
```
Returns internal dialect instance
getDialectType()
```php
public function getDialectType(): string;
```
Returns the name of the dialect used
getInternalHandler()
```php
public function getInternalHandler(): mixed;
```
Return internal PDO handler
getNestedTransactionSavepointName()
```php
public function getNestedTransactionSavepointName(): string;
```
Returns the savepoint name to use for nested transactions
getRealSQLStatement()
```php
public function getRealSQLStatement(): string;
```
Active SQL statement in the object without replace bound parameters
getSQLBindTypes()
```php
public function getSQLBindTypes(): array;
```
Active SQL statement in the object
getSQLStatement()
```php
public function getSQLStatement(): string;
```
Active SQL statement in the object
getSQLVariables()
```php
public function getSQLVariables(): array;
```
Active SQL statement in the object
getType()
```php
public function getType(): string;
```
Returns type of database system the adapter is used for
insert()
```php
public function insert(
string $table,
array $values,
mixed $fields = null,
mixed $dataTypes = null
): bool;
```
Inserts data into a table using custom RDBMS SQL syntax
insertAsDict()
```php
public function insertAsDict(
string $table,
mixed $data,
mixed $dataTypes = null
): bool;
```
Inserts data into a table using custom RBDM SQL syntax
```php
// Inserting a new invoice
$success = $connection->insertAsDict(
"co_invoices",
[
"inv_title" => "Test Invoice",
"inv_total" => 100,
]
);
// Next SQL sentence is sent to the database system
INSERT INTO `co_invoices` (`inv_title`, `inv_total`) VALUES ("Test Invoice", 100);
```
isNestedTransactionsWithSavepoints()
```php
public function isNestedTransactionsWithSavepoints(): bool;
```
Returns if nested transactions should use savepoints
isUnderTransaction()
```php
public function isUnderTransaction(): bool;
```
Checks whether connection is under database transaction
lastInsertId()
```php
public function lastInsertId( string|null $name = null ): string|bool;
```
Returns insert id for the auto_increment column inserted in the last SQL
statement
limit()
```php
public function limit(
string $sqlQuery,
mixed $number
): string;
```
Appends a LIMIT clause to sqlQuery argument
listTables()
```php
public function listTables( string|null $schemaName = null ): array;
```
List all tables on a database
listViews()
```php
public function listViews( string|null $schemaName = null ): array;
```
List all views on a database
modifyColumn()
```php
public function modifyColumn(
string $tableName,
string $schemaName,
ColumnInterface $column,
ColumnInterface|null $currentColumn = null
): bool;
```
Modifies a table column based on a definition
query()
```php
public function query(
string $sqlStatement,
array $bindParams = [],
array $bindTypes = []
): ResultInterface|bool;
```
Sends SQL statements to the database server returning the success state.
Use this method only when the SQL statement sent to the server returns
rows
releaseSavepoint()
```php
public function releaseSavepoint( string $name ): bool;
```
Releases given savepoint
rollback()
```php
public function rollback( bool $nesting = true ): bool;
```
Rollbacks the active transaction in the connection
rollbackSavepoint()
```php
public function rollbackSavepoint( string $name ): bool;
```
Rollbacks given savepoint
setNestedTransactionsWithSavepoints()
```php
public function setNestedTransactionsWithSavepoints( bool $nestedTransactionsWithSavepoints ): \Phalcon\Db\Adapter\AdapterInterface;
```
Set if nested transactions should use savepoints
sharedLock()
```php
public function sharedLock(
string $sqlQuery,
string $modifier = ""
): string;
```
Returns a SQL modified with a shared-lock clause. See the dialect's
`sharedLock()` for per-engine semantics. The optional `modifier` is
passed straight through (use `Dialect::LOCK_NOWAIT` /
`Dialect::LOCK_SKIP_LOCKED` for PostgreSQL).
supportSequences()
```php
public function supportSequences(): bool;
```
Check whether the database system requires a sequence to produce
auto-numeric values
supportsDefaultValue()
```php
public function supportsDefaultValue(): bool;
```
SQLite does not support the DEFAULT keyword
tableExists()
```php
public function tableExists(
string $tableName,
string|null $schemaName = null
): bool;
```
Generates SQL checking for the existence of a schema.table
tableOptions()
```php
public function tableOptions(
string $tableName,
string|null $schemaName = null
): array;
```
Gets creation options from a table
update()
```php
public function update(
string $table,
mixed $fields,
mixed $values,
mixed $whereCondition = null,
mixed $dataTypes = null
): bool;
```
Updates data on a table using custom RDBMS SQL syntax
updateAsDict()
```php
public function updateAsDict(
string $table,
mixed $data,
mixed $whereCondition = null,
mixed $dataTypes = null
): bool;
```
Updates data on a table using custom RBDM SQL syntax
Another, more convenient syntax
```php
// Updating existing invoice
$success = $connection->updateAsDict(
"co_invoices",
[
"inv_title" => "New Test Invoice",
],
"inv_id = 101"
);
// Next SQL sentence is sent to the database system
UPDATE `co_invoices` SET `inv_title` = "New Test Invoice" WHERE inv_id = 101
```
useExplicitIdValue()
```php
public function useExplicitIdValue(): bool;
```
Check whether the database system requires an explicit value for identity
columns
viewExists()
```php
public function viewExists(
string $viewName,
string|null $schemaName = null
): bool;
```
Generates SQL checking for the existence of a schema.view
## Contracts\Db\Check
Interface
Canonical contract for Phalcon\Db\Check.
- **`Phalcon\Contracts\Db\Check`**
- [`Phalcon\Db\CheckInterface`](/5.20/api/phalcon_db/#dbcheckinterface)
### Method Summary
Gets the CHECK expression (the SQL boolean predicate).
Gets the constraint name. An empty string indicates an unnamed CHECK
### Methods
getExpression()
```php
public function getExpression(): string;
```
Gets the CHECK expression (the SQL boolean predicate).
getName()
```php
public function getName(): string;
```
Gets the constraint name. An empty string indicates an unnamed CHECK
constraint - the dialect will emit the clause without a `CONSTRAINT`
prefix in that case.
## Contracts\Db\Column
Interface
Canonical contract for Phalcon\Db\Column.
@todo v7 - these will become required interface members. They are
omitted from the v5 line to avoid breaking third-party
implementors:
- getGenerationExpression() : string | null
- isArray() : bool
- isGenerated() : bool
- isGenerationStored() : bool
- isInvisible() : bool
- **`Phalcon\Contracts\Db\Column`**
- [`Phalcon\Db\ColumnInterface`](/5.20/api/phalcon_db/#dbcolumninterface)
### Method Summary
Check whether field absolute to position in table
Returns the type of bind handling
Returns default value of column
Returns column name
Returns column scale
Returns column size
Returns column type
Returns column type reference
Returns column type values
Check whether column has default value
Auto-Increment
Check whether column have first position in table
Not null
Check whether column have an numeric type
Column is part of the primary key?
Returns true if number column is unsigned
### Methods
getAfterPosition()
```php
public function getAfterPosition(): string|null;
```
Check whether field absolute to position in table
getBindType()
```php
public function getBindType(): int;
```
Returns the type of bind handling
getDefault()
```php
public function getDefault(): mixed;
```
Returns default value of column
getName()
```php
public function getName(): string;
```
Returns column name
getScale()
```php
public function getScale(): int;
```
Returns column scale
getSize()
```php
public function getSize(): int|string;
```
Returns column size
getType()
```php
public function getType(): int|string;
```
Returns column type
getTypeReference()
```php
public function getTypeReference(): int;
```
Returns column type reference
getTypeValues()
```php
public function getTypeValues(): array|string|int;
```
Returns column type values
hasDefault()
```php
public function hasDefault(): bool;
```
Check whether column has default value
isAutoIncrement()
```php
public function isAutoIncrement(): bool;
```
Auto-Increment
isFirst()
```php
public function isFirst(): bool;
```
Check whether column have first position in table
isNotNull()
```php
public function isNotNull(): bool;
```
Not null
isNumeric()
```php
public function isNumeric(): bool;
```
Check whether column have an numeric type
isPrimary()
```php
public function isPrimary(): bool;
```
Column is part of the primary key?
isUnsigned()
```php
public function isUnsigned(): bool;
```
Returns true if number column is unsigned
## Contracts\Db\Dialect
Interface
Canonical contract for Phalcon\Db dialects.
@todo v7 - these will become required interface members. They are
omitted from the v5 line to avoid breaking third-party
implementors:
- addCheck() : string
- createMaterializedView() : string
- dropCheck() : string
- dropMaterializedView() : string
- onConflictUpdate() : string
- refreshMaterializedView() : string
- returning() : string
- **`Phalcon\Contracts\Db\Dialect`**
- [`Phalcon\Db\DialectInterface`](/5.20/api/phalcon_db/#dbdialectinterface)
`Phalcon\Db\ColumnInterface` · `Phalcon\Db\IndexInterface` · `Phalcon\Db\ReferenceInterface`
### Method Summary
Generates SQL to add a column to a table
Generates SQL to add an index to a table
Generates SQL to add an index to a table
Generates SQL to add the primary key to a table
Generate SQL to create a new savepoint
Generates SQL to create a table
Generates SQL to create a view
Generates SQL to describe a table
Generates SQL to query indexes on a table.
Generates SQL to query foreign keys on a table.
Generates SQL to delete a column from a table
Generates SQL to delete a foreign key from a table
Generates SQL to delete an index from a table
Generates SQL to delete primary key from a table
Generates SQL to drop a table
Generates SQL to drop a view
Returns a SQL modified with a FOR UPDATE clause. The optional `modifier`
Gets the column name in RDBMS
Gets a list of columns
Returns registered functions
Transforms an intermediate representation for an expression into a
Generates the SQL for LIMIT clause
List all tables in database
Generates SQL to modify a column in a table
Registers custom SQL functions
Generate SQL to release a savepoint
Generate SQL to rollback a savepoint
Builds a SELECT statement
Returns a SQL modified with a shared-lock clause. MySQL emits
Checks whether the platform supports releasing savepoints.
Checks whether the platform supports savepoints
Generates SQL checking for the existence of a schema.table
Generates the SQL to describe the table creation options
Generates SQL checking for the existence of a schema.view
### Constants
No row-lock modifier - the default behavior for `forUpdate()`.
Append `NOWAIT` to the `FOR UPDATE` clause - the query fails immediately
if a row it needs is locked instead of blocking. MySQL 8.0+ and
PostgreSQL 9.5+ recognize this. SQLite has no row-level locking and
silently ignores the modifier.
Append `SKIP LOCKED` to the `FOR UPDATE` clause - the query returns
rows that are not currently locked and silently skips ones that are.
MySQL 8.0+ and PostgreSQL 9.5+ recognize this. SQLite ignores it.
### Methods
addColumn()
```php
public function addColumn(
string $tableName,
string $schemaName,
ColumnInterface $column
): string;
```
Generates SQL to add a column to a table
addForeignKey()
```php
public function addForeignKey(
string $tableName,
string $schemaName,
ReferenceInterface $reference
): string;
```
Generates SQL to add an index to a table
addIndex()
```php
public function addIndex(
string $tableName,
string $schemaName,
IndexInterface $index
): string;
```
Generates SQL to add an index to a table
addPrimaryKey()
```php
public function addPrimaryKey(
string $tableName,
string $schemaName,
IndexInterface $index
): string;
```
Generates SQL to add the primary key to a table
createSavepoint()
```php
public function createSavepoint( string $name ): string;
```
Generate SQL to create a new savepoint
createTable()
```php
public function createTable(
string $tableName,
string $schemaName,
array $definition
): string;
```
Generates SQL to create a table
createView()
```php
public function createView(
string $viewName,
array $definition,
string|null $schemaName = null
): string;
```
Generates SQL to create a view
describeColumns()
```php
public function describeColumns(
string $table,
string|null $schema = null
): string;
```
Generates SQL to describe a table
describeIndexes()
```php
public function describeIndexes(
string $table,
string|null $schema = null
): string;
```
Generates SQL to query indexes on a table.
The base adapter consumes the result as `FETCH_NUM` rows by position:
column index 2 must be the index key name and column index 4 the indexed
column name.
describeReferences()
```php
public function describeReferences(
string $table,
string|null $schema = null
): string;
```
Generates SQL to query foreign keys on a table.
The base adapter consumes the result as `FETCH_NUM` rows by position:
index 1 the local column, index 2 the constraint name, index 3 the
referenced schema, index 4 the referenced table, and index 5 the
referenced column.
dropColumn()
```php
public function dropColumn(
string $tableName,
string $schemaName,
string $columnName
): string;
```
Generates SQL to delete a column from a table
dropForeignKey()
```php
public function dropForeignKey(
string $tableName,
string $schemaName,
string $referenceName
): string;
```
Generates SQL to delete a foreign key from a table
dropIndex()
```php
public function dropIndex(
string $tableName,
string $schemaName,
string $indexName
): string;
```
Generates SQL to delete an index from a table
dropPrimaryKey()
```php
public function dropPrimaryKey(
string $tableName,
string $schemaName
): string;
```
Generates SQL to delete primary key from a table
dropTable()
```php
public function dropTable(
string $tableName,
string $schemaName,
bool $ifExists = true
): string;
```
Generates SQL to drop a table
dropView()
```php
public function dropView(
string $viewName,
string|null $schemaName = null,
bool $ifExists = true
): string;
```
Generates SQL to drop a view
forUpdate()
```php
public function forUpdate(
string $sqlQuery,
string $modifier = ""
): string;
```
Returns a SQL modified with a FOR UPDATE clause. The optional `modifier`
appends a row-lock disposition keyword - pass `Dialect::LOCK_NOWAIT`
or `Dialect::LOCK_SKIP_LOCKED` (or leave as `Dialect::LOCK_NONE`).
getColumnDefinition()
```php
public function getColumnDefinition( ColumnInterface $column ): string;
```
Gets the column name in RDBMS
getColumnList()
```php
public function getColumnList( array $columnList ): string;
```
Gets a list of columns
getCustomFunctions()
```php
public function getCustomFunctions(): array;
```
Returns registered functions
getSqlExpression()
```php
public function getSqlExpression(
array $expression,
string|null $escapeChar = null,
array $bindCounts = []
): string;
```
Transforms an intermediate representation for an expression into a
database system valid expression
limit()
```php
public function limit(
string $sqlQuery,
mixed $number
): string;
```
Generates the SQL for LIMIT clause
listTables()
```php
public function listTables( string|null $schemaName = null ): string;
```
List all tables in database
modifyColumn()
```php
public function modifyColumn(
string $tableName,
string $schemaName,
ColumnInterface $column,
ColumnInterface|null $currentColumn = null
): string;
```
Generates SQL to modify a column in a table
registerCustomFunction()
```php
public function registerCustomFunction(
string $name,
callable $customFunction
): \Phalcon\Db\Dialect;
```
Registers custom SQL functions
releaseSavepoint()
```php
public function releaseSavepoint( string $name ): string;
```
Generate SQL to release a savepoint
rollbackSavepoint()
```php
public function rollbackSavepoint( string $name ): string;
```
Generate SQL to rollback a savepoint
select()
```php
public function select( array $definition ): string;
```
Builds a SELECT statement
sharedLock()
```php
public function sharedLock(
string $sqlQuery,
string $modifier = ""
): string;
```
Returns a SQL modified with a shared-lock clause. MySQL emits
`LOCK IN SHARE MODE`; PostgreSQL emits `FOR SHARE`; SQLite returns the
original query unchanged. The optional `modifier` appends a row-lock
disposition keyword (`Dialect::LOCK_NOWAIT` / `Dialect::LOCK_SKIP_LOCKED`)
for PostgreSQL - MySQL's legacy `LOCK IN SHARE MODE` does not support
modifiers, so non-empty values are silently ignored on MySQL.
supportsReleaseSavepoints()
```php
public function supportsReleaseSavepoints(): bool;
```
Checks whether the platform supports releasing savepoints.
supportsSavepoints()
```php
public function supportsSavepoints(): bool;
```
Checks whether the platform supports savepoints
tableExists()
```php
public function tableExists(
string $tableName,
string|null $schemaName = null
): string;
```
Generates SQL checking for the existence of a schema.table
tableOptions()
```php
public function tableOptions(
string $table,
string|null $schema = null
): string;
```
Generates the SQL to describe the table creation options
viewExists()
```php
public function viewExists(
string $viewName,
string|null $schemaName = null
): string;
```
Generates SQL checking for the existence of a schema.view
## Contracts\Db\Geometry\Geometry
Interface
Canonical contract for Phalcon\Db\Geometry value objects.
- **`Phalcon\Contracts\Db\Geometry\Geometry`**
- [`Phalcon\Db\Geometry\GeometryInterface`](/5.20/api/phalcon_db/#dbgeometrygeometryinterface)
### Method Summary
Gets the Spatial Reference System Identifier (SRID).
Gets the geometry type.
Renders the geometry as a Well-Known Text (WKT) string.
### Methods
getSrid()
```php
public function getSrid(): int;
```
Gets the Spatial Reference System Identifier (SRID).
getType()
```php
public function getType(): int;
```
Gets the geometry type.
toWkt()
```php
public function toWkt(): string;
```
Renders the geometry as a Well-Known Text (WKT) string.
## Contracts\Db\Index
Interface
Canonical contract for Phalcon\Db\Index.
@todo v7 - these will become required interface members. They are
omitted from the v5 line to avoid breaking third-party
implementors:
- getDirections() : array
- getWhere() : string
- isConcurrent() : bool
- isInvisible() : bool
- **`Phalcon\Contracts\Db\Index`**
- [`Phalcon\Db\IndexInterface`](/5.20/api/phalcon_db/#dbindexinterface)
### Method Summary
Gets the columns that corresponds the index
Gets the index name
Gets the index type
### Methods
getColumns()
```php
public function getColumns(): array;
```
Gets the columns that corresponds the index
getName()
```php
public function getName(): string;
```
Gets the index name
getType()
```php
public function getType(): string;
```
Gets the index type
## Contracts\Db\Reference
Interface
Canonical contract for Phalcon\Db\Reference.
- **`Phalcon\Contracts\Db\Reference`**
- [`Phalcon\Db\ReferenceInterface`](/5.20/api/phalcon_db/#dbreferenceinterface)
### Method Summary
Gets local columns which reference is based
Gets the index name
Gets the referenced on delete
Gets the referenced on update
Gets referenced columns
Gets the schema where referenced table is
Gets the referenced table
Gets the schema where referenced table is
### Methods
getColumns()
```php
public function getColumns(): array;
```
Gets local columns which reference is based
getName()
```php
public function getName(): string;
```
Gets the index name
getOnDelete()
```php
public function getOnDelete(): string|null;
```
Gets the referenced on delete
getOnUpdate()
```php
public function getOnUpdate(): string|null;
```
Gets the referenced on update
getReferencedColumns()
```php
public function getReferencedColumns(): array;
```
Gets referenced columns
getReferencedSchema()
```php
public function getReferencedSchema(): string|null;
```
Gets the schema where referenced table is
getReferencedTable()
```php
public function getReferencedTable(): string;
```
Gets the referenced table
getSchemaName()
```php
public function getSchemaName(): string|null;
```
Gets the schema where referenced table is
## Contracts\Db\Result
Interface
Canonical contract for Phalcon\Db result objects.
- **`Phalcon\Contracts\Db\Result`**
- [`Phalcon\Db\ResultInterface`](/5.20/api/phalcon_db/#dbresultinterface)
### Method Summary
Moves internal resultset cursor to another position letting us to fetch a
Allows to execute the statement again. Some database systems don't
Fetches an array/object of strings that corresponds to the fetched row,
Returns an array of arrays containing all the records in the result. This
Returns an array of strings that corresponds to the fetched row, or FALSE
Gets the internal PDO result object
Gets number of rows returned by a resultset
Changes the fetching mode affecting Phalcon\Db\Result\Pdo::fetch()
### Methods
dataSeek()
```php
public function dataSeek( int $number );
```
Moves internal resultset cursor to another position letting us to fetch a
certain row
execute()
```php
public function execute(): bool;
```
Allows to execute the statement again. Some database systems don't
support scrollable cursors. So, as cursors are forward only, we need to
execute the cursor again to fetch rows from the beginning
fetch()
```php
public function fetch(): mixed;
```
Fetches an array/object of strings that corresponds to the fetched row,
or FALSE if there are no more rows. This method is affected by the active
fetch flag set using `Phalcon\Db\Result\Pdo::setFetchMode()`
fetchAll()
```php
public function fetchAll(): array;
```
Returns an array of arrays containing all the records in the result. This
method is affected by the active fetch flag set using
`Phalcon\Db\Result\Pdo::setFetchMode()`
fetchArray()
```php
public function fetchArray(): mixed;
```
Returns an array of strings that corresponds to the fetched row, or FALSE
if there are no more rows. This method is affected by the active fetch
flag set using `Phalcon\Db\Result\Pdo::setFetchMode()`
getInternalResult()
```php
public function getInternalResult(): \PDOStatement;
```
Gets the internal PDO result object
numRows()
```php
public function numRows(): int;
```
Gets number of rows returned by a resultset
setFetchMode()
```php
public function setFetchMode( int $fetchMode ): bool;
```
Changes the fetching mode affecting Phalcon\Db\Result\Pdo::fetch()
## Contracts\Dispatcher\Dispatcher
Interface
Canonical contract for Phalcon\Dispatcher\AbstractDispatcher.
Note: The deprecated `getParam()`/`getParams()`/`hasParam()`/`setParam()`/
`setParams()` spellings are still declared for backwards compatibility and
are scheduled to be removed in the next major version in favor of their
`*Parameter` counterparts.
- **`Phalcon\Contracts\Dispatcher\Dispatcher`**
- [`Phalcon\Contracts\Cli\Dispatcher`](#contractsclidispatcher)
- [`Phalcon\Contracts\Mvc\Dispatcher`](#contractsmvcdispatcher)
- [`Phalcon\Dispatcher\DispatcherInterface`](/5.20/api/phalcon_dispatcher/#dispatcherdispatcherinterface)
### Method Summary
Dispatches a handle action taking into account the routing parameters
Forwards the execution flow to another controller/action
Gets last dispatched action name
Gets the default action suffix
Gets the default handler suffix
Gets a param by its name or numeric index
Gets a param by its name or numeric index
Gets action params
Gets action params
Returns value returned by the latest dispatched action
Check if a param exists
Checks if the dispatch loop is finished or has more pendent
Sets the action name to be dispatched
Sets the default action suffix
Sets the default action name
Sets the default namespace
Sets the default suffix for the handler
Sets the module name which the application belongs to
Sets the namespace which the controller belongs to
Set a param by its name or numeric index
Sets action params to be dispatched
### Methods
dispatch()
```php
public function dispatch(): mixed|bool;
```
Dispatches a handle action taking into account the routing parameters
forward()
```php
public function forward( array $forward ): void;
```
Forwards the execution flow to another controller/action
getActionName()
```php
public function getActionName(): string;
```
Gets last dispatched action name
getActionSuffix()
```php
public function getActionSuffix(): string;
```
Gets the default action suffix
getHandlerSuffix()
```php
public function getHandlerSuffix(): string;
```
Gets the default handler suffix
getParam()
```php
public function getParam(
mixed $param,
mixed $filters = null
): mixed;
```
Gets a param by its name or numeric index
Note: This signature omits the `defaultValue` argument the implementation
accepts; the two will be aligned in the next major version.
getParameter()
```php
public function getParameter(
mixed $param,
mixed $filters = null
): mixed;
```
Gets a param by its name or numeric index
getParameters()
```php
public function getParameters(): array;
```
Gets action params
getParams()
```php
public function getParams(): array;
```
Gets action params
getReturnedValue()
```php
public function getReturnedValue(): mixed;
```
Returns value returned by the latest dispatched action
hasParam()
```php
public function hasParam( mixed $param ): bool;
```
Check if a param exists
isFinished()
```php
public function isFinished(): bool;
```
Checks if the dispatch loop is finished or has more pendent
controllers/tasks to dispatch
setActionName()
```php
public function setActionName( string $actionName ): void;
```
Sets the action name to be dispatched
setActionSuffix()
```php
public function setActionSuffix( string $actionSuffix ): void;
```
Sets the default action suffix
setDefaultAction()
```php
public function setDefaultAction( string $actionName ): void;
```
Sets the default action name
setDefaultNamespace()
```php
public function setDefaultNamespace( string $defaultNamespace ): void;
```
Sets the default namespace
setHandlerSuffix()
```php
public function setHandlerSuffix( string $handlerSuffix ): void;
```
Sets the default suffix for the handler
setModuleName()
```php
public function setModuleName( string|null $moduleName = null ): void;
```
Sets the module name which the application belongs to
setNamespaceName()
```php
public function setNamespaceName( string $namespaceName ): void;
```
Sets the namespace which the controller belongs to
setParam()
```php
public function setParam(
mixed $param,
mixed $value
): void;
```
Set a param by its name or numeric index
setParams()
```php
public function setParams( array $params ): void;
```
Sets action params to be dispatched
## Contracts\Dispatcher\DispatcherTypes
Interface
Central registry of the array shapes used across the Dispatcher namespace.
- **`Phalcon\Contracts\Dispatcher\DispatcherTypes`**
## Contracts\Domain\Payload\Payload
Interface
Canonical combined read/write contract for a domain payload.
`Payload` extends both `Writeable` and `Readable`, exposing the full
capability set. The intended convention narrows that surface by which side of
the Action-Domain-Responder boundary holds the payload: the domain layer
builds the payload through `Writeable` (the setters), while the responder
consumes the finished payload through `Readable` (the getters). Type-hinting
against the narrower contract at each boundary keeps each side to the
capability it needs, even though the concrete payload implements both.
@see Readable
@see Writeable
- [`Phalcon\Contracts\Domain\Payload\Readable`](#contractsdomainpayloadreadable)
- **`Phalcon\Contracts\Domain\Payload\Payload`** - extends [`Phalcon\Contracts\Domain\Payload\Readable`](#contractsdomainpayloadreadable), [`Phalcon\Contracts\Domain\Payload\Writeable`](#contractsdomainpayloadwriteable)
## Contracts\Domain\Payload\Readable
Interface
Canonical read-only contract for a domain payload.
Responders consume a finished payload through this contract (the getters),
narrowing the surface to the read side of the Action-Domain-Responder
boundary.
- **`Phalcon\Contracts\Domain\Payload\Readable`**
- [`Phalcon\Contracts\Domain\Payload\Payload`](#contractsdomainpayloadpayload)
- [`Phalcon\Domain\Payload\ReadableInterface`](/5.20/api/phalcon_domain/#domainpayloadreadableinterface)
`Throwable`
### Method Summary
Gets the potential exception thrown in the domain layer
Gets arbitrary extra values produced by the domain layer.
Gets the input received by the domain layer.
Gets the messages produced by the domain layer.
Gets the output produced from the domain layer.
Gets the status of this payload.
### Methods
getException()
```php
public function getException(): Throwable|null;
```
Gets the potential exception thrown in the domain layer
getExtras()
```php
public function getExtras(): mixed;
```
Gets arbitrary extra values produced by the domain layer.
getInput()
```php
public function getInput(): mixed;
```
Gets the input received by the domain layer.
getMessages()
```php
public function getMessages(): mixed;
```
Gets the messages produced by the domain layer.
getOutput()
```php
public function getOutput(): mixed;
```
Gets the output produced from the domain layer.
getStatus()
```php
public function getStatus(): mixed;
```
Gets the status of this payload.
Status values are drawn from the `Status` vocabulary.
@see \Phalcon\Domain\Payload\Status
## Contracts\Domain\Payload\Writeable
Interface
Canonical write-only contract for a domain payload.
The domain layer builds a payload through this contract (the setters),
narrowing the surface to the write side of the Action-Domain-Responder
boundary.
- **`Phalcon\Contracts\Domain\Payload\Writeable`**
- [`Phalcon\Domain\Payload\WriteableInterface`](/5.20/api/phalcon_domain/#domainpayloadwriteableinterface)
`Throwable`
### Method Summary
Sets an exception produced by the domain layer.
Sets arbitrary extra values produced by the domain layer.
Sets the input received by the domain layer.
Sets the messages produced by the domain layer.
Sets the output produced from the domain layer.
Sets the status of this payload.
### Methods
setException()
```php
public function setException( Throwable $exception ): Payload;
```
Sets an exception produced by the domain layer.
setExtras()
```php
public function setExtras( mixed $extras ): Payload;
```
Sets arbitrary extra values produced by the domain layer.
setInput()
```php
public function setInput( mixed $input ): Payload;
```
Sets the input received by the domain layer.
setMessages()
```php
public function setMessages( mixed $messages ): Payload;
```
Sets the messages produced by the domain layer.
setOutput()
```php
public function setOutput( mixed $output ): Payload;
```
Sets the output produced from the domain layer.
setStatus()
```php
public function setStatus( mixed $status ): Payload;
```
Sets the status of this payload.
Status values are drawn from the `Status` vocabulary.
@see \Phalcon\Domain\Payload\Status
## Contracts\Encryption\Crypt\Crypt
Interface
Canonical contract for Phalcon\Encryption\Crypt.
The encrypted payload produced by `encrypt()` uses the wire format:
iv ‖ hmac ‖ ciphertext ‖ tag
where `hmac` is present only when signing is enabled (`useSigning(true)`,
the default) and `tag` is present only for AEAD ciphers (`gcm`/`ccm`).
The AEAD parameters (`authData`, `authTag`, `authTagLength`) are instance
state set through the relevant setters and shared across every
`encrypt()`/`decrypt()` call on the instance. A `Crypt` service shared
through the DI container is therefore not safe for interleaved AEAD
operations.
- **`Phalcon\Contracts\Encryption\Crypt\Crypt`**
- [`Phalcon\Encryption\Crypt\CryptInterface`](/5.20/api/phalcon_encryption/#encryptioncryptcryptinterface)
### Method Summary
Decrypts a text
Decrypt a text that is coded as a base64 string
Encrypts a text
Encrypts a text returning the result as a base64 string
Returns authentication data
Returns the authentication tag
Returns the authentication tag length
Returns a list of available cyphers
Returns the current cipher
Returns the encryption key
Sets authentication data
Sets the authentication tag
Sets the authentication tag length
Sets the cipher algorithm
Sets the encryption key
Changes the padding scheme used.
Sets if the calculating message digest must be used.
### Methods
decrypt()
```php
public function decrypt(
string $input,
string|null $key = null
): string;
```
Decrypts a text
decryptBase64()
```php
public function decryptBase64(
string $input,
string|null $key = null
): string;
```
Decrypt a text that is coded as a base64 string
encrypt()
```php
public function encrypt(
string $input,
string|null $key = null
): string;
```
Encrypts a text
encryptBase64()
```php
public function encryptBase64(
string $input,
string|null $key = null
): string;
```
Encrypts a text returning the result as a base64 string
getAuthData()
```php
public function getAuthData(): string;
```
Returns authentication data
getAuthTag()
```php
public function getAuthTag(): string;
```
Returns the authentication tag
getAuthTagLength()
```php
public function getAuthTagLength(): int;
```
Returns the authentication tag length
getAvailableCiphers()
```php
public function getAvailableCiphers(): array;
```
Returns a list of available cyphers
getCipher()
```php
public function getCipher(): string;
```
Returns the current cipher
getKey()
```php
public function getKey(): string;
```
Returns the encryption key
setAuthData()
```php
public function setAuthData( string $data ): Crypt;
```
Sets authentication data
setAuthTag()
```php
public function setAuthTag( string $tag ): Crypt;
```
Sets the authentication tag
setAuthTagLength()
```php
public function setAuthTagLength( int $length ): Crypt;
```
Sets the authentication tag length
setCipher()
```php
public function setCipher( string $cipher ): Crypt;
```
Sets the cipher algorithm
setKey()
```php
public function setKey( string $key ): Crypt;
```
Sets the encryption key
setPadding()
```php
public function setPadding( int $scheme ): Crypt;
```
Changes the padding scheme used.
useSigning()
```php
public function useSigning( bool $useSigning ): Crypt;
```
Sets if the calculating message digest must be used.
## Contracts\Encryption\Crypt\Padding\Pad
Interface
Canonical contract for Phalcon\Encryption\Crypt\Padding strategies.
The pad/unpad protocol operates on binary (8-bit) data. Implementations
must measure and slice the input with byte-true functions (`strlen`,
`substr`, or the `mb_*` family with the explicit `"8bit"` encoding); using
encoding-sensitive functions such as `mb_strlen()` on the padded plaintext
yields the wrong padding size whenever the bytes form valid multibyte
sequences.
- **`Phalcon\Contracts\Encryption\Crypt\Padding\Pad`**
- [`Phalcon\Encryption\Crypt\Padding\PadInterface`](/5.20/api/phalcon_encryption/#encryptioncryptpaddingpadinterface)
### Method Summary
### Methods
pad()
```php
public function pad( int $paddingSize ): string;
```
unpad()
```php
public function unpad(
string $input,
int $blockSize
): int;
```
## Contracts\Encryption\Security\CryptoUtils
Interface
- **`Phalcon\Contracts\Encryption\Security\CryptoUtils`**
- [`Phalcon\Contracts\Encryption\Security\Security`](#contractsencryptionsecuritysecurity)
`Phalcon\Encryption\Security\Random`
### Method Summary
### Methods
computeHmac()
```php
public function computeHmac(
string $data,
string $key,
string $algorithm,
bool $raw = false
): string;
```
getRandom()
```php
public function getRandom(): Random;
```
getRandomBytes()
```php
public function getRandomBytes(): int;
```
getSaltBytes()
```php
public function getSaltBytes( int $numberBytes = 0 ): string;
```
setRandomBytes()
```php
public function setRandomBytes( int $randomBytes ): Security;
```
## Contracts\Encryption\Security\CsrfProtection
Interface
- **`Phalcon\Contracts\Encryption\Security\CsrfProtection`**
### Method Summary
### Methods
checkToken()
```php
public function checkToken(
string|null $tokenKey = null,
mixed $tokenValue = null,
bool $destroyIfValid = true
): bool;
```
destroyToken()
```php
public function destroyToken(): Security;
```
getRequestToken()
```php
public function getRequestToken(): string|null;
```
getSessionToken()
```php
public function getSessionToken(): string|null;
```
getToken()
```php
public function getToken(): string|null;
```
getTokenKey()
```php
public function getTokenKey(): string|null;
```
## Contracts\Encryption\Security\JWT\Signer\Signer
Interface
Canonical contract for JWT Signer classes
- **`Phalcon\Contracts\Encryption\Security\JWT\Signer\Signer`**
- [`Phalcon\Encryption\Security\JWT\Signer\SignerInterface`](/5.20/api/phalcon_encryption/#encryptionsecurityjwtsignersignerinterface)
### Method Summary
Return the value that is used for the "alg" header
Return the algorithm used
Sign a payload using the passphrase
Verify a passed source with a payload and passphrase
### Methods
```php
public function getAlgHeader(): string;
```
Return the value that is used for the "alg" header
getAlgorithm()
```php
public function getAlgorithm(): string;
```
Return the algorithm used
sign()
```php
public function sign(
string $payload,
string $passphrase
): string;
```
Sign a payload using the passphrase
verify()
```php
public function verify(
string $source,
string $payload,
string $passphrase
): bool;
```
Verify a passed source with a payload and passphrase
## Contracts\Encryption\Security\PasswordSecurity
Interface
- **`Phalcon\Contracts\Encryption\Security\PasswordSecurity`**
### Method Summary
### Methods
checkHash()
```php
public function checkHash(
string $password,
string $passwordHash,
int $maxPassLength = 0
): bool;
```
getDefaultHash()
```php
public function getDefaultHash(): int;
```
```php
public function getHashInformation( string $hash ): array;
```
getWorkFactor()
```php
public function getWorkFactor(): int;
```
hash()
```php
public function hash(
string $password,
array $options = []
): string;
```
isLegacyHash()
```php
public function isLegacyHash( string $passwordHash ): bool;
```
setDefaultHash()
```php
public function setDefaultHash( int $defaultHash ): Security;
```
setWorkFactor()
```php
public function setWorkFactor( int $workFactor ): Security;
```
## Contracts\Encryption\Security\Security
Interface
- [`Phalcon\Contracts\Encryption\Security\CryptoUtils`](#contractsencryptionsecuritycryptoutils)
- **`Phalcon\Contracts\Encryption\Security\Security`** - extends [`Phalcon\Contracts\Encryption\Security\CryptoUtils`](#contractsencryptionsecuritycryptoutils), [`Phalcon\Contracts\Encryption\Security\CsrfProtection`](#contractsencryptionsecuritycsrfprotection), [`Phalcon\Contracts\Encryption\Security\PasswordSecurity`](#contractsencryptionsecuritypasswordsecurity)
## Contracts\Encryption\Security\Uuid\NodeProvider
Interface
- **`Phalcon\Contracts\Encryption\Security\Uuid\NodeProvider`**
- [`Phalcon\Encryption\Security\Uuid\NodeProviderInterface`](/5.20/api/phalcon_encryption/#encryptionsecurityuuidnodeproviderinterface)
### Method Summary
### Methods
getNode()
```php
public function getNode(): string;
```
## Contracts\Encryption\Security\Uuid\TimeBasedUuid
Interface
- **`Phalcon\Contracts\Encryption\Security\Uuid\TimeBasedUuid`**
- [`Phalcon\Encryption\Security\Uuid\TimeBasedUuidInterface`](/5.20/api/phalcon_encryption/#encryptionsecurityuuidtimebaseduuidinterface)
### Method Summary
### Methods
getDateTime()
```php
public function getDateTime(): \DateTimeImmutable;
```
getNode()
```php
public function getNode(): string;
```
## Contracts\Encryption\Security\Uuid\Uuid
Interface
Canonical marker contract for UUID version adapters.
Also carries the standard RFC 4122 namespace UUIDs as constants.
- **`Phalcon\Contracts\Encryption\Security\Uuid\Uuid`**
- [`Phalcon\Encryption\Security\Uuid\UuidInterface`](/5.20/api/phalcon_encryption/#encryptionsecurityuuiduuidinterface)
### Constants
## Contracts\Events\Enumerable
Interface
Optional capability contract for an events manager that can report every
attached listener in one call. Callers detect support with `instanceof`.
Deliberately separate from Manager rather than a member of it: adding a
member to a published interface breaks every implementor, so a second,
narrow interface states the capability without touching the first.
Tooling that reports on an events manager type-hints this instead of the
concrete Manager, so it depends on a published contract rather than on an
implementation detail that is free to change.
- **`Phalcon\Contracts\Events\Enumerable`**
### Method Summary
Returns every event type that currently has at least one listener,
### Methods
getListenerMap()
```php
public function getListenerMap(): array;
```
Returns every event type that currently has at least one listener,
mapped to that type's listeners. Types contributed by subscribers are
included, because addSubscriber() attaches through the regular listener
pipeline.
## Contracts\Events\Event
Interface
Canonical contract for Phalcon\Events\Event.
- **`Phalcon\Contracts\Events\Event`**
- [`Phalcon\Events\EventInterface`](/5.20/api/phalcon_events/#eventseventinterface)
### Method Summary
Gets event data
Gets event type
Check whether the event is cancelable
Check whether the event is currently stopped
Sets event data
Sets event type
Stops the event preventing propagation
### Methods
getData()
```php
public function getData(): mixed;
```
Gets event data
getType()
```php
public function getType(): mixed;
```
Gets event type
isCancelable()
```php
public function isCancelable(): bool;
```
Check whether the event is cancelable
isStopped()
```php
public function isStopped(): bool;
```
Check whether the event is currently stopped
setData()
```php
public function setData( mixed $data = null ): Event;
```
Sets event data
setType()
```php
public function setType( string $type ): Event;
```
Sets event type
stop()
```php
public function stop(): Event;
```
Stops the event preventing propagation
## Contracts\Events\EventsAware
Interface
Canonical contract for Phalcon\Events\EventsAwareInterface. Implemented by
components that accept an events manager and dispatch through it.
Cross-references the legacy ManagerInterface (not the canonical Manager
contract) to preserve LSP for the many AbstractEventsAware subclasses that
already type-hint ManagerInterface. ManagerInterface extends Manager, so
this remains type-compatible with any code that needs the canonical surface.
- **`Phalcon\Contracts\Events\EventsAware`**
- [`Phalcon\Events\EventsAwareInterface`](/5.20/api/phalcon_events/#eventseventsawareinterface)
`Phalcon\Events\ManagerInterface`
### Method Summary
Returns the internal events manager
Sets the events manager
### Methods
getEventsManager()
```php
public function getEventsManager(): ManagerInterface|null;
```
Returns the internal events manager
setEventsManager()
```php
public function setEventsManager( ManagerInterface $eventsManager ): void;
```
Sets the events manager
## Contracts\Events\Manager
Interface
Canonical contract for Phalcon\Events\Manager.
- **`Phalcon\Contracts\Events\Manager`**
- [`Phalcon\Events\ManagerInterface`](/5.20/api/phalcon_events/#eventsmanagerinterface)
### Method Summary
Registers an event subscriber. The subscriber's getSubscribedEvents()
Returns whether priority ordering is currently enabled.
Attach a listener to the events manager.
Removes every registered subscriber and detaches each listener they
Toggle response collection on/off.
Detach a listener from the events manager.
Removes all listeners - globally or for a single event type.
Toggle priority ordering on/off.
Fires an event, notifying the active listeners.
Returns all listeners attached to the given event type.
Returns the responses recorded during the last fire (when collecting).
Returns the list of registered subscriber instances.
Check whether the given event type has any listeners.
Check whether the manager is currently collecting responses.
Returns true when the given handler is an object or callable.
Removes a previously registered subscriber. Detaches every listener the
### Constants
### Methods
addSubscriber()
```php
public function addSubscriber( Subscriber $subscriber ): void;
```
Registers an event subscriber. The subscriber's getSubscribedEvents()
map is parsed and each entry is attached through the regular listener
pipeline.
arePrioritiesEnabled()
```php
public function arePrioritiesEnabled(): bool;
```
Returns whether priority ordering is currently enabled.
attach()
```php
public function attach(
string $eventType,
mixed $handler,
int $priority = self::DEFAULT_PRIORITY
): void;
```
Attach a listener to the events manager.
clearSubscribers()
```php
public function clearSubscribers(): void;
```
Removes every registered subscriber and detaches each listener they
contributed. Listeners attached via attach() are untouched.
collectResponses()
```php
public function collectResponses( bool $collect ): void;
```
Toggle response collection on/off.
detach()
```php
public function detach(
string $eventType,
mixed $handler
): void;
```
Detach a listener from the events manager.
detachAll()
```php
public function detachAll( string|null $type = null ): void;
```
Removes all listeners - globally or for a single event type.
enablePriorities()
```php
public function enablePriorities( bool $enablePriorities ): void;
```
Toggle priority ordering on/off.
fire()
```php
public function fire(
string $eventType,
object $source,
mixed $data = null,
bool $cancelable = true
);
```
Fires an event, notifying the active listeners.
getListeners()
```php
public function getListeners( string $type ): array;
```
Returns all listeners attached to the given event type.
getResponses()
```php
public function getResponses(): array;
```
Returns the responses recorded during the last fire (when collecting).
getSubscribers()
```php
public function getSubscribers(): array;
```
Returns the list of registered subscriber instances.
hasListeners()
```php
public function hasListeners( string $type ): bool;
```
Check whether the given event type has any listeners.
isCollecting()
```php
public function isCollecting(): bool;
```
Check whether the manager is currently collecting responses.
isValidHandler()
```php
public function isValidHandler( mixed $handler ): bool;
```
Returns true when the given handler is an object or callable.
removeSubscriber()
```php
public function removeSubscriber( Subscriber $subscriber ): void;
```
Removes a previously registered subscriber. Detaches every listener the
subscriber declared via getSubscribedEvents(). Idempotent.
## Contracts\Events\Stoppable
Interface
Phalcon's local mirror of PSR-14 StoppableEventInterface. Identical shape;
not extended from the PSR interface because the Zephir extension cannot
reference Composer-loaded interfaces at build time. A separate bridge
package exposes a PSR-14 adapter.
- **`Phalcon\Contracts\Events\Stoppable`**
### Method Summary
Returns true when the event must stop propagating to subsequent
### Methods
isPropagationStopped()
```php
public function isPropagationStopped(): bool;
```
Returns true when the event must stop propagating to subsequent
listeners.
## Contracts\Events\Subscriber
Interface
Contract for event subscriber classes. A subscriber declares the events it
wants to listen to via a static map; Events\Manager parses the map and
attaches each entry as a regular listener.
Accepted value shapes per event key:
'event:name' => 'methodName'
'event:name' => ['methodName', priority]
'event:name' => [
['methodName1'],
['methodName2', priority],
]
Keys can be either a Phalcon event string (e.g. "db:beforeQuery") or a
fully qualified event class name.
Wildcard subscriptions: Phalcon's manager fires both the prefix queue and
the full-name queue (e.g. "db" is fired before "db:beforeQuery"). To
subscribe to every event of a component, use the prefix as the key:
'db' => 'onAnyDbEvent' // fires for db:beforeQuery, db:afterQuery, ...
- **`Phalcon\Contracts\Events\Subscriber`**
### Method Summary
Returns a map of event name => listener config. Called once per
### Methods
getSubscribedEvents()
```php
public static function getSubscribedEvents(): array;
```
Returns a map of event name => listener config. Called once per
Manager::addSubscriber() / removeSubscriber() call.
## Contracts\Filter\FilterTypes
Interface
Central registry of the array shapes used across the Filter namespace.
- **`Phalcon\Contracts\Filter\FilterTypes`**
`Phalcon\Filter\Validation\ValidatorInterface`
## Contracts\Filter\Sanitizer
Interface
The contract for sanitizers registered in Phalcon\Filter\Filter.
A sanitizer is an invokable object: it must expose a public `__invoke()`
method that receives the value to sanitize as its first parameter and
returns the sanitized value. Additional parameters, when a sanitizer
needs them (e.g. `regex`, `replace`), must be declared after the value
parameter; Phalcon\Filter\Filter::sanitize() forwards them in order.
`__invoke()` is intentionally not declared here: implementations type
their value parameter differently (`string` for text-only sanitizers,
untyped for coercing ones), and PHP parameter variance does not allow an
implementation to narrow a parameter declared by an interface.
A sanitizer operates on a single value. Array handling (one level of
recursion by default) is the responsibility of
Phalcon\Filter\Filter::sanitize(), not of the sanitizer.
@method mixed __invoke(mixed $value, mixed ...$params)
- **`Phalcon\Contracts\Filter\Sanitizer`**
## Contracts\Flash\Flash
Interface
Canonical contract for Phalcon\Flash messengers.
Note: `output()` and `clear()` are part of the concrete `Direct` / `Session`
API and are not declared on this contract; they are scheduled to be added in
the next major version.
- **`Phalcon\Contracts\Flash\Flash`**
- [`Phalcon\Flash\FlashInterface`](/5.20/api/phalcon_flash/#flashflashinterface)
### Method Summary
Shows a HTML error message
Outputs a message
Shows a HTML notice/information message
Shows a HTML success message
Shows a HTML warning message
### Methods
error()
```php
public function error( string $message ): string|null;
```
Shows a HTML error message
message()
```php
public function message(
string $type,
string $message
): string|null;
```
Outputs a message
Note: the shipped implementations (`Direct`, `Session`) accept
`string|array` for `$message`; this contract declares `string` and is
scheduled to be widened to `mixed` in the next major version. Delivery
semantics differ per implementation: `Direct::message()` renders and
emits the message immediately, while `Session::message()` stores the raw
message for output on a later request.
notice()
```php
public function notice( string $message ): string|null;
```
Shows a HTML notice/information message
success()
```php
public function success( string $message ): string|null;
```
Shows a HTML success message
warning()
```php
public function warning( string $message ): string|null;
```
Shows a HTML warning message
## Contracts\Flash\FlashTypes
Interface
Central registry of the array shapes used across the Flash namespace.
- **`Phalcon\Contracts\Flash\FlashTypes`**
## Contracts\Forms\FormsTypes
Interface
Central registry of the array shapes used across the Forms namespace.
- **`Phalcon\Contracts\Forms\FormsTypes`**
`Phalcon\Filter\Validation\ValidatorInterface` · `Phalcon\Forms\Element\ElementInterface` · `Phalcon\Forms\Form`
## Contracts\Forms\Schema
Interface
Contract for objects that supply a normalized list of form element
definitions. Implementations may source the definitions from a PHP array,
a JSON document, a YAML file, or any other format.
Each returned definition must be an associative array containing at least:
- 'type' (string) - element type key (e.g. 'text', 'select', 'checkgroup')
- 'name' (string) - the HTML name attribute value
Optional keys per definition:
- 'label' (string) - visible label text
- 'default' (mixed) - pre-populated default value
- 'attributes' (array) - additional HTML attributes
- 'filters' (array|string) - filter names applied on bind()
- 'validators' (array) - ValidatorInterface instances
- 'options' (array) - choices for select / checkgroup / radiogroup
- **`Phalcon\Contracts\Forms\Schema`**
### Method Summary
Returns an ordered list of normalized element definitions.
### Methods
```php
public function load(): array;
```
Returns an ordered list of normalized element definitions.
## Contracts\Front\FrontController
Interface
[_FrontController_][] affords an entry point into the outermost presentation
layer in any execution context (HTTP, CLI, etc.).
- **`Phalcon\Contracts\Front\FrontController`**
### Method Summary
Runs the front controller.
### Methods
run()
```php
public function run(): int;
```
Runs the front controller.
- Directives:
- Implementations MUST report success by returning an integer `0`.
- Implementations MUST report non-success by returning an integer
between `1` and `254` (inclusive).
- Implementations MUST gracefully handle all [_Throwable_][]s.
- Implementations MUST NOT [`exit()`][], [`die()`][], or otherwise
avoid returning.
- Notes:
- **The return value is intended as an exit status code.** Exit
status codes may be received initially by the in-process logic
that invoked `run()` (bootstrap scripts, test harnesses, etc.),
and may ultimately be received by a parent process (shell,
supervisor, init system, CI runner, monitoring tool, or similar)
via [`exit()`][]. Whether or not the exit status is consumed by the
calling code or parent process depends on the execution
environment: php-fpm and mod_php typically have no consumer,
whereas worker loops, supervised long-running processes, runtime
layers, and CI harnesses do.
- **"Success" and "non-success" are context-dependent.** In an HTTP
context, "success" typically means that the request was processed
and a response was emitted regardless of the HTTP status code,
whereas "non-success" may indicate that a [_Throwable_][] had to be
handled by the _FrontController_ itself. In a command line context,
"success" typically means that the command completed without
errors, whereas "non-success" may be one of several error
conditions (cf. the [`sysexits.h`][] conventions where applicable).
- **The exit status code `255` is reserved by PHP itself.** Cf.
[`exit()`][]: "Exit codes should be in the range 0 to 254, the exit
code 255 is reserved by PHP and should not be used."
- **Handle all possible exceptions.** The logic calling the front
controller should not have to deal with any exceptions bubbling up
from it.
- **Graceful handling means returning, not exiting.** A "graceful"
handler catches the [_Throwable_][], turns it into a non-success
exit status, and returns that status from `run()` rather than
calling [`exit()`][].
- **Return the exit status; leave termination to the caller.** The
value of an exit status code comes from letting the caller decide
what to do with it: a worker loop, queue worker, or test harness
needs `run()` to hand control back so it can continue, retry, or
assert on the result. An implementation that calls [`exit()`][]
inside `run()` prevents those uses, terminating the process before
the caller regains control.
## Contracts\Front\FrontTypeAliases
Interface
[_FrontTypeAliases_][] provides custom PHPStan types to aid static analysis.
- ```
front_exit_status_int int<0,254>
```
- An `int` exit status code: `0` for success, `1` to `254` for
non-success. The value `255` is reserved by PHP itself.
- **`Phalcon\Contracts\Front\FrontTypeAliases`**
## Contracts\Html\Helper\Input\SelectData
Interface
Interface for SELECT option data providers.
Return format: [value => label] for flat options;
[groupLabel => [value => label, ...]] for optgroups.
- **`Phalcon\Contracts\Html\Helper\Input\SelectData`**
`Phalcon\Contracts\Html\HtmlTypes`
### Method Summary
Returns the per-option attribute map.
### Methods
```php
public function getAttributes(): array;
```
Returns the per-option attribute map.
Format: [optionValue => [attrName => stringValue, ...]].
Implementations must return resolved string values; no escaping,
ordering, or rendering is performed here.
```php
public function getOptions(): array;
```
## Contracts\Html\HtmlTypes
Interface
Central registry of the array shapes used across the Html namespace.
Attribute values stay scalar here. The array member that PSR-13 allows for
link attributes lives in the Link registry instead, because the helper
pipeline concatenates and escapes every value as a string.
- **`Phalcon\Contracts\Html\HtmlTypes`**
`Closure`
## Contracts\Html\Link\LinkTypes
Interface
Central registry of the array shapes used across the Html\Link namespace.
PSR-13 states that a link attribute value is "a PHP primitive or an array of
PHP strings", so `link_attributes` keeps the array member that the plain
Html attribute shape drops.
- **`Phalcon\Contracts\Html\Link\LinkTypes`**
`Phalcon\Html\Link\Interfaces\LinkInterface`
## Contracts\Http\AttributeRequest
Interface
Extends the request contract with the native attribute bag.
`getAttributes()` already exists on the concrete `Phalcon\Http\Request`; this
interface exposes it as a contract without touching `RequestInterface`
(adding a method there would break userland implementers). It lets consumers
type against the attribute-bearing request without depending on the concrete.
- [`Phalcon\Http\RequestInterface`](/5.20/api/phalcon_http/#httprequestinterface)
- **`Phalcon\Contracts\Http\AttributeRequest`**
`Phalcon\Http\RequestInterface` · `Phalcon\Http\Request\Bag\AttributeBag`
### Method Summary
Returns the request attribute bag.
### Methods
getAttributes()
```php
public function getAttributes(): AttributeBag;
```
Returns the request attribute bag.
## Contracts\Http\HttpTypes
Interface
Central registry of the array shapes used across the Http namespace.
- **`Phalcon\Contracts\Http\HttpTypes`**
`Phalcon\Http\Cookie\CookieInterface` · `Phalcon\Http\Request\FileInterface`
## Contracts\Image\ImageTypes
Interface
Central registry of the array shapes used across the Image namespace.
This is a type registry, not a contract. It declares no members and must
not be implemented; it exists only so that every shape below has a single
definition, imported where it is needed with a phpstan-import-type tag
naming this interface as the source.
Alias names are prefixed with `image_` because PHPStan resolves imported
type names per file and has no namespacing for them: the prefix is what
keeps generic names such as `config` from clashing with an alias imported
from another namespace into the same file.
- **`Phalcon\Contracts\Image\ImageTypes`**
`Phalcon\Image\Adapter\AdapterInterface`
## Contracts\Logger\Adapter\Adapter
Interface
Canonical contract for Phalcon\Logger adapters.
- **`Phalcon\Contracts\Logger\Adapter\Adapter`**
- [`Phalcon\Logger\Adapter\AdapterInterface`](/5.20/api/phalcon_logger/#loggeradapteradapterinterface)
`Phalcon\Logger\Formatter\FormatterInterface` · `Phalcon\Logger\Item`
### Method Summary
Adds a message in the queue
Starts a transaction
Closes the logger
Commits the internal transaction
Returns the internal formatter
Returns the whether the logger is currently in an active transaction or
Processes the message in the adapter
Rollbacks the internal transaction
Sets the message formatter
### Methods
add()
```php
public function add( Item $item ): Adapter;
```
Adds a message in the queue
begin()
```php
public function begin(): Adapter;
```
Starts a transaction
close()
```php
public function close(): bool;
```
Closes the logger
commit()
```php
public function commit(): Adapter;
```
Commits the internal transaction
```php
public function getFormatter(): FormatterInterface;
```
Returns the internal formatter
inTransaction()
```php
public function inTransaction(): bool;
```
Returns the whether the logger is currently in an active transaction or
not
process()
```php
public function process( Item $item ): void;
```
Processes the message in the adapter
rollback()
```php
public function rollback(): Adapter;
```
Rollbacks the internal transaction
```php
public function setFormatter( FormatterInterface $formatter ): Adapter;
```
Sets the message formatter
## Contracts\Logger\Formatter\Formatter
Interface
Canonical contract for Phalcon\Logger formatters.
- **`Phalcon\Contracts\Logger\Formatter\Formatter`**
- [`Phalcon\Logger\Formatter\FormatterInterface`](/5.20/api/phalcon_logger/#loggerformatterformatterinterface)
`Phalcon\Logger\Item`
### Method Summary
Applies a format to an item
### Methods
```php
public function format( Item $item ): string;
```
Applies a format to an item
## Contracts\Logger\Logger
Interface
Canonical contract for Phalcon\Logger\Logger.
- **`Phalcon\Contracts\Logger\Logger`**
- [`Phalcon\Logger\LoggerInterface`](/5.20/api/phalcon_logger/#loggerloggerinterface)
`Phalcon\Contracts\Logger\Adapter\Adapter`
### Method Summary
Action must be taken immediately.
Critical conditions.
Detailed debug information.
System is unusable.
Runtime errors that do not require immediate action but should typically
Returns an adapter from the stack
Returns the adapter stack array
Returns the log level
Returns the name of the logger
Interesting events.
Logs with an arbitrary level.
Normal but significant events.
Extra-verbose diagnostic output.
Exceptional occurrences that are not errors.
### Methods
alert()
```php
public function alert(
string $message,
array $context = []
): void;
```
Action must be taken immediately.
Example: Entire website down, database unavailable, etc. This should
trigger the SMS alerts and wake you up.
critical()
```php
public function critical(
string $message,
array $context = []
): void;
```
Critical conditions.
Example: Application component unavailable, unexpected exception.
debug()
```php
public function debug(
string $message,
array $context = []
): void;
```
Detailed debug information.
emergency()
```php
public function emergency(
string $message,
array $context = []
): void;
```
System is unusable.
error()
```php
public function error(
string $message,
array $context = []
): void;
```
Runtime errors that do not require immediate action but should typically
be logged and monitored.
getAdapter()
```php
public function getAdapter( string $name ): Adapter;
```
Returns an adapter from the stack
getAdapters()
```php
public function getAdapters(): array;
```
Returns the adapter stack array
getLogLevel()
```php
public function getLogLevel(): int;
```
Returns the log level
getName()
```php
public function getName(): string;
```
Returns the name of the logger
info()
```php
public function info(
string $message,
array $context = []
): void;
```
Interesting events.
Example: User logs in, SQL logs.
log()
```php
public function log(
mixed $level,
string $message,
array $context = []
): void;
```
Logs with an arbitrary level.
An unknown level (a typo or an unmapped value) is not rejected; it maps
to the CUSTOM level and is logged, rather than raising an exception.
notice()
```php
public function notice(
string $message,
array $context = []
): void;
```
Normal but significant events.
trace()
```php
public function trace(
string $message,
array $context = []
): void;
```
Extra-verbose diagnostic output.
warning()
```php
public function warning(
string $message,
array $context = []
): void;
```
Exceptional occurrences that are not errors.
Example: Use of deprecated APIs, poor use of an API, undesirable things
that are not necessarily wrong.
## Contracts\Messages\Messages
Interface
Canonical contract for Phalcon\Messages\Messages.
The collection stores Phalcon\Messages\MessageInterface objects and is
iterated by integer position. An entry added under a string key through the
ArrayAccess interface stays reachable by that offset but is not visited
during iteration (`foreach`), which walks the integer sequence only.
@extends ArrayAccess<array-key, mixed>
@extends Iterator<int, MessageInterface>
- `\ArrayAccess`
- **`Phalcon\Contracts\Messages\Messages`** - extends `\ArrayAccess`, `\Countable`, `\Iterator`
`ArrayAccess` · `Countable` · `Iterator` · `Phalcon\Messages\MessageInterface`
### Method Summary
Appends a message to the collection
Appends an array of messages to the collection
Filters the message collection by field name
### Methods
appendMessage()
```php
public function appendMessage( MessageInterface $message ): void;
```
Appends a message to the collection
appendMessages()
```php
public function appendMessages( mixed $messages );
```
Appends an array of messages to the collection
filter()
```php
public function filter( string $fieldName ): array;
```
Filters the message collection by field name
## Contracts\Messages\MessagesTypes
Interface
Central registry of the array shapes used across the Messages namespace.
This is a type registry, not a contract. It declares no members and must
not be implemented; it exists only so that every shape below has a single
definition, imported where it is needed with a phpstan-import-type tag
naming this interface as the source.
Alias names are prefixed with `messages_` because PHPStan resolves imported
type names per file and has no namespacing for them: the prefix is what
keeps generic names such as `metadata` from clashing with an alias imported
from another namespace into the same file.
- **`Phalcon\Contracts\Messages\MessagesTypes`**
`Phalcon\Messages\MessageInterface`
## Contracts\Mvc\Dispatcher
Interface
Canonical contract for Phalcon\Mvc\Dispatcher.
- [`Phalcon\Contracts\Dispatcher\Dispatcher`](#contractsdispatcherdispatcher)
- **`Phalcon\Contracts\Mvc\Dispatcher`**
- [`Phalcon\Mvc\DispatcherInterface`](/5.20/api/phalcon_mvc/#mvcdispatcherinterface)
`Phalcon\Contracts\Dispatcher\Dispatcher` · `Phalcon\Mvc\ControllerInterface`
### Method Summary
Returns the active controller in the dispatcher
Gets last dispatched controller name
Returns the latest dispatched controller
Sets the controller name to be dispatched
Sets the default controller suffix
Sets the default controller name
### Methods
getActiveController()
```php
public function getActiveController(): ControllerInterface|null;
```
Returns the active controller in the dispatcher
getControllerName()
```php
public function getControllerName(): string;
```
Gets last dispatched controller name
getLastController()
```php
public function getLastController(): ControllerInterface|null;
```
Returns the latest dispatched controller
setControllerName()
```php
public function setControllerName( string $controllerName ): DispatcherContract;
```
Sets the controller name to be dispatched
setControllerSuffix()
```php
public function setControllerSuffix( string $controllerSuffix ): DispatcherContract;
```
Sets the default controller suffix
setDefaultController()
```php
public function setDefaultController( string $controllerName ): DispatcherContract;
```
Sets the default controller name
## Contracts\Mvc\Model\Relation\CacheKeyProvider
Interface
Interface for models that provide a custom unique key for the reusable
records cache in the Model Manager. Implement this interface when the
default object-identity based key (unique_key) does not produce stable
cache hits across multiple object instances that represent the same
database record.
- **`Phalcon\Contracts\Mvc\Model\Relation\CacheKeyProvider`**
### Method Summary
Returns a string that uniquely identifies this model instance for
### Methods
getUniqueKey()
```php
public function getUniqueKey(): string;
```
Returns a string that uniquely identifies this model instance for
use as the key in the reusable records cache.
## Contracts\Paginator\Adapter
Interface
Interface for Phalcon\Paginator adapters
- **`Phalcon\Contracts\Paginator\Adapter`**
- [`Phalcon\Paginator\Adapter\AdapterInterface`](/5.20/api/phalcon_paginator/#paginatoradapteradapterinterface)
### Method Summary
Get current rows limit
Returns a slice of the resultset to show in the pagination
Set the current page number
Set current rows limit
### Methods
getLimit()
```php
public function getLimit(): int;
```
Get current rows limit
paginate()
```php
public function paginate(): Repository;
```
Returns a slice of the resultset to show in the pagination
setCurrentPage()
```php
public function setCurrentPage( int $page ): Adapter;
```
Set the current page number
setLimit()
```php
public function setLimit( int $limit ): Adapter;
```
Set current rows limit
## Contracts\Paginator\PaginatorTypes
Interface
Central registry of the array shapes used across the Paginator namespace.
This is a type registry, not a contract. It declares no members and must
not be implemented; it exists only so that every shape below has a single
definition, imported where it is needed with a phpstan-import-type tag
naming this interface as the source.
Alias names are prefixed with `paginator_` because PHPStan resolves
imported type names per file and has no namespacing for them: the prefix
is what keeps generic names such as `config` from clashing with an alias
imported from another namespace into the same file.
- **`Phalcon\Contracts\Paginator\PaginatorTypes`**
`Phalcon\Mvc\Model\Query\Builder`
## Contracts\Paginator\Repository
Interface
Interface for the repository of current state
Phalcon\Paginator\AdapterInterface::paginate()
Two adapter dialects fill this repository:
- Offset adapters (Model, NativeArray, QueryBuilder) populate every
property as a sequential page number / item count.
- Cursor adapters (QueryBuilderCursor) reuse the same properties with a
different meaning: `getCurrent()`/`getNext()` carry keyset cursor values
rather than page numbers, and `getTotalItems()`, `getLast()` and
`getPrevious()` are not computed (they return 0).
- **`Phalcon\Contracts\Paginator\Repository`**
- [`Phalcon\Paginator\RepositoryInterface`](/5.20/api/phalcon_paginator/#paginatorrepositoryinterface)
### Method Summary
Gets the aliases for properties repository
Gets number of the current page
Gets number of the first page
Gets the items on the current page
Gets number of the last page
Gets current rows limit
Gets number of the next page
Gets number of the previous page
Gets the total number of items
Sets the aliases for properties repository
Sets values for properties of the repository
### Constants
### Methods
getAliases()
```php
public function getAliases(): array;
```
Gets the aliases for properties repository
getCurrent()
```php
public function getCurrent(): int;
```
Gets number of the current page
Cursor adapters store the cursor value used for the current page here
(0 on the first page), not a sequential page number.
getFirst()
```php
public function getFirst(): int;
```
Gets number of the first page
getItems()
```php
public function getItems(): mixed;
```
Gets the items on the current page
getLast()
```php
public function getLast(): int;
```
Gets number of the last page
Cursor adapters do not compute this and return 0.
getLimit()
```php
public function getLimit(): int;
```
Gets current rows limit
getNext()
```php
public function getNext(): int;
```
Gets number of the next page
Cursor adapters store the next cursor value here rather than a page
number; 0 means there is no next page.
getPrevious()
```php
public function getPrevious(): int;
```
Gets number of the previous page
Cursor adapters do not compute this and return 0.
getTotalItems()
```php
public function getTotalItems(): int;
```
Gets the total number of items
Cursor adapters do not compute this and return 0.
setAliases()
```php
public function setAliases( array $aliases ): Repository;
```
Sets the aliases for properties repository
setProperties()
```php
public function setProperties( array $properties ): Repository;
```
Sets values for properties of the repository
## Contracts\Queue\ConnectionFactory
Interface
Builds a Context: the entry point of every adapter.
- **`Phalcon\Contracts\Queue\ConnectionFactory`**
### Method Summary
Creates a context (a session/connection to the transport).
### Methods
createContext()
```php
public function createContext(): Context;
```
Creates a context (a session/connection to the transport).
## Contracts\Queue\Consumer
Interface
Receives messages from a single queue.
- **`Phalcon\Contracts\Queue\Consumer`**
### Method Summary
Acknowledges the message; the transport may then discard it.
Returns the queue this consumer reads from.
Receives a message, blocking up to timeout milliseconds (0 = block
Receives a message without blocking, or null when none is ready.
Rejects the message. When requeue is true the transport redelivers it.
### Methods
acknowledge()
```php
public function acknowledge( Message $message ): void;
```
Acknowledges the message; the transport may then discard it.
getQueue()
```php
public function getQueue(): Queue;
```
Returns the queue this consumer reads from.
receive()
```php
public function receive( int $timeout = 0 ): Message|null;
```
Receives a message, blocking up to timeout milliseconds (0 = block
until one is available). Returns null when none arrives in time.
receiveNoWait()
```php
public function receiveNoWait(): Message|null;
```
Receives a message without blocking, or null when none is ready.
reject()
```php
public function reject(
Message $message,
bool $requeue = false
): void;
```
Rejects the message. When requeue is true the transport redelivers it.
## Contracts\Queue\Context
Interface
A session with the transport. Factory for messages, destinations,
producers and consumers.
- **`Phalcon\Contracts\Queue\Context`**
### Method Summary
Closes the context and releases its resources.
Creates a consumer for the given destination.
Creates a message with an optional body, properties and headers.
Creates a producer.
Creates a queue destination by name.
Creates a subscription consumer for consuming from several queues.
Creates a temporary queue tied to the lifetime of the context.
Creates a topic destination by name.
Removes all messages from the given queue.
### Methods
close()
```php
public function close(): void;
```
Closes the context and releases its resources.
createConsumer()
```php
public function createConsumer( Destination $destination ): Consumer;
```
Creates a consumer for the given destination.
createMessage()
```php
public function createMessage(
string $body = "",
array $properties = [],
array $headers = []
): Message;
```
Creates a message with an optional body, properties and headers.
createProducer()
```php
public function createProducer(): Producer;
```
Creates a producer.
createQueue()
```php
public function createQueue( string $queueName ): Queue;
```
Creates a queue destination by name.
createSubscriptionConsumer()
```php
public function createSubscriptionConsumer(): SubscriptionConsumer;
```
Creates a subscription consumer for consuming from several queues.
createTemporaryQueue()
```php
public function createTemporaryQueue(): Queue;
```
Creates a temporary queue tied to the lifetime of the context.
createTopic()
```php
public function createTopic( string $topicName ): Topic;
```
Creates a topic destination by name.
purgeQueue()
```php
public function purgeQueue( Queue $queue ): void;
```
Removes all messages from the given queue.
## Contracts\Queue\Destination
Interface
Marker interface for a message destination: a Queue or a Topic.
- **`Phalcon\Contracts\Queue\Destination`**
- [`Phalcon\Contracts\Queue\Queue`](#contractsqueuequeue)
- [`Phalcon\Contracts\Queue\Topic`](#contractsqueuetopic)
## Contracts\Queue\Inspectable
Interface
Optional capability contract for a transport that can report statistics for
a queue (for example ready, delayed and buried job counts). Callers detect
support with `instanceof`.
The array returned by getStats() is ADAPTER-NATIVE: its keys and their
semantics are defined by the implementing adapter and are NOT guaranteed to
be uniform across adapters. It is an inspection surface, not a portable or
normalized schema. Each implementation documents the exact keys it returns.
- **`Phalcon\Contracts\Queue\Inspectable`**
### Method Summary
Returns statistics for the given queue.
### Methods
getStats()
```php
public function getStats( Queue $queue ): array;
```
Returns statistics for the given queue.
## Contracts\Queue\Message
Interface
A message exchanged through the transport. Carries a body, application
properties, transport headers and the standard messaging metadata.
- **`Phalcon\Contracts\Queue\Message`**
### Method Summary
Returns the message body.
Returns the correlation id used to correlate request/reply messages.
Returns a single header value, or the default when it is not set.
Returns all transport headers.
Returns the message id.
Returns all application properties.
Returns a single property value, or the default when it is not set.
Returns the reply-to destination name.
Returns the timestamp (in milliseconds) or null when it is not set.
Whether the message has been redelivered.
Sets the message body.
Sets the correlation id.
Sets a single transport header.
Replaces all transport headers.
Sets the message id.
Replaces all application properties.
Sets a single application property.
Marks the message as redelivered.
Sets the reply-to destination name.
Sets the timestamp (in milliseconds).
### Methods
getBody()
```php
public function getBody(): string;
```
Returns the message body.
getCorrelationId()
```php
public function getCorrelationId(): string|null;
```
Returns the correlation id used to correlate request/reply messages.
```php
public function getHeader(
string $name,
mixed $defaultValue = null
): mixed;
```
Returns a single header value, or the default when it is not set.
```php
public function getHeaders(): array;
```
Returns all transport headers.
getMessageId()
```php
public function getMessageId(): string|null;
```
Returns the message id.
getProperties()
```php
public function getProperties(): array;
```
Returns all application properties.
getProperty()
```php
public function getProperty(
string $name,
mixed $defaultValue = null
): mixed;
```
Returns a single property value, or the default when it is not set.
getReplyTo()
```php
public function getReplyTo(): string|null;
```
Returns the reply-to destination name.
getTimestamp()
```php
public function getTimestamp(): int|null;
```
Returns the timestamp (in milliseconds) or null when it is not set.
isRedelivered()
```php
public function isRedelivered(): bool;
```
Whether the message has been redelivered.
setBody()
```php
public function setBody( string $body ): void;
```
Sets the message body.
setCorrelationId()
```php
public function setCorrelationId( string $correlationId ): void;
```
Sets the correlation id.
```php
public function setHeader(
string $name,
mixed $value
): void;
```
Sets a single transport header.
```php
public function setHeaders( array $headers ): void;
```
Replaces all transport headers.
setMessageId()
```php
public function setMessageId( string $messageId ): void;
```
Sets the message id.
setProperties()
```php
public function setProperties( array $properties ): void;
```
Replaces all application properties.
setProperty()
```php
public function setProperty(
string $name,
mixed $value
): void;
```
Sets a single application property.
setRedelivered()
```php
public function setRedelivered( bool $redelivered ): void;
```
Marks the message as redelivered.
setReplyTo()
```php
public function setReplyTo( string $replyTo ): void;
```
Sets the reply-to destination name.
setTimestamp()
```php
public function setTimestamp( int $timestamp ): void;
```
Sets the timestamp (in milliseconds).
## Contracts\Queue\Processor
Interface
Processes a single message. The return value tells the consumer what to
do next: acknowledge, reject, or requeue.
The literal constant values are kept compatible with the wider interop
ecosystem.
- **`Phalcon\Contracts\Queue\Processor`**
### Method Summary
Processes the message and returns one of the ACK / REJECT / REQUEUE
### Constants
### Methods
process()
```php
public function process(
Message $message,
Context $context
): string|object;
```
Processes the message and returns one of the ACK / REJECT / REQUEUE
constants, or an object whose string form is one of those values.
## Contracts\Queue\Producer
Interface
Sends messages to a destination.
- **`Phalcon\Contracts\Queue\Producer`**
### Method Summary
Returns the delivery delay (in milliseconds) or null when not set.
Returns the message priority or null when not set.
Returns the time to live (in milliseconds) or null when not set.
Sends a message to the given destination.
Sets the delivery delay (in milliseconds). Null clears it.
Sets the message priority. Null clears it.
Sets the time to live (in milliseconds). Null clears it.
### Methods
getDeliveryDelay()
```php
public function getDeliveryDelay(): int|null;
```
Returns the delivery delay (in milliseconds) or null when not set.
getPriority()
```php
public function getPriority(): int|null;
```
Returns the message priority or null when not set.
getTimeToLive()
```php
public function getTimeToLive(): int|null;
```
Returns the time to live (in milliseconds) or null when not set.
send()
```php
public function send(
Destination $destination,
Message $message
): void;
```
Sends a message to the given destination.
setDeliveryDelay()
```php
public function setDeliveryDelay( mixed $deliveryDelay = null ): Producer;
```
Sets the delivery delay (in milliseconds). Null clears it.
setPriority()
```php
public function setPriority( mixed $priority = null ): Producer;
```
Sets the message priority. Null clears it.
setTimeToLive()
```php
public function setTimeToLive( mixed $timeToLive = null ): Producer;
```
Sets the time to live (in milliseconds). Null clears it.
## Contracts\Queue\Queue
Interface
A queue destination (point-to-point).
- [`Phalcon\Contracts\Queue\Destination`](#contractsqueuedestination)
- **`Phalcon\Contracts\Queue\Queue`**
### Method Summary
Returns the queue name.
### Methods
getQueueName()
```php
public function getQueueName(): string;
```
Returns the queue name.
## Contracts\Queue\QueueTypes
Interface
Central registry of the array shapes used across the Queue namespace.
- **`Phalcon\Contracts\Queue\QueueTypes`**
## Contracts\Queue\SubscriptionConsumer
Interface
Consumes from several queues at once, dispatching each message to the
callback registered for its consumer.
- **`Phalcon\Contracts\Queue\SubscriptionConsumer`**
### Method Summary
Starts consuming, blocking up to timeout milliseconds (0 = block
Subscribes a consumer; the callback receives each delivered message.
Removes a previously subscribed consumer.
Removes every subscribed consumer.
### Methods
consume()
```php
public function consume( int $timeout = 0 ): void;
```
Starts consuming, blocking up to timeout milliseconds (0 = block
until a message is available).
subscribe()
```php
public function subscribe(
Consumer $consumer,
callable $callback
): void;
```
Subscribes a consumer; the callback receives each delivered message.
unsubscribe()
```php
public function unsubscribe( Consumer $consumer ): void;
```
Removes a previously subscribed consumer.
unsubscribeAll()
```php
public function unsubscribeAll(): void;
```
Removes every subscribed consumer.
## Contracts\Queue\Topic
Interface
A topic destination (publish/subscribe).
- [`Phalcon\Contracts\Queue\Destination`](#contractsqueuedestination)
- **`Phalcon\Contracts\Queue\Topic`**
### Method Summary
Returns the topic name.
### Methods
getTopicName()
```php
public function getTopicName(): string;
```
Returns the topic name.
## Contracts\Queue\VisibilityAware
Interface
Marker contract for a consumer that supports a visibility timeout
(for example Beanstalk TTR or an SQS visibility timeout). Callers detect
support with `instanceof`. It carries no behavior and commits to no class
shape.
- **`Phalcon\Contracts\Queue\VisibilityAware`**
## Contracts\Session\SessionTypes
Interface
Central registry of the array shapes used across the Session namespace.
- **`Phalcon\Contracts\Session\SessionTypes`**
`Phalcon\Storage\Serializer\SerializerInterface`
## Contracts\Storage\StorageTypes
Interface
Central registry of the array shapes used across the Storage namespace.
- **`Phalcon\Contracts\Storage\StorageTypes`**
`Phalcon\Storage\Serializer\SerializerInterface` · `WeakReference`
## Contracts\Support\Collection
Interface
Canonical contract for Phalcon\Support\Collection.
@extends ArrayAccess<int|string, mixed>
@extends IteratorAggregate<int|string, mixed>
- `\ArrayAccess`
- **`Phalcon\Contracts\Support\Collection`** - extends `\ArrayAccess`, `\IteratorAggregate`
- [`Phalcon\Support\Collection\CollectionInterface`](/5.20/api/phalcon_support/#supportcollectioncollectioninterface)
`ArrayAccess` · `IteratorAggregate`
### Method Summary
Clears the internal collection.
Returns the values from a single property/method extracted from every
Invokes the callback for every item in the collection.
Returns a new collection of items for which the callback returns true.
Returns the first value in the collection or null when empty.
Returns an element from the collection.
Returns the keys (insensitive or not) of the collection.
Returns the configured runtime type guard, or null when not set.
Returns the values of the internal array.
Checks whether an element exists in the collection.
Initializes the internal array.
Returns true when the collection has no entries.
Returns the keys (insensitive or not) of the collection.
Returns the last value in the collection or null when empty.
Returns a new collection with the callback applied to every value.
Reduces the collection to a single value using the callback.
Removes the element from the collection.
Replaces the collection data with a new array, clearing first.
Stores an element in the collection.
Returns a new collection sorted by value, preserving keys.
Returns the collection as an array.
Returns the collection serialized as a JSON string.
Returns the values of the internal array.
Returns a new collection containing only the items whose
### Methods
__get()
```php
public function __get( string $element ): mixed;
```
__isset()
```php
public function __isset( string $element ): bool;
```
__set()
```php
public function __set(
string $element,
mixed $value
): void;
```
__unset()
```php
public function __unset( string $element ): void;
```
clear()
```php
public function clear(): void;
```
Clears the internal collection.
column()
```php
public function column( string $propertyOrMethod ): array;
```
Returns the values from a single property/method extracted from every
item in the collection, keyed by the original collection key.
each()
```php
public function each( callable $callback ): static;
```
Invokes the callback for every item in the collection.
filter()
```php
public function filter( callable $callback ): static;
```
Returns a new collection of items for which the callback returns true.
first()
```php
public function first(): mixed;
```
Returns the first value in the collection or null when empty.
get()
```php
public function get(
string $element,
mixed $defaultValue = null,
string|null $cast = null
): mixed;
```
Returns an element from the collection.
getKeys()
```php
public function getKeys( bool $insensitive = true ): array;
```
Returns the keys (insensitive or not) of the collection.
getType()
```php
public function getType(): string|null;
```
Returns the configured runtime type guard, or null when not set.
getValues()
```php
public function getValues(): array;
```
Returns the values of the internal array.
has()
```php
public function has( string $element ): bool;
```
Checks whether an element exists in the collection.
init()
```php
public function init( array $data = [] ): void;
```
Initializes the internal array.
isEmpty()
```php
public function isEmpty(): bool;
```
Returns true when the collection has no entries.
keys()
```php
public function keys( bool $insensitive = true ): array;
```
Returns the keys (insensitive or not) of the collection.
last()
```php
public function last(): mixed;
```
Returns the last value in the collection or null when empty.
map()
```php
public function map( callable $callback ): static;
```
Returns a new collection with the callback applied to every value.
reduce()
```php
public function reduce(
callable $callback,
mixed $initial = null
): mixed;
```
Reduces the collection to a single value using the callback.
remove()
```php
public function remove( string $element ): void;
```
Removes the element from the collection.
replace()
```php
public function replace( array $data ): void;
```
Replaces the collection data with a new array, clearing first.
set()
```php
public function set(
string $element,
mixed $value
): void;
```
Stores an element in the collection.
sort()
```php
public function sort(
callable|null $callback = null,
int $order = 4
): static;
```
Returns a new collection sorted by value, preserving keys.
toArray()
```php
public function toArray(): array;
```
Returns the collection as an array.
toJson()
```php
public function toJson( int $options = 4194383 ): string;
```
Returns the collection serialized as a JSON string.
values()
```php
public function values(): array;
```
Returns the values of the internal array.
where()
```php
public function where(
string $propertyOrMethod,
mixed $value
): static;
```
Returns a new collection containing only the items whose
`propertyOrMethod` strictly equals `$value`.
## Contracts\Support\Debug\Renderer
Interface
Canonical contract for Phalcon\Support\Debug renderers. Turns an
ExceptionReport into output.
- [`Phalcon\Contracts\Support\Debug\TemplateAware`](#contractssupportdebugtemplateaware)
- **`Phalcon\Contracts\Support\Debug\Renderer`**
`Phalcon\Support\Debug\Report\ExceptionReport`
### Method Summary
Returns the CSS sources block for the given base URI.
Returns the JavaScript sources block for the given base URI.
Returns the framework version block.
Renders the report.
### Methods
getCssSources()
```php
public function getCssSources( string $uri ): string;
```
Returns the CSS sources block for the given base URI.
getJsSources()
```php
public function getJsSources( string $uri ): string;
```
Returns the JavaScript sources block for the given base URI.
getVersion()
```php
public function getVersion(): string;
```
Returns the framework version block.
render()
```php
public function render( ExceptionReport $report ): string;
```
Renders the report.
## Contracts\Support\Debug\TemplateAware
Interface
Canonical contract for components that render through named, overridable
template strings.
- **`Phalcon\Contracts\Support\Debug\TemplateAware`**
- [`Phalcon\Contracts\Support\Debug\Renderer`](#contractssupportdebugrenderer)
### Method Summary
Returns the template for the given name (override if set, default
Overrides the template for the given name.
### Methods
getTemplate()
```php
public function getTemplate( string $name ): string;
```
Returns the template for the given name (override if set, default
otherwise).
setTemplate()
```php
public function setTemplate(
string $name,
string $template
): static;
```
Overrides the template for the given name.
## Contracts\Support\SupportTypes
Interface
Central registry of the array shapes used across the Support namespace.
- **`Phalcon\Contracts\Support\SupportTypes`**
## Contracts\Translate\TranslateTypes
Interface
Central registry of the array shapes used across the Translate namespace.
- **`Phalcon\Contracts\Translate\TranslateTypes`**
## Contracts\View\Renderer
Interface
Renders a template with the given data and returns the result as a string.
A neutral abstraction: it is not tied to MVC, to ADR, or to any particular
template engine. `Phalcon\Mvc\View\Simple` satisfies it out of the box, and
userland engines only need this one method to become a drop-in renderer.
- **`Phalcon\Contracts\View\Renderer`**
### Method Summary
Renders the template and returns the output.
### Methods
render()
```php
public function render(
string $path,
array $params = []
): string;
```
Renders the template and returns the output.
Source: https://docs.phalcon.io/5.20/api/phalcon_contracts/index.mdx