Phalcon Contracts

Contracts\ADR\ADRTypes

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.

Contracts\ADR\Action

Marker contract for a per-endpoint Action. An Action is a Handler: __invoke(request): response.

Contracts\ADR\Application

Handles a request end to end: routes it, dispatches the Action and returns the response, routing any error through the error responder.

Uses Phalcon\Contracts\Http\AttributeRequest · Phalcon\Http\ResponseInterface

Method Summary

Methods

handle()

public function handle( AttributeRequest $request ): ResponseInterface;

Contracts\ADR\Dispatcher

Resolves an Action by class name, builds the middleware pipeline around it and runs it to produce a response.

Uses Phalcon\Contracts\Http\AttributeRequest · Phalcon\Http\ResponseInterface

Method Summary

Methods

dispatch()

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

Contracts\ADR\Emitter\Emitter

Sends a response to the client. Called by the front controller only.

Uses Phalcon\Http\ResponseInterface

Method Summary

Methods

emit()

public function emit( ResponseInterface $response ): void;

Contracts\ADR\Exceptions\ADRThrowable

Base throwable contract for the ADR component. Every ADR exception implements it, so callers can catch all ADR errors with a single type.

Contracts\ADR\Handler

Receives the request and returns a response. The terminal handler in the pipeline is the Action.

Uses Phalcon\Contracts\Http\AttributeRequest · Phalcon\Http\ResponseInterface

Method Summary

Methods

__invoke()

public function __invoke( AttributeRequest $request ): ResponseInterface;

Contracts\ADR\Middleware

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.

Uses Phalcon\Contracts\Http\AttributeRequest · Phalcon\Http\ResponseInterface

Method Summary

Methods

__invoke()

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

Contracts\ADR\Payload\Payload

Contract for the immutable payload produced by the domain layer.

Uses Throwable

Method Summary

Methods

getException()

public function getException(): Throwable|null;

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

getExtras()

public function getExtras(): mixed;

Gets the arbitrary extra domain information.

getInput()

public function getInput(): mixed;

Gets the domain input.

getMessages()

public function getMessages(): mixed;

Gets the domain messages.

getResult()

public function getResult(): mixed;

Gets the domain result.

getStatus()

public function getStatus(): mixed;

Gets the payload status.

withException()

public function withException( Throwable $exception ): Payload;

Returns a copy of the payload with the given exception.

withExtras()

public function withExtras( mixed $extras ): Payload;

Returns a copy of the payload with the given extras.

withInput()

public function withInput( mixed $input ): Payload;

Returns a copy of the payload with the given input.

withMessages()

public function withMessages( mixed $messages ): Payload;

Returns a copy of the payload with the given messages.

withResult()

public function withResult( mixed $result ): Payload;

Returns a copy of the payload with the given result.

withStatus()

public function withStatus( mixed $status ): Payload;

Returns a copy of the payload with the given status.

Contracts\ADR\Responder\Formatter\Formatter

Renders a payload into a string for a given content type.

Uses Phalcon\Contracts\ADR\Payload\Payload

Method Summary

Methods

accepts()

public function accepts( string $acceptHeader ): bool;

Whether this formatter can satisfy the given Accept header.

contentType()

public function contentType(): string;

The content type this formatter produces.

format()

public function format( Payload $payload ): string;

Renders the payload into a string.

Contracts\ADR\Responder\Responder

Turns a payload into an HTTP response. The only layer that speaks HTTP.

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

Method Summary

Methods

__invoke()

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

Contracts\ADR\Router\AttributeFilter

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.

Uses Phalcon\Contracts\ADR\ADRTypes

Method Summary

Methods

filter()

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

Contracts\ADR\Router\Router

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.

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

Method Summary

Methods

candidatesFor()

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

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

classFor()

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()

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

methodFor()

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()

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()

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()

public function setBaseNamespace( string $baseNamespace ): Router;

setMiddlewareMap()

public function setMiddlewareMap( array $middlewareMap ): Router;

setWordSeparator()

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

The result of matching a request against the router: the Action class, the extracted route attributes, the route’s middleware and its optional name.

Uses Phalcon\Contracts\ADR\ADRTypes

Method Summary

Methods

getAction()

public function getAction(): string;

getAttributes()

public function getAttributes(): array;

getMiddleware()

public function getMiddleware(): array;

getName()

public function getName(): string|null;

Contracts\Acl\Adapter\Adapter

Canonical contract for Phalcon\Acl adapters

Uses Phalcon\Acl\ComponentInterface · Phalcon\Acl\RoleInterface

Method Summary

Methods

addComponent()

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()

public function addComponentAccess(
    string $componentName,
    mixed $accessList
): bool;

Adds access to components

addInherit()

public function addInherit(
    string $roleName,
    mixed $roleToInherits
): bool;

Do a role inherit from another existing role

addRole()

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()

public function allow(
    string $roleName,
    string $componentName,
    mixed $access,
    mixed $func = null
): void;

Allow access to a role on a component

deny()

public function deny(
    string $roleName,
    string $componentName,
    mixed $access,
    mixed $func = null
): void;

Deny access to a role on a component

dropComponentAccess()

public function dropComponentAccess(
    string $componentName,
    mixed $accessList
): void;

Removes access from a component

getActiveAccess()

public function getActiveAccess(): null|string;

Returns the access which the list is checking if some role can access it

getActiveComponent()

public function getActiveComponent(): null|string;

Returns the component which the list is checking if some role can access it

getActiveRole()

public function getActiveRole(): null|string;

Returns the role which the list is checking if it’s allowed to certain component/access

getComponents()

public function getComponents(): ComponentInterface[];

Return an array with every component registered in the list

getDefaultAction()

public function getDefaultAction(): int;

Returns the default ACL access level

getInheritedRoles()

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()

public function getNoArgumentsDefaultAction(): int;

Returns the default ACL access level for no arguments provided in isAllowed action if there exists func for accessKey

getRoles()

public function getRoles(): RoleInterface[];

Return an array with every role registered in the list

isAllowed()

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()

public function isComponent( string $componentName ): bool;

Check whether component exist in the components list

isRole()

public function isRole( string $roleName ): bool;

Check whether role exist in the roles list

setDefaultAction()

public function setDefaultAction( int $defaultAccess ): void;

Sets the default access level (Phalcon\Acl\Enum::ALLOW or Phalcon\Acl\Enum::DENY)

setNoArgumentsDefaultAction()

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

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.

Method Summary

Methods

load()

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()

public function save(): bool;

Persists the current policy snapshot to the backing store.

Contracts\Acl\Component

Canonical contract for an ACL component entity.

Method Summary

Methods

__toString()

public function __toString(): string;

Magic method __toString

getDescription()

public function getDescription(): string|null;

Returns component description

getName()

public function getName(): string;

Returns the component name

Contracts\Acl\ComponentAware

Canonical contract for ACL component-aware objects.

Method Summary

Methods

getComponentName()

public function getComponentName(): string;

Returns component name

Contracts\Acl\Role

Canonical contract for an ACL role entity.

Method Summary

Methods

__toString()

public function __toString(): string;

Magic method __toString

getDescription()

public function getDescription(): string|null;

Returns role description

getName()

public function getName(): string;

Returns the role name

Contracts\Acl\RoleAware

Canonical contract for ACL role-aware objects.

Method Summary

Methods

getRoleName()

public function getRoleName(): string;

Returns role name

Contracts\Application\ApplicationTypes

Central registry of the array shapes used across the Application namespace.

Uses Closure

Contracts\Assets\Asset

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.

Method Summary

Methods

getAssetKey()

public function getAssetKey(): string;

Gets the asset’s key.

getAttributes()

public function getAttributes(): array|null;

Gets extra HTML attributes.

getFilter()

public function getFilter(): bool;

Gets if the asset must be filtered or not.

getType()

public function getType(): string;

Gets the asset’s type.

setAttributes()

public function setAttributes( array $attributes ): Asset;

Sets extra HTML attributes.

setFilter()

public function setFilter( bool $filter ): Asset;

Sets if the asset must be filtered or not.

setType()

public function setType( string $type ): Asset;

Sets the asset’s type.

Contracts\Assets\Filter

Canonical contract for Phalcon\Assets filters (Cssmin, Jsmin, None, and custom user filters).

Method Summary

Methods

filter()

public function filter( string $content ): string;

Filters the content returning a string with the filtered content

Contracts\Auth\Access\Access

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.

Uses Phalcon\Contracts\Auth\Guard\Guard

Method Summary

Methods

getExceptActions()

public function getExceptActions(): array;

getOnlyActions()

public function getOnlyActions(): array;

isAllowed()

public function isAllowed(
    Guard $guard,
    string $actionName,
    array $context = []
): bool;

Whether the identity behind the guard may run the action.

redirectTo()

public function redirectTo(): array|null;

setExceptActions()

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()

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

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().

Uses Phalcon\Contracts\Auth\AuthUser · Phalcon\Contracts\Encryption\Security\Security

Method Summary

Methods

fromOptions()

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()

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()

public function retrieveById( mixed $id ): AuthUser|null;

Find a user by their unique identifier.

validateCredentials()

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

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.

Method Summary

Methods

getModel()

public function getModel(): string|null;

Returns the user-model class name to hydrate, if configured.

Contracts\Auth\Adapter\RememberAdapter

Capability extension implemented by adapters that support remember-me.

Uses Phalcon\Contracts\Auth\AuthUser · Phalcon\Contracts\Auth\RememberToken

Method Summary

Methods

createRememberToken()

public function createRememberToken( AuthUser $user ): RememberToken;

Create and persist a new remember token for the user.

retrieveByToken()

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

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.

Method Summary

Methods

createRememberToken()

public function createRememberToken(
    string $token,
    string|null $userAgent = null
): RememberToken;

Persists a new remember token for the user.

getRememberToken()

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

Implemented by user models that can be authenticated.

Method Summary

Methods

getAuthIdentifier()

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()

public function getAuthPassword(): string;

Returns the hashed password for the authenticatable user.

Contracts\Auth\Guard\BasicAuth

Uses Phalcon\Contracts\Auth\AuthUser

Method Summary

Methods

basic()

public function basic(
    string $field = "email",
    array $extraConditions = []
): bool;

Authenticate against HTTP Basic credentials. Returns true on success.

onceBasic()

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

Uses Phalcon\Contracts\Auth\Adapter\Adapter · Phalcon\Contracts\Auth\AuthUser · Phalcon\Contracts\Container\Service\Collection · Phalcon\Di\DiInterface

Method Summary

Methods

check()

public function check(): bool;

Whether the current request is authenticated.

fromOptions()

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()

public function getLastUserAttempted(): AuthUser|null;

Returns the last user the guard tried to authenticate during this request, regardless of success.

guest()

public function guest(): bool;

Whether the current request is unauthenticated.

hasUser()

public function hasUser(): bool;

Whether the guard currently holds a resolved user.

id()

public function id(): int|string|null;

Returns the authenticated user’s identifier, or null when no authenticated user is present.

setUser()

public function setUser( AuthUser $user ): static;

Sets the current user explicitly. Returns $this for fluent chaining.

user()

public function user(): AuthUser|null;

Returns the resolved user for the current request, or null.

validate()

public function validate( array $credentials = [] ): bool;

Validates the given credentials without logging in.

Contracts\Auth\Guard\GuardConfig

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.

Contracts\Auth\Guard\GuardStateful

Implemented by guards backed by persistent state (sessions/cookies).

Uses Phalcon\Contracts\Auth\Adapter\Adapter · Phalcon\Contracts\Auth\AuthUser

Method Summary

Methods

attempt()

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()

public function login(
    AuthUser $user,
    bool $remember = false
): void;

loginById()

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()

public function logout(): void;

viaRemember()

public function viaRemember(): bool;

Contracts\Auth\Manager

Uses Phalcon\Auth\Exception · Phalcon\Contracts\Auth\Access\Access · Phalcon\Contracts\Auth\Adapter\Adapter · Phalcon\Contracts\Auth\Guard\Guard

Method Summary

Methods

access()

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()

public function addAccessList( array $accessList ): self;

addGuard()

public function addGuard(
    string $nameGuard,
    Guard $guard,
    bool $isDefault = false
): self;

attempt()

public function attempt(
    array $credentials = [],
    bool $remember = false
): bool;

check()

public function check(): bool;

Whether the default guard reports the current request as authenticated.

except()

public function except( string $actions ): self;

Restricts the active access gate to skip the listed action names.

getAccess()

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()

public function getAccessList(): array;

getDefaultGuard()

public function getDefaultGuard(): Guard|null;

getGuards()

public function getGuards(): array;

guard()

public function guard( string|null $name = null ): Guard;

Returns the named guard, or the default guard when $name is null.

id()

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()

public function logout(): void;

Logs the current user out via the default guard.

only()

public function only( string $actions ): self;

Restricts the active access gate to apply only to the listed action names.

setAccess()

public function setAccess( Access $access ): self;

setDefaultGuard()

public function setDefaultGuard( Guard $guard ): self;

user()

public function user(): AuthUser|null;

Returns the resolved user from the default guard, or null.

validate()

public function validate( array $credentials = [] ): bool;

Validates the given credentials against the default guard without logging in.

Contracts\Auth\RememberToken

A persisted remember-me token row.

Method Summary

Methods

delete()

public function delete(): bool;

Deletes the token from storage.

getToken()

public function getToken(): string;

Returns the token value stored for this remember entry.

getUserAgent()

public function getUserAgent(): string|null;

Returns the user agent associated with this token, if any.

Contracts\Autoload\AutoloadTypes

Central registry of the array shapes used across the Autoload namespace.

Contracts\Cache\Cache

Canonical contract for Phalcon\Cache\Cache.

Uses DateInterval · Phalcon\Cache\Exception\InvalidArgumentException

Method Summary

Methods

clear()

public function clear(): bool;

Wipes clean the entire cache’s keys.

delete()

public function delete( string $key ): bool;

Delete an item from the cache by its unique key.

deleteMultiple()

public function deleteMultiple( mixed $keys ): bool;

Deletes multiple cache items in a single operation.

get()

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

Fetches a value from the cache.

getMultiple()

public function getMultiple(
    mixed $keys,
    mixed $defaultValue = null
);

Obtains multiple cache items by their unique keys.

has()

public function has( string $key ): bool;

Determines whether an item is present in the cache.

set()

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()

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

Central registry of the array shapes used across the Cli namespace.

Uses Phalcon\Cli\Router\Route

Contracts\Cli\Dispatcher

Canonical contract for Phalcon\Cli\Dispatcher.

Uses Phalcon\Cli\TaskInterface · Phalcon\Contracts\Dispatcher\Dispatcher

Method Summary

Methods

getActiveTask()

public function getActiveTask(): TaskInterface;

Returns the active task in the dispatcher

getLastTask()

public function getLastTask(): TaskInterface;

Returns the latest dispatched controller

getOptions()

public function getOptions(): array;

Get dispatched options

getTaskName()

public function getTaskName(): string;

Gets last dispatched task name

getTaskSuffix()

public function getTaskSuffix(): string;

Gets default task suffix

setDefaultTask()

public function setDefaultTask( string $taskName ): void;

Sets the default task name

setOptions()

public function setOptions( array $options ): void;

Set the options to be dispatched

setTaskName()

public function setTaskName( string $taskName ): void;

Sets the task name to be dispatched

setTaskSuffix()

public function setTaskSuffix( string $taskSuffix ): void;

Sets the default task suffix

Contracts\Container\Ioc\IocContainer

[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.

Method Summary

Methods

getService()

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()

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

[IocContainerFactory][] affords obtaining a new instance of [IocContainer][].

Method Summary

Methods

newContainer()

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

[IocThrowable][] extends [Throwable][] to mark an [Exception][] as IOC-related.

It adds no class members.

Uses Throwable

Contracts\Container\Ioc\IocTypeAliases

Contracts\Container\Resolver\ReflectionMethodResolver

Uses Phalcon\Contracts\Container\Ioc\IocContainer · ReflectionMethod

Method Summary

Methods

resolveMethod()

public function resolveMethod(
    IocContainer $ioc,
    ReflectionMethod $method,
    object $instance
): void;

Contracts\Container\Resolver\ReflectionParameterResolver

Uses Phalcon\Contracts\Container\Ioc\IocContainer · ReflectionParameter

Method Summary

Methods

resolveParameter()

public function resolveParameter(
    IocContainer $ioc,
    ReflectionParameter $parameter
): mixed;

Contracts\Container\Resolver\Resolvable

Uses Phalcon\Contracts\Container\Ioc\IocContainer

Method Summary

Methods

resolve()

public function resolve( IocContainer $ioc ): mixed;

Contracts\Container\Resolver\ResolverService

Uses Phalcon\Contracts\Container\Ioc\IocContainer · ReflectionMethod · ReflectionParameter · ReflectionType

Method Summary

Methods

isResolvableClass()

public function isResolvableClass( string $className ): bool;

resolveCall()

public function resolveCall(
    IocContainer $ioc,
    callable $callableObject,
    array $arguments
): mixed;

resolveClass()

public function resolveClass(
    IocContainer $ioc,
    string $className,
    array $arguments
): object;

resolveMethod()

public function resolveMethod(
    IocContainer $ioc,
    ReflectionMethod $method,
    object $instance
): void;

resolveParameters()

public function resolveParameters(
    IocContainer $ioc,
    array $parameters,
    array $arguments
): array;

resolveType()

public function resolveType(
    IocContainer $ioc,
    ReflectionType $type
): mixed;

Contracts\Container\Resolver\ResolverThrowable

Uses Throwable

Contracts\Container\Service\Collection

Uses Closure · Phalcon\Container\Definition\ServiceDefinition · Phalcon\Container\Resolver\Resolver · Phalcon\Contracts\Container\Ioc\IocContainer

Method Summary

Methods

bind()

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

callableGet()

public function callableGet( string $name ): Closure;

callableNew()

public function callableNew( string $name ): Closure;

extend()

public function extend(
    string $name,
    callable $callableObject
): void;

get()

public function get( string $name ): mixed;

getAlias()

public function getAlias( string $name ): string;

getByTag()

public function getByTag( string $tag ): array;

getDefinition()

public function getDefinition( string $name ): ServiceDefinition;

getInstance()

public function getInstance( string $name ): object;

getParameter()

public function getParameter( string $name ): mixed;

getResolver()

public function getResolver(): Resolver;

has()

public function has( string $name ): bool;

hasAlias()

public function hasAlias( string $name ): bool;

hasDefinition()

public function hasDefinition( string $name ): bool;

hasInstance()

public function hasInstance( string $name ): bool;

hasParameter()

public function hasParameter( string $name ): bool;

isAutowireEnabled()

public function isAutowireEnabled(): bool;

new()

public function new( string $name ): mixed;

newDefinition()

public function newDefinition( string $name ): ServiceDefinition;

set()

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

setAlias()

public function setAlias(
    string $name,
    string $alias
): static;

setAutowire()

public function setAutowire( bool $enabled ): static;

setDefinition()

public function setDefinition(
    string $name,
    ServiceDefinition $definition
): static;

setInstance()

public function setInstance(
    string $name,
    object $instance,
    string $lifetime
): static;

setParameter()

public function setParameter(
    string $name,
    mixed $value
): static;

unsetAlias()

public function unsetAlias( string $name ): void;

unsetDefinition()

public function unsetDefinition( string $name ): void;

unsetInstance()

public function unsetInstance( string $name ): void;

unsetInstances()

public function unsetInstances( string $lifetime ): void;

unsetParameter()

public function unsetParameter( string $name ): void;

Contracts\Container\Service\Definition

Uses Phalcon\Contracts\Container\Ioc\IocContainer

Method Summary

Methods

addExtender()

public function addExtender( callable $extender ): static;

buildService()

public function buildService( IocContainer $ioc ): object;

getClass()

public function getClass(): string;

getExtenders()

public function getExtenders(): array;

getFactory()

public function getFactory(): callable;

getLifetime()

public function getLifetime(): string;

getServiceName()

public function getServiceName(): string;

hasClass()

public function hasClass(): bool;

hasExtenders()

public function hasExtenders(): bool;

hasFactory()

public function hasFactory(): bool;

setClass()

public function setClass( string $className ): static;

setExtenders()

public function setExtenders( array $extenders ): static;

setFactory()

public function setFactory( callable $factory ): static;

setLifetime()

public function setLifetime( string $lifetime ): static;

unsetClass()

public function unsetClass(): static;

unsetExtenders()

public function unsetExtenders(): static;

unsetFactory()

public function unsetFactory(): static;

Contracts\Container\Service\Enumerable

Optional capability contract for a container that can report the services it holds. Callers detect support with instanceof.

Deliberately separate from Collection rather than a member of it. Collection mirrors the service-interop surface, which has no notion of enumeration, and adding a member to a published interface breaks every implementor. A second, narrow interface states the capability without touching the first.

Carries no interop attribution because nothing here is copied: enumeration is Phalcon’s own addition.

Tooling that reports on a container type-hints this instead of the concrete Container, so it depends on a published contract rather than on an implementation detail that is free to change.

Method Summary

Methods

getServiceNames()

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

Method Summary

Methods

provide()

public function provide( Collection $services ): void;

Contracts\Container\Service\Throwable

Uses Throwable

Contracts\Db\Adapter\Adapter

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

Uses Phalcon\Db\ColumnInterface · Phalcon\Db\DialectInterface · Phalcon\Db\IndexInterface · Phalcon\Db\RawValue · Phalcon\Db\ReferenceInterface · Phalcon\Db\ResultInterface

Method Summary

Methods

addColumn()

public function addColumn(
    string $tableName,
    string $schemaName,
    ColumnInterface $column
): bool;

Adds a column to a table

addForeignKey()

public function addForeignKey(
    string $tableName,
    string $schemaName,
    ReferenceInterface $reference
): bool;

Adds a foreign key to a table

addIndex()

public function addIndex(
    string $tableName,
    string $schemaName,
    IndexInterface $index
): bool;

Adds an index to a table

addPrimaryKey()

public function addPrimaryKey(
    string $tableName,
    string $schemaName,
    IndexInterface $index
): bool;

Adds a primary key to a table

affectedRows()

public function affectedRows(): int;

Returns the number of affected rows by the last INSERT/UPDATE/DELETE reported by the database system

begin()

public function begin( bool $nesting = true ): bool;

Starts a transaction in the connection

close()

public function close(): void;

Closes active connection returning success. Phalcon automatically closes and destroys active connections within Phalcon\Db\Pool

commit()

public function commit( bool $nesting = true ): bool;

Commits the active transaction in the connection

connect()

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()

public function createSavepoint( string $name ): bool;

Creates a new savepoint

createTable()

public function createTable(
    string $tableName,
    string $schemaName,
    array $definition
): bool;

Creates a table

createView()

public function createView(
    string $viewName,
    array $definition,
    string|null $schemaName = null
): bool;

Creates a view

delete()

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()

public function describeColumns(
    string $table,
    string|null $schema = null
): ColumnInterface[];

Returns an array of Phalcon\Db\Column objects describing a table

describeIndexes()

public function describeIndexes(
    string $table,
    string|null $schema = null
): IndexInterface[];

Lists table indexes

describeReferences()

public function describeReferences(
    string $table,
    string|null $schema = null
): ReferenceInterface[];

Lists table references

dropColumn()

public function dropColumn(
    string $tableName,
    string $schemaName,
    string $columnName
): bool;

Drops a column from a table

dropForeignKey()

public function dropForeignKey(
    string $tableName,
    string $schemaName,
    string $referenceName
): bool;

Drops a foreign key from a table

dropIndex()

public function dropIndex(
    string $tableName,
    string $schemaName,
    string $indexName
): bool;

Drop an index from a table

dropPrimaryKey()

public function dropPrimaryKey(
    string $tableName,
    string $schemaName
): bool;

Drops primary key from a table

dropTable()

public function dropTable(
    string $tableName,
    string|null $schemaName = null,
    bool $ifExists = true
): bool;

Drops a table from a schema/database

dropView()

public function dropView(
    string $viewName,
    string|null $schemaName = null,
    bool $ifExists = true
): bool;

Drops a view

escapeIdentifier()

public function escapeIdentifier( mixed $identifier ): string;

Escapes a column/table/schema name

escapeString()

public function escapeString( string $str ): string;

Escapes a value to avoid SQL injections

execute()

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()

public function fetchAll(
    string $sqlQuery,
    int $fetchMode = 2,
    array $bindParams = [],
    array $bindTypes = []
): array;

Dumps the complete result of a query into an array

fetchColumn()

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

// 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()

public function fetchOne(
    string $sqlQuery,
    int $fetchMode = 2,
    array $bindParams = [],
    array $bindTypes = []
): array;

Returns the first row in a SQL query result

forUpdate()

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()

public function getColumnDefinition( ColumnInterface $column ): string;

Returns the SQL column definition from a column

getColumnList()

public function getColumnList( mixed $columnList ): string;

Gets a list of columns

getConnectionId()

public function getConnectionId(): int;

Gets the active connection unique identifier

getDefaultIdValue()

public function getDefaultIdValue(): RawValue;

Return the default identity value to insert in an identity column

getDefaultValue()

public function getDefaultValue(): RawValue|null;

Returns the default value to make the RBDM use the default value declared in the table definition

// 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()

public function getDescriptor(): array;

Return descriptor used to connect to the active database

getDialect()

public function getDialect(): DialectInterface;

Returns internal dialect instance

getDialectType()

public function getDialectType(): string;

Returns the name of the dialect used

getInternalHandler()

public function getInternalHandler(): mixed;

Return internal PDO handler

getNestedTransactionSavepointName()

public function getNestedTransactionSavepointName(): string;

Returns the savepoint name to use for nested transactions

getRealSQLStatement()

public function getRealSQLStatement(): string;

Active SQL statement in the object without replace bound parameters

getSQLBindTypes()

public function getSQLBindTypes(): array;

Active SQL statement in the object

getSQLStatement()

public function getSQLStatement(): string;

Active SQL statement in the object

getSQLVariables()

public function getSQLVariables(): array;

Active SQL statement in the object

getType()

public function getType(): string;

Returns type of database system the adapter is used for

insert()

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()

public function insertAsDict(
    string $table,
    mixed $data,
    mixed $dataTypes = null
): bool;

Inserts data into a table using custom RBDM SQL syntax

// 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);