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.

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 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