joomla/router

Joomla Router Package

The Router Package

, _(*1)

The standard router

Construction

The standard router optionally takes a Joomla\Input\Input object. If not provided, the router will create a new Input object which imports its data from $_REQUEST., _(*2)

<?php
use Joomla\Router\Router;

// Create a default web request router.
$router = new Router;

// Create a router by injecting the input.
$router = new Router($application->getInput());

Adding maps

The purpose of a router is to find a controller based on a routing path. The path could be a URL for a web site, or it could be an end-point for a RESTful web-services API., _(*3)

The addMap method is used to map at routing pattern to a controller., _(*4)

<?php
$router = new Router;
$router->addMap('/article/:article_id', '\\Acme\\ArticleController')
    ->addMap('/component/*', '\\Acme\\ComponentFrontController');

Matching an exact route.

<?php
$router->addMap('/articles', 'ArticlesController');
$controller = $router->getController('/articles');

In this case there is an exact match between the route and the map. An ArticlesController would be returned by getController., _(*5)

Matching any segment with wildcards

<?php
$router->addMap('/articles/*', 'ArticlesController');
$controller = $router->getController('/articles/foo/bar');

In this case, the router will match any route starting with "/articles/". Anything after that initial prefix is ignored and the controller would have to inspect the route manually to determine the last part of the route., _(*6)

<?php
$router->addMap('/articles/*/published', 'PublishedController');
$controller = $router->getController('/articles/foo/bar/published');

Wildcards can be used within segments. In the second example if the "/published" suffix is used, a PublishedController will be returned instead of an ArticlesController., _(*7)

Matching any segments to named variables

<?php
$router->addMap('/articles/*tags', 'ArticlesController');
$controller = $router->getController('/articles/space,apollo,moon');

A star * followed by a name will store the wildcard match in a variable of that name. In this case, the router will return an ArticlesController but it will inject a variable into the input named tags holding the value of anything that came after the prefix. In this example, tags will be equal to the value "space,apollo,moon"., _(*8)

<?php
$controller = $router->getController('/articles/space,apollo,moon/and-stars');

Note, however, all the route after the "/articles/" prefix will be matched. In the second case, tags would equal "space,apollo,moon/and-stars". This could, however, be used to map a category tree, for example:, _(*9)

<?php
$controller = $router->getController('/articles/*categories', 'ArticlesController');
$controller = $router->getController('/articles/cat-1/cat-2');

In this case the router would return a ArticlesController where the input was injected with categories with a value of "cat-1/cat-2"., _(*10)

If you need to match the star character exactly, back-quote it, for example:, _(*11)

<?php
$router->addMap('/articles/\*tags', 'ArticlesTagController');

Matching one segment to a named variable

<?php
$router->addMap('/articles/:article_id', 'ArticleController');
$controller = $router->getController('/articles/1');

A colon : followed by a name will store the value of that segment in a variable of that name. In this case, the router will return an ArticleController injecting article_id into the input with a value of "1"., _(*12)

Note that a route of /articles/1/like would not be matched. The following cases would be required to match this type of route:, _(*13)

<?php
$router->addMap('/articles/:article_id/like', 'ArticleLikeController');
$router->addMap('/articles/:article_id/*action', 'ArticleActionController');

If you need to match the colon character exactly, back-quote it, for example:, _(*14)

<?php
$router->addMap('/articles/\:tags', 'ArticlesTagController');

Installation via Composer

Add "joomla/router": "~1.0" to the require block in your composer.json and then run composer install., _(*15)

{
    "require": {
        "joomla/router": "~1.0"
    }
}

Alternatively, you can simply run the following from the command line:, _(*16)

composer require joomla/router "~1.0"