Comodojo dispatcher docs¶

Requirements¶

To work properly, dispatcher requires an apache webserver with PHP >=5.3.0, installed as apache module or cgi/fastcgi.

It may work on different webservers like nginx (ensure to convert the .htaccess logic if you plan to use rewrite mode), but this is actually untested.

Installing via composer¶

First install composer, then create a new dispatcher.project using this command:

php composer.phar create-project comodojo/dispatcher.project dispatcher

This will install a new instance of dispatcher and required dependencies in “dispatcher” folder.

If you need also default content and tests, install the package:

php composer.phar require comodojo/dispatcher.servicebundle.default

## Downloading as archive

Stable releases are published on dispatcher.comodojo.org.

To install, download latest package and type (in the package folder):

php composer.phar install

Directory structure¶

The project package will create the following directory structure (excluding files):

dispatcher/
    - DispatcherInstaller/ => contains the DispatcherInstaller class, fired when composer install/update/remove packages
    - cache/ => cache files will be written here; ensure apache user can write here
    - configs/ => configuration files' folder
    - logs/ => where monolog (if enabled) will write logs
    - plugins/ => this folder is dedicated to plugins manually installed or created by user
    - services/ => this folder is dedicated to services manually installed or created by user
    - templates/ => this folder is dedicated to templates manually installed or created by user
    - vendor/ => composer standard vendor folder
    - index.php
    - [...]

Configuration files¶

Dispatcher comes out of the box with a default configuration that can be edited to change global behaviour of framework.

Configuration files are contained in configs folder:

• dispatcher-config.php: contains constants defined to change some aspect of framework (like paths, logging, ...)
• plugins-config.php: (should) contain plugins init scripts; initially empty
• routing-config.php: (should) contain declaration of routes; initially empty

These files are loaded at boot time.

General properties¶

define("DISPATCHER_REAL_PATH",realpath(dirname(__FILE__))."/../");

define("DISPATCHER_BASEURL","");

define ('DISPATCHER_ENABLED', true);

define ('DISPATCHER_USE_REWRITE', true);

define('DISPATCHER_AUTO_ROUTE', false);

define('DISPATCHER_DEFAULT_ENCODING', 'UTF-8');

define('DISPATCHER_SUPPORTED_METHODS', 'GET,PUT,POST,DELETE');

Logging¶

define('DISPATCHER_LOG_ENABLED', false);

define('DISPATCHER_LOG_NAME', 'dispatcher');

define('DISPATCHER_LOG_TARGET', null)

define('DISPATCHER_LOG_LEVEL', 'ERROR')

Folders¶

define('DISPATCHER_CACHE_FOLDER', DISPATCHER_REAL_PATH."cache/");

define('DISPATCHER_SERVICES_FOLDER', DISPATCHER_REAL_PATH."services/");

define('DISPATCHER_PLUGINS_FOLDER', DISPATCHER_REAL_PATH."plugins/");

define('DISPATCHER_TEMPLATES_FOLDER', DISPATCHER_REAL_PATH."templates/");

define('DISPATCHER_LOG_FOLDER', DISPATCHER_REAL_PATH."logs/");

Cache¶

define('DISPATCHER_CACHE_ENABLED', true);

define('DISPATCHER_CACHE_DEFAULT_TTL', 600);

define('DISPATCHER_CACHE_FAIL_SILENTLY', true);

mod_rewrite¶

Dispatcher uses the apache mod_rewrite extension to acquire requests and route those to relative services.

It is also possible to disable this feature and force dispatcher to reply only to requests directed to index.php, settting the DISPATCHER_USE_REWRITE constant to false.

In this case, parameters should be passed as a standard http query-string *key=value” pairs.

Attributes and Parameters¶

TBW

Defining routes¶

To define a new route, the setRoute() method should be invoked before the dispatch().

Syntax of method is:

setRoute( [route], [type], [target], [parameters], [relative] )

So, an example route could be:

$dispatcher->setRoute("helloworld", "ROUTE", "HelloWorld.php", array(), true);

Predefined routes¶

The router supports 2 special routes:

• Landing route “” (empty string)
• Default route “default”

Only the default route is initially defined and lands to a 404 “Service not found” error.

Autorouting¶

If enabled setting constant DISPATCHER_AUTO_ROUTE, dispatcher will try to map requests to service files using file names.

Only files in the DISPATCHER_SERVICES_FOLDER are taken into account.

Conditional routing¶

Thanks to the event subsystem, dispatcher can force or totally override the routing logic.

This snippet (from dispatcher.plugin.test) simply change the target service if a special request header is provided.:

public static function conditional_routing_header($ObjectRoute) {

    $headers = self::getRequestHeaders();

    if ( array_key_exists("C-Conditional-Route", $headers) ) {

        $ObjectRoute
            ->setClass("test_route_second")
            ->setTarget("vendor/comodojo/dispatcher.servicebundle.test/services/test_route_second.php");

    }

    return $ObjectRoute;

}

Router-side attributes inject¶

TBW

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.

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