Dispatcher Component

    Phalcon\Mvc\Dispatcher is the component responsible for instantiating controllers and executing the required actions on them in an MVC application. Understanding its operation and capabilities helps us get more out of the services provided by the framework.

    The Dispatch Loop

    This is an important process that has much to do with the MVC flow itself, especially with the controller part. The work occurs within the controller dispatcher. The controller files are read, loaded, and instantiated. Then the required actions are executed. If an action forwards the flow to another controller/action, the controller dispatcher starts again. To better illustrate this, the following example shows approximately the process performed within Phalcon\Mvc\Dispatcher:

    The code above lacks validations, filters and additional checks, but it demonstrates the normal flow of operation in the dispatcher.

    is able to send events to an EventsManager if it is present. Events are triggered using the type . Some events when returning boolean false could stop the active operation. The following events are supported:

    The tutorial shows how to take advantage of dispatching events implementing a security filter with Acl

    The following example demonstrates how to attach listeners to this component:

    1. <?php
    3. use Phalcon\Mvc\Dispatcher as MvcDispatcher;
    4. use Phalcon\Events\Event;
    5. use Phalcon\Events\Manager as EventsManager;
    7. $di->set(
    8.     'dispatcher',
    9.     function () {
    10.         // Create an event manager
    11.         $eventsManager = new EventsManager();
    13.         // Attach a listener for type 'dispatch'
    14.         $eventsManager->attach(
    15.             'dispatch',
    16.             function (Event $event, $dispatcher) {
    17.                 // ...
    18.             }
    19.         );
    21.         $dispatcher = new MvcDispatcher();
    23.         // Bind the eventsManager to the view component
    24.         $dispatcher->setEventsManager($eventsManager);
    26.         return $dispatcher;
    27.     },
    28.     true
    29. );

    An instantiated controller automatically acts as a listener for dispatch events, so you can implement methods as callbacks:

    1. <?php
    3. use Phalcon\Mvc\Controller;
    4. use Phalcon\Mvc\Dispatcher;
    6. class PostsController extends Controller
    7. {
    8.     public function beforeExecuteRoute(Dispatcher $dispatcher)
    9.     {
    10.         // Executed before every found action
    11.     }
    13.     public function afterExecuteRoute(Dispatcher $dispatcher)
    14.     {
    15.         // Executed after every found action
    16.     }
    17. }

    The dispatch loop allows us to forward the execution flow to another controller/action. This is very useful to check if the user can access to certain options, redirect users to other screens or simply reuse code.

    1. <?php
    3. use Phalcon\Mvc\Controller;
    5. class PostsController extends Controller
    6. {
    7.     public function indexAction()
    8.     {
    10.     }
    12.     public function saveAction($year, $postTitle)
    13.     {
    14.         // ... Store some product and forward the user
    16.         // Forward flow to the index action
    17.         $this->dispatcher->forward(
    18.             [
    19.                 'controller' => 'posts',
    20.                 'action'     => 'index',
    21.             ]
    22.         );
    23.     }
    24. }

    Keep in mind that making a forward is not the same as making a HTTP redirect. Although they apparently got the same result. The forward doesn’t reload the current page, all the redirection occurs in a single request, while the HTTP redirect needs two requests to complete the process.

    More forwarding examples:

    1. <?php
    3. // Forward flow to another action in the current controller
    4. $this->dispatcher->forward(
    5.     [
    6.         'action' => 'search',
    7.     ]
    8. );
    10. // Forward flow to another action in the current controller
    11. // passing parameters
    12. $this->dispatcher->forward(
    13.     [
    14.         'action' => 'search',
    15.         'params' => [1, 2, 3],
    16.     ]
    17. );
    ParameterDescription
    controllerA valid controller name to forward to.
    actionA valid action name to forward to.
    paramsAn array of parameters for the action.
    namespaceA valid namespace name where the controller is part of.

    You can use the dispatcher::beforeForward event to change modules and redirect easier and “cleaner”:

    1. <?php
    3. use Phalcon\Di;
    4. use Phalcon\Events\Manager;
    5. use Phalcon\Mvc\Dispatcher;
    6. use Phalcon\Events\Event;
    8. $di = new Di();
    10. $modules = [
    11.     'backend' => [
    12.         'className' => \App\Backend\Bootstrap::class,
    13.         'path'      => '/app/Modules/Backend/Bootstrap.php',
    14.         'metadata'  => [
    15.             'controllersNamespace' => 'App\Backend\Controllers',
    16.         ],
    17.     ],
    18. ];
    20. $manager = new Manager();
    22. $manager->attach(
    23.     'dispatch:beforeForward',
    24.     function (Event $event, Dispatcher $dispatcher, array $forward) use ($modules) {
    25.         $moduleName = $forward['module'];
    27.         $metadata = $modules[$moduleName]['metadata'];
    29.         $dispatcher->setModuleName($moduleName);
    31.         $dispatcher->setNamespaceName(
    32.             $metadata['controllersNamespace']
    33.         );
    34.     }
    35. );
    37. $dispatcher = new Dispatcher();
    39. $dispatcher->setDI($di);
    42. $di->set('dispatcher', $dispatcher);
    44. $dispatcher->forward(
    45.     [
    46.         'module'     => 'backend',
    47.         'controller' => 'posts',
    48.         'action'     => 'index',
    49.     ]
    50. );
    52. echo $dispatcher->getModuleName(); // will display properly 'backend'

    Preparing Parameters

    Thanks to the hook points provided by Phalcon\Mvc\Dispatcher you can easily adapt your application to any URL schema; i.e. you might want your URLs look like: . Since parameters are passed with the order that they are defined in the URL to actions, you can transform them to adopt the desired schema:

    If the desired schema is: https://example.com/controller/key1:value1/key2:value, the following code is required:

    1. <?php
    3. use Phalcon\Dispatcher;
    4. use Phalcon\Events\Event;
    5. use Phalcon\Events\Manager as EventsManager;
    6. use Phalcon\Mvc\Dispatcher as MvcDispatcher;
    8. $di->set(
    9.     'dispatcher',
    10.     function () {
    11.         // Create an EventsManager
    12.         $eventsManager = new EventsManager();
    14.         // Attach a listener
    15.         $eventsManager->attach(
    16.             'dispatch:beforeDispatchLoop',
    17.             function (Event $event, $dispatcher) {
    18.                 $params = $dispatcher->getParams();
    20.                 $keyParams = [];
    22.                 // Explode each parameter as key,value pairs
    23.                 foreach ($params as $param) {
    24.                     $parts = explode(':', $param);
    26.                     $key   = $parts[0];
    27.                     $value = $parts[1];
    29.                     $keyParams[$key] = $value;
    30.                 }
    32.                 // Override parameters
    33.                 $dispatcher->setParams($keyParams);
    34.             }
    35.         );
    37.         $dispatcher = new MvcDispatcher();
    39.         $dispatcher->setEventsManager($eventsManager);
    41.         return $dispatcher;
    42.     }
    43. );

    When a route provides named parameters you can receive them in a controller, a view or any other component that extends .

    1. <?php
    3. use Phalcon\Mvc\Controller;
    5. class PostsController extends Controller
    6. {
    7.     public function indexAction()
    8.     {
    10.     }
    12.     public function saveAction()
    13.     {
    14.         // Get the post's title passed in the URL as parameter
    15.         // or prepared in an event
    16.         $title = $this->dispatcher->getParam('title');
    18.         // Get the post's year passed in the URL as parameter
    19.         // or prepared in an event also filtering it
    20.         $year = $this->dispatcher->getParam('year', 'int');
    22.         // ...
    23.     }
    24. }

    Preparing actions

    You can also define an arbitrary schema for actions before in the dispatch loop.

    If the original URL is: , and for example you want to camelize show-latest-products to ShowLatestProducts, the following code is required:

    1. <?php
    3. use Phalcon\Text;
    4. use Phalcon\Mvc\Dispatcher as MvcDispatcher;
    5. use Phalcon\Events\Event;
    6. use Phalcon\Events\Manager as EventsManager;
    8. $di->set(
    9.     'dispatcher',
    10.     function () {
    11.         // Create an EventsManager
    12.         $eventsManager = new EventsManager();
    14.         // Camelize actions
    15.         $eventsManager->attach(
    16.             'dispatch:beforeDispatchLoop',
    17.             function (Event $event, $dispatcher) {
    18.                 $dispatcher->setActionName(
    19.                     Text::camelize(
    20.                         $dispatcher->getActionName()
    21.                     )
    22.                 );
    23.             }
    24.         );
    26.         $dispatcher = new MvcDispatcher();
    28.         $dispatcher->setEventsManager($eventsManager);
    30.         return $dispatcher;
    31.     }
    32. );

    If the original URL always contains a .php extension:

    1. https://example.com/admin/products/show-latest-products.php
    2. https://example.com/admin/products/index.php

    You can remove it before dispatch the controller/action combination:

    1. <?php
    3. use Phalcon\Mvc\Dispatcher as MvcDispatcher;
    4. use Phalcon\Events\Event;
    5. use Phalcon\Events\Manager as EventsManager;
    7. $di->set(
    8.     'dispatcher',
    9.     function () {
    10.         // Create an EventsManager
    11.         $eventsManager = new EventsManager();
    13.         // Remove extension before dispatch
    14.         $eventsManager->attach(
    15.             'dispatch:beforeDispatchLoop',
    16.             function (Event $event, $dispatcher) {
    17.                 $action = $dispatcher->getActionName();
    19.                 // Remove extension
    20.                 $action = preg_replace('/\.php$/', '', $action);
    22.                 // Override action
    23.                 $dispatcher->setActionName($action);
    24.             }
    25.         );
    27.         $dispatcher = new MvcDispatcher();
    28.         $dispatcher->setEventsManager($eventsManager);
    30.         return $dispatcher;
    31.     }

    In this example, the developer wants to inspect the parameters that an action will receive in order to dynamically inject model instances.

    The controller looks like:

    Method showAction receives an instance of the model \Posts, the developer could inspect this before dispatch the action preparing the parameter accordingly:

    1. <?php
    3. use \Exception;
    4. use Phalcon\Mvc\Model;
    5. use Phalcon\Mvc\Dispatcher as MvcDispatcher;
    6. use Phalcon\Events\Event;
    7. use Phalcon\Events\Manager as EventsManager;
    8. use \ReflectionMethod;
    10. $di->set(
    11.     'dispatcher',
    12.     function () {
    13.         // Create an EventsManager
    14.         $eventsManager = new EventsManager();
    16.         $eventsManager->attach(
    17.             'dispatch:beforeDispatchLoop',
    18.             function (Event $event, $dispatcher) {
    19.                 // Possible controller class name
    20.                 $controllerName = $dispatcher->getControllerClass();
    22.                 // Possible method name
    23.                 $actionName = $dispatcher->getActiveMethod();
    25.                 try {
    26.                     // Get the reflection for the method to be executed
    27.                     $reflection = new ReflectionMethod($controllerName, $actionName);
    29.                     $parameters = $reflection->getParameters();
    31.                     // Check parameters
    32.                     foreach ($parameters as $parameter) {
    33.                         // Get the expected model name
    34.                         $className = $parameter->getClass()->name;
    36.                         // Check if the parameter expects a model instance
    37.                         if (is_subclass_of($className, Model::class)) {
    38.                             $model = $className::findFirstById(
    39.                                 $dispatcher->getParams()[0]
    40.                             );
    42.                             // Override the parameters by the model instance
    43.                             $dispatcher->setParams(
    44.                                 [
    45.                                     $model,
    46.                                 ]
    47.                             );
    48.                         }
    49.                     }
    50.                 } catch (Exception $e) {
    51.                     // An exception has occurred, maybe the class or action does not exist?
    52.                 }
    53.             }
    54.         );
    56.         $dispatcher = new MvcDispatcher();
    58.         $dispatcher->setEventsManager($eventsManager);
    60.         return $dispatcher;
    61.     }
    62. );

    From 3.1.x onwards the dispatcher also comes with an option to handle this internally for all models passed into a controller action by using Phalcon\Mvc\Model\Binder.

    1. use Phalcon\Mvc\Dispatcher;
    2. use Phalcon\Mvc\Model\Binder;
    4. $dispatcher = new Dispatcher();
    6. $dispatcher->setModelBinder(
    7.     new Binder()
    8. );
    10. return $dispatcher;

    It also introduces a new interface which allows you to define the controllers associated models to allow models binding in base controllers.

    For example, you have a base CrudController which your PostsController extends from. Your CrudController looks something like this:

    1. use Phalcon\Mvc\Controller;
    2. use Phalcon\Mvc\Model;
    4. class CrudController extends Controller
    5. {
    6.     /**
    7.      * Show action
    8.      */
    9.     public function showAction(Model $model)
    10.     {
    11.         $this->view->model = $model;
    12.     }
    13. }

    In your PostsController you need to define which model the controller is associated with. This is done by implementing the Phalcon\Mvc\Model\Binder\BindableInterface which will add the getModelName() method from which you can return the model name. It can return string with just one model name or associative array where key is parameter name.

    1. use Phalcon\Mvc\Model\Binder\BindableInterface;
    2. use Models\Posts;
    4. class PostsController extends CrudController implements BindableInterface
    5. {
    6.     public static function getModelName()
    7.     {
    8.         return Posts::class;
    9.     }
    10. }

    By declaring the model associated with the PostsController the binder can check the controller for the getModelName() method before passing the defined model into the parent show action.

    If your project structure does not use any parent controller you can of course still bind the model directly into the controller action:

    1. use Phalcon\Mvc\Controller;
    2. use Models\Posts;
    4. class PostsController extends Controller
    5. {
    6.     /**
    7.      * Shows posts
    8.      */
    9.     public function showAction(Posts $post)
    10.     {
    11.         $this->view->post = $post;
    12.     }
    13. }

    Using the it’s possible to insert a hook point before the dispatcher throws an exception when the controller/action combination wasn’t found:

    Of course, this method can be moved onto independent plugin classes, allowing more than one class take actions when an exception is produced in the dispatch loop:

    1. <?php
    3. use Exception;
    4. use Phalcon\Events\Event;
    5. use Phalcon\Mvc\Dispatcher;
    6. use Phalcon\Mvc\Dispatcher\Exception as DispatchException;
    8. class ExceptionsPlugin
    9. {
    10.     public function beforeException(Event $event, Dispatcher $dispatcher, Exception $exception)
    11.     {
    12.         // Default error action
    13.         $action = 'show503';
    15.         // Handle 404 exceptions
    16.         if ($exception instanceof DispatchException) {
    17.             $action = 'show404';
    18.         }
    20.         $dispatcher->forward(
    21.             [
    22.                 'controller' => 'index',
    23.                 'action'     => $action,
    24.             ]
    25.         );
    27.         return false;
    28. }

    Implementing your own Dispatcher