Events

This section will help you understand how to register your own callbacks to events in the router. It will also cover the basics of event-handlers; how to use the handlers provided with the router and how to create your own custom event-handlers.

Available Events

This section contains all available events that can be registered using the RoutingEventHandler.

All event callbacks will retrieve a RoutingEventArgument object as parameter. This object contains easy access to event-name, router- and request instance and any special event-arguments related to the given event. You can see what special event arguments each event returns in the list below.

Name	Special arguments	Description
EVENT_ALL	-	Fires when a event is triggered.
EVENT_INIT	-	Fires when router is initializing and before routes are loaded.
EVENT_LOAD	loadedRoutes	Fires when all routes have been loaded and rendered, just before the output is returned.
EVENT_ADD_ROUTE	route	Fires when route is added to the router.
EVENT_BOOT	bootmanagers	Fires when the router is booting. This happens just before boot-managers are rendered and before any routes has been loaded.
EVENT_RENDER_BOOTMANAGER	bootmanagers bootmanager	Fires before a boot-manager is rendered.
EVENT_LOAD_ROUTES	routes	Fires when the router is about to load all routes.
EVENT_FIND_ROUTE	name	Fires whenever the has method is used.
EVENT_GET_URL	name params	Fires whenever the Router::url method is called and the router tries to find the route.
EVENT_MATCH_ROUTE	route	Fires when a route is matched and valid (correct request-type etc). and before the route is rendered.
EVENT_RENDER_MIDDLEWARES	route middlewares	Fires before middlewares for a route is rendered.

Registering New Event

To register a new event you need to create a new instance of the Qubus\Routing\Events\RoutingEventHandler object. On this object you can add as many callbacks as you like by calling the registerEvent method.

When you've registered events, make sure to add it to your routes file by calling the addEventHandler method from the router. We recommend that you add your event-handlers within your routes.php.

use Qubus\Routing\Events\RoutingEventHandler;
use Qubus\Routing\Events\RoutingEventArgument;

// --- your routes goes here ---

$eventHandler = new RoutingEventHandler();

// Add event that fires when a route is rendered
$eventHandler->register(RoutingEventHandler::EVENT_ADD_ROUTE, function(RoutingEventArgument $argument) {
   
   // Get the route by using the special argument for this event.
   $route = $argument->route;
   
   // DO STUFF...
    
});

$router->addEventHandler($eventHandler);

Custom EventHandlers

Qubus\Routing\Events\RoutingEventHandler is the class that manages events and must inherit from the Qubus\Routing\Events\EventHandler contract. The handler knows how to handle events for the given handler type.

Most of the time the basic Qubus\Routing\Events\RoutingEventHandler class will be more than enough for most people as you simply register an event which fires when triggered.

Let's go over how to create your very own event handler class.

Below is a basic example of a custom event-handler called DatabaseDebugHandler. The idea of the example below is to log all events to the database when triggered. Hopefully this is enough to give you an idea of how event handlers work.

namespace Mvc\App\Events;

use Qubus\Routing\Router;
use Qubus\Routing\Events\RoutingEventArgument;
use Qubus\Routing\Events\EventHandler;

class DatabaseDebugHandler implements EventHandler
{

    /**
     * Debug callback
     * @var \Closure
     */
    protected $callback;

    public function __construct()
    {
        $this->callback = function (RoutingEventArgument $argument) {
            // todo: store log in database
        };
    }

    /**
     * Get events.
     *
     * @param string|null $name Filter events by name.
     * @return array
     */
    public function getEvents(?string $name): array
    {
        return [
            $name => [
                $this->callback,
            ],
        ];
    }

    /**
     * Fires any events registered with given event name
     *
     * @param Router $router Router instance
     * @param string $name Event name
     * @param array ...$eventArgs Event arguments
     */
    public function fireEvents(Router $router, string $name, ...$eventArgs): void
    {
        $callback = $this->callback;
        $callback(new RoutingEventArgument($router, $eventArgs));
    }

    /**
     * Set debug callback
     *
     * @param \Closure $event
     */
    public function setCallback(\Closure $event): void
    {
        $this->callback = $event;
    }

}