Download the PHP package phputil/router without Composer

phputil/router

ExpressJS-like router for PHP

• No third-party dependencies
• Unit-tested
• Mockable - it's easy to create automated tests for your API

👉 Do NOT use it in production yet - just for toy projects.

Installation

Requires PHP 7.4+

Is it useful for you? Consider giving it a Star ⭐

Installation notes

• Unlike ExpressJS, phputil/router needs an HTTP server to run (if the request is not Server Configuration for more information.
• If you are using Apache or Nginx, you may need to inform the rootURL parameter when calling listen(). Example:

Middlewares

You may also want to install the following middlewares:

• phputil/cors - CORS Middleware
• phputil/csrf - Anti CSRF Middleware

ℹ Did you create a useful middleware? Open an Issue for including it here.

Examples

Hello World

Using parameters

Middleware per route

See all the examples

ℹ Interested in helping us? Submit a Pull Request with a new example or open an Issue with your code.

Features

• [✔] Support to standard HTTP methods (GET, POST, PUT, DELETE, HEAD, OPTIONS) and PATCH.
• [✔] Route parameters
  • e.g. $app->get('/customers/:id', function( $req, $res ) { $res->send( $req->param('id') ); } );
• [✔] URL groups
  • e.g. $app->route('/customers/:id')->get('/emails', $cbGetEmails );
• [✔] Global middlewares
  • e.g. $app->use( function( $req, $res, &$stop ) { /*...*/ } );
• [✔] Middlewares per URL group
  • e.g. $app->route( '/admin' )->use( $middlewareIsAdmin )->get( '/', function( $req, $res ) { /*...*/ } );
• [✔] Middlewares per route
  • e.g. $app->get( '/', $middleware1, $middleware2, function( $req, $res ) { /*...*/ } );
• [✔] Request cookies
  • e.g. $app->get('/', function( $req, $res ) { $res->send( $req->cookie('sid') ); } );
• [✔] Extra: Can mock HTTP requests for testing, without the need to running an HTTP server.
• [🕑] (soon) Deal with multipart/form-data on PUT and PATCH

API

This library does not aim to cover the entire ExpressJS API. However, feel free to contribute to this project and add more features.

Types:

• Middleware
• Router
• RouterOptions
• HttpRequest
• ExtraData
• HttpResponse

Middleware

In phputil/router, a middleware is a function that:

1. Perform some action (e.g., set response headers, verify permissions) before a route is evaluated.
2. Can stop the router, optionally setting a response.

Syntax:

where:

• $req allows to get all the request headers and data.
• $res allows to set all the response headers and data.
• $stop allows to stop the router, when set to true.

Router

Class that represents a router.

Overview:

isDebugMode

Version 0.4+

Indicates if the router is in debug mode - in which exception traces are echoed. It is false by default.

Example:

setDebugMode

Version 0.4+

Sets the debug mode - in which exception traces are echoed.

Example:

getErrorHandler

Version 0.4+

Returns the error handler, used for catching exceptions in route callbacks and middlewares. It is null by default, what makes the router to use the function defaultErrorHandler as the error handler. That handler returns an HTTP 500 with the error message in the body. When isDebugMode() is set, it returns the stack trace in the message body.

Example:

setErrorHandler

Version 0.4+

Sets the error handler, used for catching exceptions in route callbacks and middlewares. The error handler has the following syntax:

Example:

get

Method that deals with a GET HTTP request.

where:

• $route is a route (path).
• $callbacks can receive none, one or more middleware functions and one route handler - which must be the last function.

A route handler (callback) has the following syntax:

where:

• $req allows to get all the request headers and data.
• $res allows to set all the response headers and data.

Examples:

post

Method that deals with a POST HTTP request. Same syntax as get's.

put

Method that deals with a PUT HTTP request. Same syntax as get's.

delete

Method that deals with a DELETE HTTP request. Same syntax as get's.

head

Method that deals with a HEAD HTTP request. Same syntax as get's.

option

Method that deals with a OPTION HTTP request. Same syntax as get's.

patch

Method that deals with a PATCH HTTP request. Same syntax as get's.

all

Method that deals with any HTTP request. Same syntax as get's.

group

Alias to the method route.

route

Method that adds a route group, where you can register one or more HTTP method handlers.

Example:

⚠️ Don't forget to finish a route/group with the method end().

end

Method that finishes a route group and returns to the group parent.

Example:

use

Method that adds a middleware to be evaluated before the routes declared after it.

Example:

listen

Method that executes the router.

Options are:

• rootURL is a string that sets the root URL. Example: dirname( $_SERVER['PHP_SELF'] ). By default it is ''.
• req is an object that implements the interface HttpRequest, which retrieves all the headers and data from a HTTP request. Changing it is only useful if you want to unit test your API - see Mocking an HTTP request. By default, it will receive an object from the class RealHttpRequest.
• res is an object that implements the interface HttpResponse. You probably won't need to change its value. By default, it will receive an object from the class RealHttpResponse.

Example:

You can also use an instance of RouterOptions for setting the options:

RouterOptions

Options for the listen() method.

withRootURL

withReq

withRes

HttpRequest

Interface that represents an HTTP request.

API:

ExtraData

Extra, user-defined data.

Syntax:

HttpResponse

Interface that represents an HTTP response.

Most of its methods are chainable, that is, you can call them in a sequence. Example:

API:

Mocking an HTTP request

👉 Useful for API testing

License

Thiago Delgado Pinto