Download the PHP package cklamm/router without Composer

PHP Router

There is obviously an insufficient amount of routing libraries for PHP, so I wrote this one. Jokes aside, I do not recommend to use this library instead of popular ones like FastRoute or the Symfony Routing component. I wrote it mainly as an exercise.

That being said, what can this library do? Like any router, it allows you to define which functionality your PHP application should invoke when a specific URL is requested. It also supports different HTTP methods, route parameters (including optional and wildcard parameters), route grouping, middleware and path generation through named routes.

Contents

• Installation
• Usage Example
• Defining Routes
• Route Parameters
• Route Groups
• Middleware
• Dispatching
• Path Generation

Installation

The library can be installed via Composer.

Usage Example

This is a simplified example showing the most important features. Explanations can be found in the respective sections of this documentation.

Defining Routes

Routes can be defined with the add method.

add(string $method, string $route, mixed $handler, string $name = null): Route

• $method is the HTTP method and will be converted to uppercase.
• $route is the actual route definition and can contain parameters.
• $handler can be a string, but it could also be a callback function that should be executed when the route is requested. Invoking such a function is left to the implementing application.
• The optional $name is used for generating a path for this route. Route names must be unique.

There are shortcut methods for common HTTP verbs (GET, POST, PUT, PATCH, DELETE). The following two definitions are equivalent.

Route Parameters

Route definitions can contain parameters. The precedence of defined routes corresponds to the order of the table below. Therefore, unlike in many other routing libraries, the order in which routes are defined does not matter, as there is no ambiguity.

The following route has one required and two optional parameters. It matches paths such as calendar/2020, calendar/2020/12 and calendar/2020/12/31.

:warning: Be aware that this library does not use regular expressions for parameters, so the above route would also match calendar/foo/bar. Any validation must be done by the implementing application.

Route Groups

Routes can be grouped with the group method.

group(string $prefix, \Closure $cb): Node

• $prefix is the prefix that all routes in this group will have. The prefix can consist of several segments.
• $cb is a callback function that contains the grouped route definitions. Inside this function, $this refers to the Router instance.

Route groups can be nested.

Middleware

Many PHP frameworks make use of middleware which provides functionality that should be executed before or after a request. Not every middleware should be executed for every request. This library makes it easy to assign middleware either globally, to a group of routes, or to a single route.

Global Middleware

Middleware that should be executed for every route can be assigned directly to the router.

Instead of calling the method repeatedly, you can pass multiple middleware names at once.

Group Middleware

Middleware that should be executed for several routes can be assigned to a route group. If you do not want the grouped routes to have a common prefix, use an empty string as prefix.

Route Middleware

Middleware that should be executed for a single route only can be assigned to that route. Note that unlike global and group middleware, route middleware only applies to the HTTP method of that route.

Dispatching

The dispatch method determines which of the previously defined routes matches a given path. Usually this method is called only once for each request.

dispatch(string $method, string $path): Result

• $method is the requested HTTP method.
• $path is the requested path (without domain name).

The dispatch method returns an instance of cklamm\Router\Result, which has the following public properties.

If the handler that was defined for the route is a callback function, it can be executed like this:

Path Generation

The path method can be used to generate a path for a named route. This can be very useful for providing links to different pages of the application.

path(string $route, mixed $data = []): string

• $route is the name of the route. It needs to have been defined previously.
• $data is an array or an object containing values for the route parameters.

If a numerical array is passed to the path method, it will fill in the parameter values in the order they are provided. If an object or an associative array is passed, the method will fill in the values according to the names of the route parameters.