Router

Pair framework: Router class

The Router class takes care of recognizing the requested module, the action to be performed and any additional parameters.

Pair URLs are search engine friendly by default and very simple to understand.

Standard routes

URLs follow this pattern:

/module/action/parameter_1/parameter_2/...

So, the first parameter immediately after the project root will be the exact name of the module you want to use.

The second parameter is the action to be invoked in the module Controller in the previous paragraph. It is good to remember that the suffix Action must be added to the name of the function in the controller to be executed.

For example, if your application base root is domain.com, by calling this URL in the browser:

http://domain.com/persons/listAll

Pair will try to run the listAllAction function on the controller of the persons module:

<?php

class PersonsController extends Pair\Core\Controller {

	public function listAllAction() {
		// code
	}

}

By calling a URL that refers to a non-existent function, Pair will display a Resource not found error message to the connected user.

The other parameters that follow /module/action schema are stored in the Router singleton and can be accessed via a numerical positioning index.

An example will clarify this explanation. This is the URL of the request to Pair:

http://domain.com/persons/edit/3/24

To print each of the parameters indicated in the URL, you can use this code:

<?php

use Pair\Core\Router;

$router = Router::getInstance();

// persons
print $router->module;

// edit
print $router->action;

// 3
print $router->getParam(0);

// 24
print $router->getParam(1);

Special prefixes

You can indicate to the application that you want to execute ajax requests or others that require not to add the layout and the graphic template. To do this, you can set immediately after the base address of the application, the /ajax or /raw prefix.

/ajax

The `ajax` prefix is used for asynchronous calls from a web page.

/raw

The `raw` prefix is used to receive raw data without interaction with web pages, for instance by consuming API. An ajax request is implicitly raw.

When /ajax or /raw prefix is present, the position of the module and the action are available at the same position. The following URL calls the getAction() method on the person’s controller:

http://domain.com/ajax/persons/get/4

The request runs in the controller and send back raw data via AJAX:

<?php

use Pair\Core\Controller;
use Pair\Core\Router;
use Pair\Helpers\Utilities;

class PersonsController extends Controller {

	public function getAction() {

		// get the first available parameter (zero index), that equals to 4
		$personId = Router::get(0);

		// load the person with primary-key = 4
		$person = new Person($personId);

		// send out the loaded Person object as JSON
		Utilities::printJsonData($person);

	}
}

After executing the edit method in the controller and returning the processed data in the corresponding Model, the View will not be executed.

The following paragraph shows how to set Pair’s custom routes, which will be translated according to the rules written in a special file.

Custom routes

When a module is invoked, Pair searches for a file called routes.php in the module root folder. If found, read definition of custom routes.

Custom action name

Let’s start by creating a file called routes.php in the root directory of the persons module. The complete path to the file will then be /myproject/modules/persons/routes.php. This will be its content:

<?php

// set namespace
use Pair\Core\Router;

// add a custom route
Router::addRoute('/modifyPerson', 'edit');

When invoking the persons/modifyPerson URL it routes the request to the controller’s editAction (edit name + Action suffix) function.

The first parameter, the path, must start with the slash symbol.

Custom parameter name

In a custom route, you can indicate an alternative name for an action and define the parameters name by preceding it with the colon char :.

For example, by declaring the rule in the routes.php file:

Router::addRoute('/modifyPerson/:personId', 'edit');

and by calling this URL:

http://domain.com/persons/modifyPerson/33

the editAction function will be invoked in the controller of the subject module and the value 33 will be available in the singleton Router parameter personId:

<?php

use Pair\Core\Controller;
use Pair\Core\Router;

class PersonsController extends Controller {

	public function editAction() {
	
		// 33
		print Router::get('personId');

	}
	
}

Regular expression parameter

When you need to specify the type of characters that are valid for a parameter (and then accept a route), you can follow its name with a regular expression in parentheses. Eg:

// accept call by /persons/editPerson/123 (or any number)
Router::addRoute('/editPerson/:id([\d]+)', 'edit');

The regular expression [\d] indicates that a number is accepted. The following + sign adds the constraint that at least one number is present but there may be others to follow. Because of this rule, the above route will be executed only when the parameter consists of one or more numbers.

Therefore, it will not be performed in other cases, for example:

http://domain.com/persons/editPerson/12a

Or if the parameter does not contain the expected number:

http://domain.com/persons/editPerson/

This allows you to use a part of the URL in common between multiple rules and let the parameter choose the execution path. Here is an example:

<?php

// edit person by ID
Router::addRoute('/editPersonById/:id([0-9]+)', 'edit');

// edit person by username min 3 chars
Router::addRoute('/editPersonByName/:username([a-zA-Z_]{3,})', 'edit');