README

Maps HTTP requests to HTTP responses in PHP 8+.

Features

root path "/" mappings
configure root path sub-namespace
GET http method
POST http method
PUT http method
DELETE http method
OPTIONS http method
return GET request-handler if no HEAD request-handler is defined
asterix OPTIONS "OPTIONS *" http method
prevent alternative root path sub-namespace mapping (e.g. "/" is also available at "/home")
configure action prefix
configure action suffix
noun-based URLs (plural) (RESTful URLs)
verb-based URLs (singular) (actions)
override plural segments (exclude words from auto plural-singular conversion)
override singular segments (exclude words from auto singular-plural conversion)
support HEAD request from a GET request handler
variadic routing (trailing parameters)
nested resources
required parameter routing
optional parameter routing
integer parameters
string parameters
array parameters
float parameters
allowed methods provided for 405 results
accepted types provided for 406 results
cache results
logging
provide custom inflector (for noun-plural conversions)
provide custom logger
provide custom negotiator (for negotiating media-types/languages/etc.)
negotiate media-types
negotiate languages
Concurrency support for Swoole
Reverse routing
Remove the need on having to define parent resource classes (caveat 1)
route dumper (CLI)
class creator from route (CLI)
Enum support?
value-object support?
Better differentiation between when a plural or noun is needed (so overriding plural words are not needed as much)
union types (int|string)

Installation

composer install meraki/http-router

Usage

Basic configuration that will suit most small projects and that is compatible with all the PHP-FIG PSRs:

<?php
require_once __DIR__ . '/../vendor/autoload.php';

use Meraki\Http\AutoRouter;
use Laminas\Diactoros\ServerRequestFactory;

$router = new AutoRouter('Project\\Http\\');
$request = ServerRequestFactory::fromGlobals();

$result = $router->route($request);

switch ($result->status) {
	case 200:
		// get the matched route
		$route = $result->route;

		// access info about the matching route
		$requestHandler = $route->requestHandler;
		$invokeMethod = $route->invokeMethod;
		$params = $route->parameters;
		break;

	case 404:
		// the request that couldn't be matched
		$request = $result->request;
		default;

	case 405:
		// fully qualified class name that was built
		$allowedMethods = $result->allowedMethods;
		default;

	default:
		// 500 internal server error
}

To see some other use cases, look at the examples directory in the source code. For more advanced setups, check out the documentation, especially the section on configuration.

Caveats

Child resources can only be matched if there is a parent resource defined with the same HTTP method as the child

For example, the following HTTP request:

POST /contact/0412345678/ping

will only work if the following two classes exist:

$parentResource = Project\Http\Contact\PostAction::class;
$childResource = Project\Http\Contact\Ping\PostAction::class;

The $parentResource will not be instantiated at any point during routing, but it must still exists and the $childResource must have the same method signature as the $parentResource.

Notes

This library made the intentional decision to not rely on PSR7 for request and response objects. This provides for the greatest compatibility between different HTTP implementations.

Contributing

See CONTRIBUTING.md.

meraki / http-router

Maintainers

Details