SimpleRouter image

Module Description

The SimpleRouter module can be used to provide URL routing in your Scriptor application. URL routing allows you to configure an application to accept request URLs that do not map to physical files. The router can be used to map URL patterns to a specific handler. The handler can be a closure as well as a controller method that processes the request.

The SimpleRouter is perfectly suited to create REST APIs or for using your Scriptor application as a kind of headless CMS.

Install Instruction

Clone module in your site/modules/ directory or download the zip file, unzip it and upload the complete folder SimpleRouter to your server in the directory site/modules/.

Open your custom.scriptor-config.php file and add the following configuration to the modules section:

'modules' => [
      ...
        'SimpleRouter' => [
            'menu' => '',
            'position' => 1,
            'active' => true,
            'auth' => true,
            'path' =>  'modules/SimpleRouter/Route',
            'class' => 'Route',
            'display_type' => [
            ],
            'description' => 'This is a simple URL Router module for Scriptor CMS.'
        ]
    ...

Now create a file named _ext.php, in site/themes/<your-theme>/ directory and paste in this source code:

<?php
use Scriptor\Scriptor;
Scriptor::load(IM_ROOTPATH.'site/modules/SimpleRouter/Route.php');
include '_routes.php';
exit;

Next, Create the _routes.php file in the same directory.

That's it. You can use your router at this point. All Scriptor routes are defined in your _routes.php file located in the site/themes/<your-theme>/ directory. This file is automatically loaded into your application by _ext.php.

Usage

Let's look at a few more examples in the _route.php file to see how easy it is to create custom routes for your application.

To add new routes to your application, you can use the Route::add() method. This method can contain up to three parameters: 1. your route (path), 2. closure or controller method to be called if the route matched, 3. any HTTP verb.

_routes.php:

<?php

use Scriptor\Route;

// Add a new route to your Scriptor application
Route::add('/info', function() {
    echo 'This is a simple URL Router module for Scriptor CMS.';
}, 'GET');

// Execute router
Route::run();

More examples

Sometimes you may need to register a route that responds to multiple HTTP verbs. Below is a route that matches both GET and POST methods:

Route::add('/info', function() {
    echo 'This is a simple URL Router module for Scriptor CMS.';
}, ['GET', 'POST']);

Sometimes you may need to capture a parameter (e.g. the ID of a user) from the URL. You can do this by defining route parameters:

Route::add('/users/{id}', function($id) {
    echo 'This is the user id: '. (int) $id;
}, 'GET');

You can define as many route parameters as your need:

Route::add('/users/{user}/posts/{post}', function($user_id, $post_id) {
    echo 'This is the user id: '. (int) $user_id .' & post id: '.(int) $post_id;
}, 'GET');

Instead of the closure, you can also call a controller method (note, you have to create a controller module first):

Route::add('/users/{user}/posts/{post}', 
    'Scriptor\Controllers\YourModule::yourMethod', 
    'GET'
);

Route Groups

Route groups allow you to combine a variety of routes of a certain method:

// Groups all routes of the POST method:
Route::processor()->matchMethod('POST', function() {

    Route::add('/contact-form', function() {
        echo 'Post contact form data ...';
    }, 'POST');

    Route::add('/subscribe-form', function() {
        echo 'Post subscription form data ...';
    }, 'POST');

    ...
});

Special methods

Add a method that will be executed if none of the specified routes matches. Usually a message 404 not found is displayed:

// Add a 404 not found function
Route::routeNotMatch(function($path) {
    header('HTTP/1.0 404 Not Found');
    echo '<h4>Error 404</h4>';
    echo '<p>The requested path "'.$path.'" was not found!</p>';
});

Sometimes the specified route matches but not the HTTP verb, in that case you can define a method that would send a 405 response:

// Add a 405 method
Route::methodNotAllowed(function($uri, $method) {
    header('HTTP/1.0 405 Method Not Allowed');
    echo '<h4>Error 405</h4>';
    echo '<p>The requested URI "'.$uri.'" exists, but the request method "'.
          $method.'" is not allowed!</p>';
});

Requirements

Compatible with Scriptor: 1.4.11 +
PHP 8.0 +
Author: Bigin
GitHub repo
Last Updated: 2021-01-12
SimpleRouter: 1.0.0