README

Routing functions for your web application.

Summary

About
Features
Requirements
Installation
Examples
Version support

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.

folded/action: A way to organize your controllers for your web app.
folded/config: Configuration utilities for your PHP web app.
folded/crypt: Encrypt and decrypt strings for your web app.
folded/exception: Various kind of exception to throw for your web app.
folded/history: Manipulate the browser history for your web app.
folded/http: HTTP utilities for your web app.
folded/orm: An ORM for you web app.
folded/request: Request utilities, including a request validator, for your PHP web app.
folded/session: Session functions for your web app.
folded/view: View utilities for your PHP web app.

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
2. Register a POST route
3. Catching url not found exceptions
4. Catching method not allowed exceptions
5. Naming a route
6. Get the URL of a named route
7. Redirect to a named route
8. Redirect to an URL
9. Check if the current URL is the given one
10. Check if a route matches the current URL

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";
}

folded / routing

Maintainers

Details