Router

The router is the subsystem which takes the url of the request and find which content to serve back.

Most of the time it works undercover, using the data provided by the “Menu Manager” of the GUI. However, from times to times, you may want to use it directly.

Route data

A route is made of 4 elements:

- the pattern is matched against the URL to determine if the Route matches the request (it’s a regex)
- the module loosely correspond to the plugin name (it can be empty)
- the catcher is the controller which will implement the route
- the defaults are values used when the corresponding parameter is not provided in the request URL

Routes are automatically created when a node is created in the GUI. For example, a plugin “mysite” containing a node which alias is “mypage” will generate a route like this:

array(
    'pattern' => 'mypage',
    'module' => 'mysite',
    'catcher' => $nodeID,
    'defaults' => null
}

It will then be available with two URLs: /mypage and /mysite/mypage.

Route matching

When request is received, the corresponding controller is found by scanning the routes registry, in reverse order. If a module is provided in the URL, only the corresponding routes are scanned; if not, we first scan routes with no modules, then all routes with modules. This means you can override a route created for a node by registering a route with the same pattern and no module :

$this->router->addRoute($this, '/mypage');

will override this:

$this->router->addRoute($this, '/mypage', 'mysite);

Registering as a new route

The first case is when you want to add a valid url without creating a node in the “Menu Manager” GUI. You can do that using the PHPDS_deferred feature. This code is from the StandardLogin plugin:

/**
 * This very simple implementation of deferred provides the "/logout" virtual URL
 *
 * @category PHP
 * @package  StandardLogin
 * @author   greg <greg@phpdevshell.org>
 * @license  http://www.gnu.org/copyleft/gpl.html GNU General Public License
 * @link     http://www.phpdevshell.org
 */
class LOGIN_logoutDeferred extends PHPDS_dependant implements iPHPDS_deferred
{
    /**
     * Install the route
     *
     * @return void
     */
    public function construct()
    {
        $this->router->addRoute($this, '/logout');
    }

   /**
     * Actual logout and go back to the default page;
     *
     * @return int
     */
    public function reduce()
    {
        $this->factory('StandardLogin')->clearLogin();
        return 0;
    }

   /**
     * We do nothing here
     *
     * @param mixed $controller_result whatever was returned by the controller's run
     *
     * @return void
     */
    public function success($controller_result = null)
    {
    }

   /**
     * Part to execute if the action triggered has failed
     *
     * @return void
     */
    public function failure($something = null)
    {
    }
}

/* @var PHPDS $this */
$this->PHPDS_classFactory()->registerClass('#LOGIN_logoutDeferred', 'LOGIN_logoutDeferred', 'StandardLogin');

The class is registered as auto-intanciated. When its constructor is called, it registers itself to handle the “/logout” url. So if the request matches this url, the reduce() method is called allowing the code to actually answer to the given url.

Adding a route to the default routes