folded/routing

Routing functions for your web application.

v0.6.0 2020-10-03 11:06 UTC

This package is auto-updated.

Last update: 2021-11-17 10:18:09 UTC


README

Routing functions for your web application.

Packagist License Packagist PHP Version Support Packagist Version Build Status Maintainability TODOs

Summary

About

I created this library to have a standalone, fully featured router, and be able to pull it in any project, that have some existing code or not.

Folded is a constellation of packages to help you setting up a web app easily, using ready to plug in packages.

Features

  • register GET and POST routes actions (using callback)
  • can match the current browsed URL and execute the associated callback
  • can name the registered route to use additional functions like:
    • getting the URL from a route name

Requirements

  • PHP version 7.4+
  • Composer installed

Installation

1. Install the package

On your project root directory, run this command:

composer require folded/routing

2. Bootstrap the router

In the script that is called first, register your routes, and then call for matchRequestedUrl():

use function Folded\addGetRoute;
use function Folded\matchRequestedUrl;

addGetRoute("/", function() {
  echo "Hello world";
});

try {
    matchRequestedUrl();
} catch (Exception $exception) {
  // ...
}

Examples

As this library is using nikic/fast-route internally, refer to this documentation to know all the possibilities regarding constructing the route string.

1. Register a GET route

In this example, we will register a GET route.

use function Folded\addGetRoute;

addGetRoute("/about-us", function() {
  echo "<h1>About us</h1>";
});

2. Register a POST route

In this example, we will register a POST route.

use function Folded\addPostRoute;

addPostRoute("/search/{search}", function($search) {
  // Pulling posts from the database...
  echo "<h1>Search result for $search</h1>";
});

3. Catching url not found exceptions

In this example, we will catch a not found exception.

use function Folded\matchRequestedUrl;
use Folded\Exceptions\UrlNotFoundException;

try {
  matchRequestedUrl();
} catch (Exception $exception) {
  if ($exception instanceof UrlNotFoundException) {
    // Log it, or send it to an error management system...
    // Display a 404 page...
  }
}

4. Catching method not allowed exceptions

In this example, we will catch a method not allowed error (which happens when you browsed an URL, but this url has been registered with another protocol).

use function Folded\matchRequestedUrl;
use Folded\Exceptions\MethodNotAllowedException;

try {
  matchRequestedUrl();
} catch (Exception $exception) {
  if ($exception instanceof MethodNotAllowedException) {
    // Log it, or send it to an error management system...
    // Display a 405 page...
  }
}

5. Naming a route

In this example, we will name a route.

use function Folded\addGetRoute;

addGetRoute("/", function() {
  echo "welcome home";
}, "home.index");

6. Get the URL of a named route

In this example, we will get the name of a named route.

use function Folded\addGetRoute;
use function Folded\getRouteUrl;

addGetRoute("/user/{user}/post/{post}", function($user, $post) {
  echo "User $user posted $post";
}, "user.post.show");

echo getRouteUrl("user.post.show", ["user" => 42, "post" => 1]); // string(15) "/user/42/post/1"

7. Redirect to a named route

In this example, we will redirect to the URL of a named route.

use function Folded\addGetRoute;
use function Folded\redirectToRoute;

addGetRoute("/about-us", function() {
  echo "<h1>About us</h1>";
}, "about-us.index");

redirectToRoute("about-us.index");

By default, a status code 303 will be used alongside the redirection. You can override this behavior by adding the HTTP status code of your choice as second parameter:

use function Folded\addGetRoute;
use function Folded\redirectToRoute;

addGetRoute("/about-us", function() {
  echo "<h1>About us</h1>";
}, "about-us.index");

redirectToRoute("about-us.index", 200);

8. Redirect to an URL

In this example, we will redirect to a plain URL.

use function Folded\redirectToUrl;

redirectToUrl("/about-us");

By default, a status code 303 will be used alongside the redirection. You can override this behavior by adding the HTTP status code of your choice as second parameter:

use function Folded\redirectToUrl;

redirectToUrl("/", 200);

9. Check if the current URL is the given one

In this example, we will check if the current url is the one we have in parameter.

use function Folded\currentUrlIs;

if (currentUrlIs("/")) {
  echo "we are at the home page";
} else {
  echo "we are not at the home page";
}

10. Check if a route matches the current URL

In this example, we will check if a given route name matches the URL.

use function Folded\currentRouteIs;
use function Folded\addGetRoute;

addGetRoute("/about-us", function() {
  echo "<h1>About us</h1>";
}, "about-us.index");

if (currentRouteIs("about-us.index")) {
  echo "this is the about us page";
} else {
  echo "this is not the about us page";
}

Note that if your route contains named parameter, for example /user/{user}, you can use the second parameter to fill the named parameter with the actual value.

use function Folded\currentRouteIs;
use function Folded\addGetRoute;

addGetRoute("/user/{user}", function() {
  echo "<h1>User detail</h1>";
}, "user.show");

if (currentRouteIs("user.show", ["user" => 17])) {
  echo "this is the route /user/17";
} else {
  echo "this is not the route /user/17";
}

Version support

7.3 7.4 8.0
v0.1.0 ✔️
v0.1.1 ✔️
v0.1.2 ✔️
v0.1.3 ✔️
v0.2.0 ✔️
v0.3.0 ✔️
v0.4.0 ✔️
v0.4.1 ✔️
v0.5.0 ✔️
v0.5.1 ✔️
v0.6.0 ✔️