Routing - personaclix/PersonaClixEngine GitHub Wiki

Routing is basically a way of assigning content to a request. When a user attempts to access a page or resource, this is where routing comes in to ensure the right content gets delivered to the end user.

On this page, I will talk you through how to set it up for your application using the Persona Clix Engine.

In your public index.php file, declare a use statement for the Router class at the top of the file below the main engine use statement.

use PersonaClix\Engine\Router;

You can now declare your routes. To keep things organised, I would recommend creating a standalone file for your routes, but you can keep them all in this file if you want to.

Register each route using a static function in the Router class called register(). It takes 4 parameters. The first parameter is the method of the request (GET or POST). The second parameter is the path for the route (/something). The third parameter is a callable action, and the fourth and final parameter is an optional array with additional options for the route.

Standard Registered Routes

These are routes with just the minimum information required to make them work.

Here is an example of a standard registered route...

Router::register('GET', '/page',
	function() {
		echo "Welcome.";
	}
);

Registered Routes with Additional Options

These are routes that have additional options specified that can be retrieved later. The additional options are only Key => Value pairs, which means they are extremely flexible and handy.

For example, let's say you have a site design that appears on all pages/routes of the application. Only the content is controlled by the route's callable action. What if you wanted to access some information outsite of the callable action like for the title of the page to appear in the <title></title> area?

You could set an option called title when registering the route...

Router::register('GET', '/example',
	function() {
		echo "This is an example.";
	},
	[
		'title' => 'Example'
	]
);

Then to retrieve it later, you can access the Router's static getRouteOption() method.

It takes 2 parameters. The first is a string with the name of the option you wish to retrieve the value for, and the second is an optional string for the name of the route you want to retrieve the option from.

Here's an example of it's usage, which works if you followed the previous example.

<title><?php echo Router::getRouteOption('title'); ?></title>

Restricting Routes by Hostname

The host option will restrict the route to certain hostnames/domains. This is useful if you want to use the same installation of your application for multiple sites or to split it up into sub domains.

Here is an example of a registered route with a specified hostname.

Router::register('GET', '/',
	function() {
		echo "Welcome to example.com!";
	},
	[
		'host' => 'www.example.com'
	]
);

Should you wish to specify multiple hostnames, provide an array of strings instead.

Router::register('GET', '/',
	function() {
		echo "Welcome to example.com!";
	},
	[
		'host' => [
			'example.com',
			'www.example.com',
			'example.net',
			'www.example.net'
		]
	]
);

Named Routes

Naming your routes makes it possible to retrieve info about them later. Specify the "name" option with a name you wish.

Router::register('GET', '/about',
	function() {
		echo "All about our website!";
	},
	[
		'name' => 'about_page'
	]
);

Then from inside another route, create a hyperlink to the previous route, and use Router's static getRouteURL() method with the route's name to get a full URL to that route.

Router::register('GET', '/',
	function() {
		echo '<a href="' . Router::getRouteURL('about_page') . '">About Page</a>';
	}
);

Go to the route you just created a hyperlink in, and you should now see a hyperlink to the other route, and clicking on it will take you to that route.

Route Info

Use Router's static getRouteInfo() method and pass in the name of the route you want info on.

$about_page = Router::getRouteInfo('about_page');

Please note: The above will only work if you have specified a name as one of the route options.

To get info on the current route, call the method without a parameter.

$current_page = Router::getRouteInfo();

The method will return an array with all info related to the route.

Inside your public index.php file, make sure you have required in the file containing your routes if you used a standalone file. This is not required if you just kept them in the index.php file.

Now you need to try to access the requested route. The easiest way is to use PHP's call_user_func() function and pass in the Router class's static method route(). It will call the callable action associated with the current route, or if the route cannot be found, will return nothing, so you might want to check if the action is callable before calling it.

Here is an example of this...

$route_action = Router::route();

if( is_callable( $route_action ) ) {
	call_user_func( $route_action );
} else {
	echo "Route cannot be found!";
}

That's about all you need to do for routing.