---
title: "Phalcon Dispatcher"
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 Dispatcher
:::info[NOTE]
All classes are prefixed with `Phalcon`
:::
## Dispatcher\AbstractDispatcher
Abstract
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
- `\stdClass`
- [`Phalcon\Di\AbstractInjectionAware`](/5.20/api/phalcon_di/#diabstractinjectionaware)
- **`Phalcon\Dispatcher\AbstractDispatcher`** - implements [`Phalcon\Dispatcher\DispatcherInterface`](#dispatcherdispatcherinterface), [`Phalcon\Events\EventsAwareInterface`](/5.20/api/phalcon_events/#eventseventsawareinterface)
- [`Phalcon\Cli\Dispatcher`](/5.20/api/phalcon_cli/#clidispatcher)
- [`Phalcon\Mvc\Dispatcher`](/5.20/api/phalcon_mvc/#mvcdispatcher)
`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
Process the results of the router by calling into the appropriate
Forwards the execution flow to another controller/action.
Gets the latest dispatched action name
Gets the default action suffix
Returns the current method to be/executed in the dispatcher
Returns bound models from binder instance
Returns the default namespace
Possible class name that will be located to dispatch the request
Gets the default handler suffix
Gets model binder
Gets the module where the controller class is
Gets a namespace to be prepended to the current handler name
Gets a param by its name or numeric index
Gets a param by its name or numeric index
Gets action params
Gets action params
Gets previous dispatched action name
Gets previous dispatched handler name
Gets previous dispatched namespace name
Returns value returned by the latest dispatched action
Check if a param exists
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
Enable model binding during dispatch
Sets the module where the controller is (only informative)
Sets the namespace where the controller class is
Set a param by its name or numeric index
Set a param by its name or numeric index
Sets action params to be dispatched
Sets action params to be dispatched
Sets the latest returned value by an action manually
Check if the current executed action was forwarded by another one
Handles a user exception triggered inside the dispatch loop.
Set empty properties to their defaults (where defaults are available)
Throws an internal dispatch exception.
### Properties
### Methods
callActionMethod()
```php
public function callActionMethod(
mixed $handler,
string $actionMethod,
array $params = []
);
```
dispatch()
```php
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()
```php
public function forward( array $forward ): void;
```
Forwards the execution flow to another controller/action.
```php
$this->dispatcher->forward(
[
"controller" => "posts",
"action" => "index",
]
);
```
getActionName()
```php
public function getActionName(): string;
```
Gets the latest dispatched action name
getActionSuffix()
```php
public function getActionSuffix(): string;
```
Gets the default action suffix
getActiveMethod()
```php
public function getActiveMethod(): string;
```
Returns the current method to be/executed in the dispatcher
getBoundModels()
```php
public function getBoundModels(): array;
```
Returns bound models from binder instance
```php
class UserController extends Controller
{
public function showAction(User $user)
{
// return array with $user
$boundModels = $this->dispatcher->getBoundModels();
}
}
```
getDefaultNamespace()
```php
public function getDefaultNamespace(): string;
```
Returns the default namespace
getHandlerClass()
```php
public function getHandlerClass(): string;
```
Possible class name that will be located to dispatch the request
getHandlerSuffix()
```php
public function getHandlerSuffix(): string;
```
Gets the default handler suffix
getModelBinder()
```php
public function getModelBinder(): BinderInterface|null;
```
Gets model binder
getModuleName()
```php
public function getModuleName(): string|null;
```
Gets the module where the controller class is
getNamespaceName()
```php
public function getNamespaceName(): string;
```
Gets a namespace to be prepended to the current handler name
getParam()
```php
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()
```php
public function getParameter(
mixed $param,
mixed $filters = null,
mixed $defaultValue = 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
getPreviousActionName()
```php
public function getPreviousActionName(): string;
```
Gets previous dispatched action name
getPreviousHandlerName()
```php
public function getPreviousHandlerName(): string;
```
Gets previous dispatched handler name
getPreviousNamespaceName()
```php
public function getPreviousNamespaceName(): string;
```
Gets previous dispatched namespace name
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
hasParameter()
```php
public function hasParameter( 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
setModelBinder()
```php
public function setModelBinder(
BinderInterface $modelBinder,
mixed $cache = null
): DispatcherInterface;
```
Enable model binding during dispatch
```php
$di->set(
'dispatcher',
function() {
$dispatcher = new Dispatcher();
$dispatcher->setModelBinder(
new Binder(),
'cache'
);
return $dispatcher;
}
);
```
setModuleName()
```php
public function setModuleName( string|null $moduleName = null ): void;
```
Sets the module where the controller is (only informative)
setNamespaceName()
```php
public function setNamespaceName( string $namespaceName ): void;
```
Sets the namespace where the controller class is
setParam()
```php
public function setParam(
mixed $param,
mixed $value
): void;
```
Set a param by its name or numeric index
setParameter()
```php
public function setParameter(
mixed $param,
mixed $value
): void;
```
Set a param by its name or numeric index
setParameters()
```php
public function setParameters( array $params ): void;
```
Sets action params to be dispatched
setParams()
```php
public function setParams( array $params ): void;
```
Sets action params to be dispatched
setReturnedValue()
```php
public function setReturnedValue( mixed $value ): void;
```
Sets the latest returned value by an action manually
wasForwarded()
```php
public function wasForwarded(): bool;
```
Check if the current executed action was forwarded by another one
handleException()
```php
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()
```php
protected function resolveEmptyProperties(): void;
```
Set empty properties to their defaults (where defaults are available)
throwDispatchException()
```php
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()
```php
protected function toCamelCase( string $input ): string;
```
## Dispatcher\DispatcherInterface
Interface
Interface for Phalcon\Dispatcher\AbstractDispatcher
- [`Phalcon\Contracts\Dispatcher\Dispatcher`](/5.20/api/phalcon_contracts/#contractsdispatcherdispatcher)
- **`Phalcon\Dispatcher\DispatcherInterface`**
`Phalcon\Contracts\Dispatcher\Dispatcher`
## Dispatcher\Exception
Class
Exceptions thrown in Phalcon\Dispatcher/* will use this class
- `\Exception`
- **`Phalcon\Dispatcher\Exception`**
- [`Phalcon\Cli\Dispatcher\Exception`](/5.20/api/phalcon_cli/#clidispatcherexception)
- [`Phalcon\Dispatcher\Exceptions\ForwardInInitializeForbidden`](#dispatcherexceptionsforwardininitializeforbidden)
- [`Phalcon\Mvc\Dispatcher\Exception`](/5.20/api/phalcon_mvc/#mvcdispatcherexception)
### Constants
## Dispatcher\Exceptions\ForwardInInitializeForbidden
Class
- `\Exception`
- [`Phalcon\Dispatcher\Exception`](#dispatcherexception)
- **`Phalcon\Dispatcher\Exceptions\ForwardInInitializeForbidden`**
`Phalcon\Dispatcher\Exception`
### Method Summary
### Methods
__construct()
```php
public function __construct();
```
Source: https://docs.phalcon.io/5.20/api/phalcon_dispatcher/index.mdx