The event system¶
Dispatcher has an integrated event’s system that can be used to extend its features by plugins.
When a client calls dispatcher, request, route and response are modeled as objects and provided to the callback function hooked to relative event.
Dispatcher starts to emit events as soon as a request is received.
Let’s consider an example:
global $dispatcher;
function custom_404($ObjectError) {
$error_page = file_get_contents(DISPATCHER_REAL_PATH."vendor/comodojo/dispatcher.plugin.test/resources/html/404.html");
$ObjectError->setContent($error_page);
return $ObjectError;
}
$dispatcher->addHook("dispatcher.error.404", "custom_404");
In this example, a plugin will set a custom content in default 404 error page by:
- catching event “dispatcher.error.404”;
- replacing error content using “setContent()” method;
- returning to framework the modified object.
How dispatcher emits events¶
By default, dispatcher uses this schema to emit events:
[framework].[event].[notification*|*marker]
In practice:
- [framework] will always be populated by the string dispatcher;
- [event] represents the event macroclass; possible values are request, routingtable, serviceroute, result, route, redirect or error.
- [notification|marker] is a detailed view of what is happening; it can assume different values, like HTTP return codes (like 404 in the previous example for a “not found” response.
There are also two special category of events:
- start event (dispatcher), that will fire at framework startup;
- markers, fired to express a particular condition (like # that denote the end of specific event’s macroclass).
Each type of event expects the callback to return a particular kind of object. If something different is provided, callback’s result will be discarded.
Note
If a single event is hooked to multiple callbacks, it will behave as a chain: the first result (if any) will be the input of the second callback and so on.
Sone examples are:
- dispatcher.serviceroute - a level 2 event that expose the route retrieved for the current request
- dispatcher.error.404 - a level 3 event for a not found response
- dispatcher.result.# - a level 3 event that fires after every other callback
The complete event list¶
dispatcher receive a request
- dispatcher - marks the frameworks has entered the running cycle and exposes the whole ComodojoDispatcherDispatcher instance without expecting any return value
Request is modeled as an instance of ComodojoDispatcherObjectRequestObjectRequest
- dispatcher.request - provides and expects an instance of ComodojoDispatcherObjectRequestObjectRequest
- dispatcher.request.[METHOD] - provides and expects an instance of ComodojoDispatcherObjectRequestObjectRequest
- dispatcher.request.[SERVICE] - provides and expects an instance of ComodojoDispatcherObjectRequestObjectRequest
- dispatcher.request.# - provides a ComodojoDispatcherObjectRequestObjectRequest, will fire after every other callback discarding returned data
An instance of ComodojoDispatcherObjectRoutingTableObjectRoutingTable is created
- dispatcher.routingtable - provides and expects an instance of ComodojoDispatcherObjectRoutingTableObjectRoutingTable
A route was retrieved from routingtable
- dispatcher.serviceroute - provides and expects an instance of ComodojoDispatcherObjectRouteObjectRoute
- dispatcher.serviceroute.[TYPE] - provides and expects an instance of ComodojoDispatcherObjectRouteObjectRoute
- dispatcher.serviceroute.[SERVICE] - provides and expects an instance of ComodojoDispatcherObjectRouteObjectRoute
- dispatcher.serviceroute.# - provides a ComodojoDispatcherObjectRouteObjectRoute, will fire after every other callback and discarding returned data
Once a route is retrieved, dispatcher will run a service, redirect to another location or return an error; in any case, a result object that implements the ComodojoDispatcherObjectResultObjectResultInterface is inited, provided to the callback and expected as result.
dispatcher.result
In case of success
- dispatcher.route
- dispatcher.route.[STATUSCODE]
In case of redirect
- dispatcher.redirect
- dispatcher.redirect.[STATUSCODE]
In case of error
- dispatcher.error
- dispatcher.error.[STATUSCODE]
dispatcher.result.# will fire after every other callback and expects an instance of ComodojoDispatcherObjectResultObjectResultInterface
result is returned to client