Routing

This feature could very well be the most important feature of the entire application you're developing. It defines what happens when users access certain areas of the application.

Load the Route class

Inside your public index.php file, anywhere after the autoloader, define a use statement.

use ProtonSite\Route;

Register a Route

The register method takes 4 parameters, a String for the method, a String for the URI, a callable action, and an optional Key => Value array of additional options. The URI should be without any leading slash.

// Example of a GET Route for the root/home of the app.
Route::register('GET', '', function() {
    // Put any PHP code here.
});

// Example of a GET Route for /example.
Route::register('GET', 'example', function() {
    // Put any PHP code here.
});
 
// Example of a POST route for /example.
Route::register('POST', 'example', function() {
    // Put any PHP code here.
});

GET and POST Routes

There are aliases of the above register() method called get() and post(). These accept the same parameters, but without the method parameter, and do the exact same as register(). It's personal preference which API you prefer.

// Example of a GET Route.
Route::get('example', function() {
    // Put any PHP code here.
});

// Example of a POST Route.
Route::post('example', function() {
    // Put any PHP code here.
});

Registering Additional Options

The register(), get(), and post() methods accept an optional parameter at the end, a Key => Value array of additional options. This can be used to set any information you wish for processing later.

Let's set a host option so we can set the hostname/domain for the route, as a further limitation. This will allow us to use the same URIs if we want to.

Route::register('GET', '', function() {
    // Put any PHP code here.
}, ['host' => 'www.protonsite.com']);

Registering Multiple Hostnames/Domains

Added in commit 79ee6cfae1ee9d430692abd4db2bfed20712d8ef

Sometimes you may have multiple domains for the one website. Set them as an array.

Route::register('GET', 'page', function() {
    // Content Here
}, ['host' => ['domain.com', 'domain.net']]);

Fetching Routes

Search for the routes you need. The more information you provide, the narrower the results will become. A bit like searching the internet.

It takes only one parameter. A Key => Value array of options related to the routes you wish to find, and it will return an array containing all the routes it finds.

// Fetch all the routes that have their method set to GET.
$route = Route::fetch([
    'method' => 'GET'
]);

Generating Full URLs for Linking to Routes

Added in commit 6da6f0946d5dfef19dc5c032d0594f5622763891

If you use a single ProtonSite installation for multiple websites with different hostnames/domains, you will want to make sure your links work correctly when navigating between them.

The url() method takes 2 parameters, a Key => Value array of options to use when finding the route (similar to the above fetch() method), and an optional HTTPS parameter. Set it to on to force the returned URL to use HTTPS, set to auto to use the same as the current URL, or anything else to force HTTP only. Default is auto.

A simple example is as follows...

// URL to Information Page
echo Route::url(['name' => 'info']);

Routing the Request

When a user accesses your web app, they will request a specific part of that app, e.g. /example. This is the URI you defined earlier when you registered your route. It is passed to the app via Apache's MOD_REWRITE in your .htaccess file.

// Find the route that matches the method and the URI.
$route = Route::fetch([
    'method' => $_SERVER['REQUEST_METHOD'],
    'uri' => isset( $_GET['uri'] ) ? $_GET['uri'] : ''
]);

If that code next to the URI part looks new to you, it's a shorthand IF statement to check if the GET variable URI exists and uses it, otherwise it will set an empty string.

Let's fetch a route with the additional option we set earlier.

// Find the route that matches the method, host, and the URI.
$route = Route::fetch([
    'method' => $_SERVER['REQUEST_METHOD'],
    'host' => $_SERVER['HTTP_HOST'],
    'uri' => isset( $_GET['uri'] ) ? $_GET['uri'] : ''
]);

WARNING: The host option in this case will have to be set for all routes if you use it as part of the main routing operation, otherwise you will get errors.

Now to call/execute the route's action.

// Call/Execute the Route's Action
if( is_callable( $route['action'] ) ) {
    call_user_func( $route['action'] );
} else {
    // Route does not exist. Set 404 status code and display a message.
    header("HTTP/1.0 404 Not Found");
    echo "404 Not Found";
}

Routing Complete

You have now successfully set up routing. Give it a test to see if it works by visiting one of your routes in your browser after uploading to your server. Happy routing!