The Jaws_URLMapper core subsystem

Package: Jaws API File: Jaws/URLMapper.php Object: Jaws::$Maps

URL maps are a very important part of any web application as they route the user request to the proper handler. The Jaws URL mapper aims to be efficient, flexible and convenient.

How are URL maps handled

The request

In an URL, the request part is after the script. I.e., for the URL, blog/show/Blog-entry is the request.

The root map

At the base of all maps is the root map, accessible with the Jaws::$Maps->getRootMap() method. It is a Jaws_URLMapper_Map object, like all the other maps. This map is a dummy map as it is only used to contain all the other maps.

Map number

Each map has its own map number associated with it. The map numbers work much like firewall rule numbers. The map with the lowest map number, usually 0, is evaluated first and, if it is matched, all the other maps with bigger map numbers are not tested. The map number can be accessed with the Jaws_URLMapper_Map::getNum() method.

Matching expression

To match an URI with a particular map, Perl-style regular expressions are used. The complete URI is always matched against the maps. The matching expression of a map can be set with the Jaws_URLMapper_Map::setExpression() method and accessed with the Jaws_URLMapper_Map::getExpression() method.


Each map can have an arbitrary number of children maps (also named submaps). When a map is matched and the map has submaps, the submaps are tested until a match is found or, if no match is found, the action of the parent map is taken (if a map has submaps, the action of the map can be considered a default action). The only case where this is not true is with the root map. To setup a default action for the root map (much likely error 404), a match-all map with the biggest map number must be set up.

Instead of having a unidimensional array containing all the maps, it was decided to use a tree. This means a substantial decrease in processing. Regular expression is costly so this will definitely help performance.

Where are the maps stored ?

The maps are stored using a Jaws_StaticConfig object in file cnf/maps.php.

Access a map

As previously mentioned, the root map is accessed with the Jaws::$Maps->getRootMap() method. All the other maps are accessed with a call to the Jaws_URLMapper_Map::get(integer $num) method on the parent map. In exemplis:

echo Jaws::$Maps->getRootMap()->get(0)->get(2)->getExpression();

This will print the matching expression of submap '2' of map '0'.

Access all submaps

To access all the submaps of a map, you can use the Jaws_URLMapper_Map::getSubmaps() function. In exemplis:

foreach (Jaws::$Maps->getRootMap()->getSubmaps() as $map) {
    echo $map->getExpression();

Add a submap

To add a submap, the Jaws_URLMapper_Map::add(string $map, string $action, [integer $num]) method is used. If $num is not specified, the next biggest available submap number is used. In exemplis:

Jaws::$Maps->getRootMap()->add('/^blog/', 'Blog');

This adds a submap to the root map that matches every request that starts with blog and that calls the Blog gadget when encountered. The add() method returns the map number of the new map.

Remove a submap

To remove a submap, the Jaws_URLMapper_Map::remove(integer $num) method is used. In exemplis:, if you want to delete the submap with map number 12:


Change a submap's map number

To remove a submap, the Jaws_URLMapper_Map::move(integer $num, integer $newnum) method is used. If there is a collision with an existing map, the change will fail. In exemplis, if you want to change the map number of the submap with map number 12 to 13:

Jaws::$Maps->getRootMap()->move(12, 13);

Change other map settings

There exist specific methods to change and access map settings:

  • Matching expression: Jaws_URLMapper_Map::setExpression(string $expr) / Jaws_URLMapper_Map::getExpression()
  • Action: Jaws_URLMapper_Map::setAction(string $action) / Jaws_URLMapper_Map::getAction()

Save the changes

Everytime a change is made to a map, it should be saved with the Jaws_URLMapper::save() method, usually accessed through:


< Click here to go back to the Core subsystems section