Phalcon Dispatcher

Dispatcher\AbstractDispatcher

This is the base class for Phalcon\Mvc\Dispatcher and Phalcon\Cli\Dispatcher. This class can’t be instantiated directly, you can use it to create your own dispatchers.

Error protocol

Subclasses (including third-party ones) MUST implement the two abstract error hooks throwDispatchException() and handleException(). The dispatch loop calls them on every error/exception path; a subclass that omits them cannot be loaded.

Hook channels

A single lifecycle point can be intercepted through three independent channels. For any given point they run in this order:

1. Events-manager listener - e.g. dispatch:beforeExecuteRoute. A listener returning false cancels; calling forward() re-enters the loop; throwing routes through handleException().
2. Duck-typed handler method - e.g. a beforeExecuteRoute() method on the controller/task itself (presence is cached per class). Same false / forward() cancellation semantics as the event.
3. dispatch:beforeCallAction observer - fired by callActionMethod() with a Phalcon\Support\Collection carrying the mutable keys handler, action and params. Listeners may rewrite those keys to change what gets invoked; the substituted callable is re-validated before the call. dispatch:afterCallAction receives the same Collection plus a result key.

@todo fix the returnValue type in v7

Uses Exception · Phalcon\Contracts\Dispatcher\DispatcherTypes · Phalcon\Di\AbstractInjectionAware · Phalcon\Di\DiInterface · Phalcon\Dispatcher\Exception · Phalcon\Dispatcher\Exceptions\ForwardInInitializeForbidden · Phalcon\Events\EventsAwareInterface · Phalcon\Events\ManagerInterface · Phalcon\Events\Traits\EventsAwareTrait · Phalcon\Filter\FilterInterface · Phalcon\Mvc\Model\Binder · Phalcon\Mvc\Model\BinderInterface · Phalcon\Support\Collection

Method Summary

Properties

Methods

callActionMethod()

public function callActionMethod(
    mixed $handler,
    string $actionMethod,
    array $params = []
);

dispatch()

public function dispatch(): mixed|bool;

Process the results of the router by calling into the appropriate controller action(s) including any routing data or injected parameters.

forward()

public function forward( array $forward ): void;

Forwards the execution flow to another controller/action.

$this->dispatcher->forward(
    [
        "controller" => "posts",
        "action"     => "index",
    ]
);

getActionName()

public function getActionName(): string;

Gets the latest dispatched action name

getActionSuffix()

public function getActionSuffix(): string;

Gets the default action suffix

getActiveMethod()

public function getActiveMethod(): string;

Returns the current method to be/executed in the dispatcher

getBoundModels()

public function getBoundModels(): array;

Returns bound models from binder instance

class UserController extends Controller
{
    public function showAction(User $user)
    {
        // return array with $user
        $boundModels = $this->dispatcher->getBoundModels();
    }
}

getDefaultNamespace()

public function getDefaultNamespace(): string;

Returns the default namespace

getHandlerClass()

public function getHandlerClass(): string;

Possible class name that will be located to dispatch the request

getHandlerSuffix()

public function getHandlerSuffix(): string;

Gets the default handler suffix

getModelBinder()

public function getModelBinder(): BinderInterface|null;

Gets model binder

getModuleName()

public function getModuleName(): string|null;

Gets the module where the controller class is

getNamespaceName()

public function getNamespaceName(): string;

Gets a namespace to be prepended to the current handler name

getParam()

public function getParam(
    mixed $param,
    mixed $filters = null,
    mixed $defaultValue = null
): mixed;

Gets a param by its name or numeric index

Note: The interface declares getParam(param, filters = null) without the defaultValue argument, so code typed against DispatcherInterface cannot use the default-value feature. This signature drift is intentional for now; the interface and implementation will be aligned in the next major version.

getParameter()

public function getParameter(
    mixed $param,
    mixed $filters = null,
    mixed $defaultValue = null
): mixed;

Gets a param by its name or numeric index

getParameters()

public function getParameters(): array;

Gets action params

getParams()

public function getParams(): array;

Gets action params

getPreviousActionName()

public function getPreviousActionName(): string;

Gets previous dispatched action name

getPreviousHandlerName()

public function getPreviousHandlerName(): string;

Gets previous dispatched handler name

getPreviousNamespaceName()

public function getPreviousNamespaceName(): string;

Gets previous dispatched namespace name

getReturnedValue()

public function getReturnedValue(): mixed;

Returns value returned by the latest dispatched action

hasParam()

public function hasParam( mixed $param ): bool;

Check if a param exists

hasParameter()

public function hasParameter( mixed $param ): bool;

Check if a param exists

isFinished()

public function isFinished(): bool;

Checks if the dispatch loop is finished or has more pendent controllers/tasks to dispatch

setActionName()

public function setActionName( string $actionName ): void;

Sets the action name to be dispatched

setActionSuffix()

public function setActionSuffix( string $actionSuffix ): void;

Sets the default action suffix

setDefaultAction()

public function setDefaultAction( string $actionName ): void;

Sets the default action name

setDefaultNamespace()

public function setDefaultNamespace( string $defaultNamespace ): void;

Sets the default namespace

setHandlerSuffix()

public function setHandlerSuffix( string $handlerSuffix ): void;

Sets the default suffix for the handler

setModelBinder()

public function setModelBinder(
    BinderInterface $modelBinder,
    mixed $cache = null
): DispatcherInterface;

Enable model binding during dispatch

$di->set(
    'dispatcher',
    function() {
        $dispatcher = new Dispatcher();

        $dispatcher->setModelBinder(
            new Binder(),
            'cache'
        );

        return $dispatcher;
    }
);

setModuleName()

public function setModuleName( string|null $moduleName = null ): void;

Sets the module where the controller is (only informative)

setNamespaceName()

public function setNamespaceName( string $namespaceName ): void;

Sets the namespace where the controller class is

setParam()

public function setParam(
    mixed $param,
    mixed $value
): void;

Set a param by its name or numeric index

setParameter()

public function setParameter(
    mixed $param,
    mixed $value
): void;

Set a param by its name or numeric index

setParameters()

public function setParameters( array $params ): void;

Sets action params to be dispatched

setParams()

public function setParams( array $params ): void;

Sets action params to be dispatched

setReturnedValue()

public function setReturnedValue( mixed $value ): void;

Sets the latest returned value by an action manually

wasForwarded()

public function wasForwarded(): bool;

Check if the current executed action was forwarded by another one

handleException()

abstract protected function handleException( \Exception $exception );

Handles a user exception triggered inside the dispatch loop.

Subclasses implement the namespace-specific behavior (typically firing the dispatch:beforeException event so listeners may forward or swallow the exception).

resolveEmptyProperties()

protected function resolveEmptyProperties(): void;

Set empty properties to their defaults (where defaults are available)

throwDispatchException()

abstract protected function throwDispatchException(
    string $message,
    int $exceptionCode = 0
);

Throws an internal dispatch exception.

Subclasses build the namespace-specific exception and route it through handleException() before throwing it when it was not handled.

toCamelCase()

protected function toCamelCase( string $input ): string;

Dispatcher\DispatcherInterface

Interface for Phalcon\Dispatcher\AbstractDispatcher

Uses Phalcon\Contracts\Dispatcher\Dispatcher

Dispatcher\Exception

Exceptions thrown in Phalcon\Dispatcher/* will use this class

Constants

Dispatcher\Exceptions\ForwardInInitializeForbidden

Uses Phalcon\Dispatcher\Exception

Method Summary

Methods

__construct()

public function __construct();