dorkodu/superpage

Superpage is a simple, fast and lightweight router for PHP apps.

Superpage

Superpage is a simple, fast and lightweight, which means an awesome router for PHP apps!

Features

• Supports GET, POST, PUT, DELETE, OPTIONS, PATCH and HEAD request methods
• Static Route Patterns
• Dynamic Route Patterns:
  • Dynamic PCRE-based Route Patterns
  • Dynamic Placeholder-based Route Patterns
• Redirecting
• Sub-routing / Mounting Routes
• Optional Route Subpatterns
• Supports X-HTTP-Method-Override header
• Custom 404 handling
• After Router Middleware / After App Middleware (Finish Callback)
• Works fine in subfolders

Prerequisites/Requirements

• PHP 7.2+ or greater
• URL Rewriting

Installation

You can require Dorkodu\Superpage\Superpage.php class, or use an autoloader like Loom or Composer.

Demo

A demo is included in the demo sub-folder. Serve it using your favorite web server, or using PHP 5.4+'s built-in server by executing php -S localhost:8080 on the shell. A .htaccess for use with Apache is included.

Usage

• Create an instance of \Dorkodu\Superpage\Superpage.
• Define your routes.
• Then run Superpage!

/*
 * Require your autoloader script, 
 * We use Loom for that :) You can use Composer too.
 */
require __DIR__ . '/loot/loom-weaver.php';

# Create Router instance
$superpage = new \Dorkodu\Superpage\Superpage();

# Define routes
$superpage->to('/', 'GET', function() { 
	echo "Home";
});

$superpage->get('/about', function() { 
	echo "About";
});

# Run it!
$superpage->run();

Routing

Hook routes (a combination of one or more HTTP methods and a pattern) using
$superpage->to(pattern, method(s), callback) :

$superpage->to('...pattern', 'GET|POST|...[METHOD]', function() { ··· });

Superpage supports GET, POST, PUT, PATCH, DELETE, HEAD (see note), and OPTIONS HTTP request methods. Pass in a single request method, or multiple request methods separated by |.

When a route matches against the current URL (e.g. $_SERVER['REQUEST_URI']), the attached route handling function will be executed. The route handling function must be a callable. Only the first route matched will be handled. When no matching route is found, a 404 handler will be executed.

Routing Shorthands

Shorthands for single request methods are provided :

$superpage->get('pattern', function() { ··· });
$superpage->post('pattern', function() { ··· });
$superpage->put('pattern', function() { ··· });
$superpage->delete('pattern', function() { ··· });
$superpage->options('pattern', function() { ··· });
$superpage->patch('pattern', function() { ··· });

You can use this shorthand for a route that can be accessed using any method :

$superpage->any('pattern', function() { ··· });

Redirecting

You can redirect a pattern to another absolute URI. This is what we choose for simplicity, may add parameters or pattern-to-pattern matches in the future. If you so desire, let us know by opening an issue. Maybe we can collaborate!

/*
 * 3rd parameter is request method, defaults to 'GET'
 * 4th parameter is status code, defaults to 301
 */ 
$superpage->redirect('pattern', '/redirect-to', $method, $statusCode);

Note : Routes must be defined before $superpage->run(); is being called.

Note : There is no shorthand like head() as Superpage will internally re-route such requests to their equivalent GET request, in order to comply with RFC2616 (see note).

Route Patterns

Route Patterns can be static or dynamic:

• Static Route Patterns

  They contain no dynamic parts and must match exactly against the path part of the current URL.

• Dynamic Route Patterns

  They contain dynamic parts that can vary per request. The varying parts are named subpatterns and are defined using either Perl-compatible regular expressions (PCRE) or by using placeholders

Static Route Patterns

A static route pattern is a regular string representing a URI. It will be compared directly against the path part of the current URL.

Example : /about

Usage Example :

// This route handling function will only be executed when visiting http(s)://www.example.org/about
$superpage->get('/about', function() {
    echo 'About Page Contents';
});

Dynamic PCRE-based Route Patterns

This type of Route Patterns contain dynamic parts which can vary per request. The varying parts are named subpatterns and are defined using regular expressions.

Examples:

• /user/(\d+)
• /blog/(\w+)

Commonly used PCRE-based subpatterns within Dynamic Route Patterns are:

• \d+ = One or more digits (0-9)
• \w+ = One or more word characters (a-z 0-9 _)
• [a-z0-9_-]+ = One or more word characters (a-z 0-9 _) and the dash (-)
• .* = Any character (including /), zero or more
• [^/]+ = Any character but /, one or more

Note: The PHP PCRE Cheat Sheet might come in handy.

The subpatterns defined in Dynamic PCRE-based Route Patterns are converted to parameters which are passed into the route handling function. Prerequisite is that these subpatterns need to be defined as parenthesized subpatterns, which means that they should be wrapped between parens:

// Bad
$superpage->get('/hello/\w+', function($name) {
    echo 'Hello ' . htmlentities($name);
});

// Good
$superpage->get('/hello/(\w+)', function($name) {
    echo 'Hello ' . htmlentities($name);
});

Note: The leading / at the very beginning of a route pattern is not mandatory, but recommended.

When multiple subpatterns are defined, the resulting route handling parameters are passed into the route handling function in the order they are defined in:

$superpage->get('/movies/(\d+)/photos/(\d+)', function($movieId, $photoId) {
    echo 'Movie #' . $movieId . ', photo #' . $photoId;
});

Dynamic Placeholder-based Route Patterns

This type of Route Patterns are the same as Dynamic PCRE-based Route Patterns, but with one difference: they don't use regex to do the pattern matching but they use the more easy placeholders instead. Placeholders are strings surrounded by curly braces, e.g. {name}. You don't need to add paren's around placeholders.

Examples :

• /movies/{id}
• /profile/{username}

Placeholders are easier to use than PRCEs, but offer you less control as they internally get translated to a PRCE that matches any character (.*).

$superpage->get('/user/{userId}/post/{postId}', function($userId, $postId) {
    echo 'User #' . $userId . ', post #' . $postId;
});

Note: the name of the placeholder does NOT NEED TO MATCH with the name of the parameter that is passed into the route handling function :

$superpage->get('/movies/{foo}/photos/{bar}', function($movieId, $photoId) {
    echo 'Movie #' . $movieId . ', photo #' . $photoId;
});

Optional Route Subpatterns

Route subpatterns can be made optional by making the subpatterns optional by adding a ? after them. Think of blog URLs in the form of /blog(/year)(/month)(/day)(/slug):

$superpage->get(
    '/blog(/\d+)?(/\d+)?(/\d+)?(/[a-z0-9_-]+)?',
    function($year = null, $month = null, $day = null, $slug = null) {
        if (!$year) { echo 'Blog overview'; return; }
        if (!$month) { echo 'Blog year overview'; return; }
        if (!$day) { echo 'Blog month overview'; return; }
        if (!$slug) { echo 'Blog day overview'; return; }
        echo 'Blogpost ' . htmlentities($slug) . ' detail';
    }
);

The code snippet above responds to the URLs /blog, /blog/year, /blog/year/month, /blog/year/month/day, and /blog/year/month/day/slug.

Note: With optional parameters it is important that the leading / of the subpatterns is put inside the subpattern itself. Don't forget to set default values for the optional parameters.

The code snipped above unfortunately also responds to URLs like /blog/foo and states that the overview needs to be shown - which is incorrect. Optional subpatterns can be made successive by extending the parenthesized subpatterns so that they contain the other optional subpatterns: The pattern should resemble /blog(/year(/month(/day(/slug)))) instead of the previous /blog(/year)(/month)(/day)(/slug):

$superpage->get('/blog(/\d+(/\d+(/\d+(/[a-z0-9_-]+)?)?)?)?', function($year = null, $month = null, $day = null, $slug = null) {
    # ...
});

Note: It is highly recommended to always define successive optional parameters.

To make things complete use quantifiers to require the correct amount of numbers in the URL:

$superpage->get('/blog(/\d{4}(/\d{2}(/\d{2}(/[a-z0-9_-]+)?)?)?)?', function($year = null, $month = null, $day = null, $slug = null) {
    # ...
});

Sub-routing / Mounting Routes

Use $superpage->mount($baseroute, $callback) to mount a collection of routes onto a sub-route pattern. The sub-route pattern is prefixed onto all following routes defined in the scope.

e.g. Mounting a callback $callback onto /people will prefix /people onto all following routes.

$superpage->mount('/people', function() use ($superpage) {
    # will result in '/people/'
    $superpage->get('/', function() {
        echo 'people overview';
    });
  
    # will result in '/people/id'
    $superpage->get('/(\d+)', function($id) {
        echo 'person id : ' . htmlentities($id);
    });

});

Nesting of sub-routes is possible, just define a second $superpage->mount() in the callable that's already contained within a preceding $superpage->mount().

Custom "404 Not Found"

The default 404 handler responses with a 404 status code and exits.

You can override this default 404 handler by using $superpage->fallback(callable);

$superpage->fallback(function() {
    header('HTTP/1.1 404 Not Found');
    # ... do something special here
});

The 404 handler will be executed when no route pattern was matched to the current URL.

💡 You can also manually trigger the 404 handler by calling $superpage->notFound()

$superpage->get('/([a-z0-9-]+)', function($id) use ($superpage) {
    if (!Posts::exists($id)) {
      $superpage->notFound();
      return;
    }
    # …
});

After Router Middleware / Run Callback

Run one (1) middleware function, name the After Router Middleware (in other projects sometimes referred to as after app middlewares) after the routing was processed. Just pass it along the $superpage->run() function. The run callback is route independent.

$superpage->run(function() { ... });

Note : If the route handling function has exit()ed the run callback won't be run.

Overriding the request method

Use X-HTTP-Method-Override to override the HTTP Request Method. Only works when the original Request Method is POST. Allowed values for X-HTTP-Method-Override are PUT, DELETE, or PATCH.

Subfolder support

Out-of-the box Superpage will run in any (sub)folder you place it into … no adjustments to your code are needed. You can freely move your entry script index.php around, and the router will automatically adapt itself to work relatively from the current folder's path by mounting all routes onto that basePath.

Say you have a server hosting the domain www.example.org using public_html/ as its document root, with this little entry script index.php:

$superpage->get('/', function() { echo 'Index'; });
$superpage->get('/hello', function() { echo 'Hello!'; });

• If your were to place this file (along with its accompanying .htaccess file or the like) at the document root level (e.g. public_html/index.php), Superpage will mount all routes onto the domain root (e.g. /) and thus respond to https://www.example.org/ and https://www.example.org/hello.

• If you were to move this file (along with its accompanying .htaccess file or the like) into a subfolder (e.g. public_html/demo/index.php), Superpage will mount all routes onto the current path (e.g. /demo) and thus repsond to https://www.example.org/demo and https://www.example.org/demo/hello. There's no need for $superpage->mount(…) in this case.

Disabling subfolder support

In case you don't want Superpage to automatically adapt itself to the folder its being placed in, it's possible to manually override the basePath by calling setBasePath(). This is necessary in the (uncommon) situation where your entry script and your entry URLs are not tightly coupled (e.g. when the entry script is placed into a subfolder that does not need be part of the URLs it responds to).

// Override auto base path detection
$superpage->setBasePath('/');

$superpage->get('/', function() { echo 'Index'; });
$superpage->get('/hello', function() { echo 'Hello!'; });

$superpage->run();

If you were to place this file into a subfolder (e.g. public_html/some/sub/folder/index.php), it will still mount the routes onto the domain root (e.g. /) and thus respond to https://www.example.org/ and https://www.example.org/hello (given that your .htaccess file – placed at the document root level – rewrites requests to it)

Integration with other libraries

Integrate other libraries with Superpage by making good use of the use keyword to pass dependencies into the handling functions.

$view = new \Foo\Bar\View();

$superpage->get('/', function() use ($view) {
    $view->load('home.view');
    $view->setdata(array(
        'name' => 'Berk Cambaz'
    ));
});

$superpage->run(function() use ($view) {
    $view->display();
});

Given this structure it is still possible to manipulate the output from within the After Router Middleware

A note on working with PUT

There's not a superglobal for PUT as $_PUT in PHP.
You must fake it :

$superpage->put('/movies/(\d+)', function($id) {
    # Fake $_PUT
    $_PUT  = array();
    parse_str(file_get_contents('php://input'), $_PUT);
    # ...
});

A note on making HEAD requests

When making HEAD requests all output will be buffered to prevent any content trickling into the response body, as defined in RFC2616 (Hypertext Transfer Protocol -- HTTP/1.1):

The HEAD method is identical to GET except that the server MUST NOT return a message-body in the response. The meta data contained in the HTTP headers in response to a HEAD request should be identical to the information sent in response to a GET request. This method can be used for obtaining meta data about the entity implied by the request without transferring the entity-body itself. This method is often used for testing hypertext links for validity, accessibility, and recent modification.

To achieve this, Superpage will internally re-route HEAD requests to their equivalent GET request and automatically suppress all output.

Tests

Superpage ships with unit tests using Seekr.

• To test the Superpage library, run SuperpageTest.php from PHP CLI.

  Like php test/SuperpageTest.php, if you are in the root project folder.

Acknowledgements

Superpage is heavily inspired by bramus/router. I've stolen the useful docs structure from there.

Even it works well, we wanted a simpler approach.

License

Superpage is released under the MIT public license. See the LICENSE for details.