README

Fast, type-safe request routing, parameter retrieval, and link generation.

It's a port of hack-router By Facebook, Inc.

Components

HTTP Exceptions

Exception classes representing common situations in HTTP applications:

HackRouting\HttpException\InternalServerErrorException
HackRouting\HttpException\MethodNotAllowedException
HackRouting\HttpException\NotFoundException

Router

A simple typed request router. Example:

<?php

use Psl\Str;
use HackRouting\Cache;
use HackRouting\Router;
use HackRouting\HttpMethod;
use HackRouting\HttpException;

$cache = new Cache\ApcuCache();
$router = new Router($cache);

$router->addRoute(HttpMethod::GET, '/', function (): string {
    return 'Hello, World!';
});

$router->addRoute(HttpMethod::GET, '/user/{username:[a-z]+}', function (array $parameters): string {
    return Str\format('Hello, %s!', $parameters['username']);
});

$router->addRoute(HttpMethod::POST, '/', function (): string {
    return 'Hello, POST world';
});

$router->addRoute(HttpMethod::GET, '/{page:about|contact}-us', static function (array $parameters): string {
    if ($parameters['page'] === 'about') {
        return 'Learn about us';
    }

    return 'Contact us';
});


try {
    [$responder, $parameters] = $router->match('GET', '/user/azjezz');
    
    $responder($parameters); // Hello, azjezz!
} catch (HttpException\MethodNotAllowedException $e) {
    $allowed_methods = $e->getAllowedMethods();
    // Handle 405.
} catch (HttpException\NotFoundException) {
    // Handle 404.
} catch (HttpException\InternalServerErrorException) {
    // Handle 500.
}

AbstractRouter

A more low-level router, which allows you to load routes using other means ( e.g. from configuration files ).

<?php

use Psl\Str;
use HackRouting\AbstractRouter;
use HackRouting\HttpMethod;

/**
 * @extends BaseRouter<(function(array<string, string>):string)>
 */
final class Matcher extends AbstractRouter {
  /**
   * @return array<non-empty-string, array<string, (function(array<string, string>):string)>>
   */
  protected function getRoutes(): array {
    return [
      HttpMethod::GET => [
        '/' => static fn(array $parameters): string => 'Hello, World!',
        '/user/{username}/' => static fn(array $parameters): string => Str\format('Hello, %s!', $parameters['username']),
      ],

      HttpMethod::POST => [
        '/' => static fn(array $parameters): string => 'Hello, POST world',
      ],
    ];
  }
}

Simplified for conciseness - see examples/AbstractRouterExample.php for full executable example.

UriPatterns

Generate route fragments, URIs (for linking), and retrieve URI parameters in a consistent and type-safe way:

<?php

use HackRouting\UriPattern\UriPattern;

final class UserPageController extends WebController {
  public static function getUriPattern(): UriPattern {
    return (new UriPattern())
      ->literal('/users/')
      ->string('user_name');
  }

  // ...
}

Parameters can be retrieved, with types checked at runtime both against the values, and the definition:

public function getResponse(): string {
  return 'Hello, '.$this->getUriParameters()->getString('user_name');
}

You can also generate links to controllers:

$link = UserPageController::getUriBuilder()
  ->setString('user_name', 'Mr Hankey')
  ->getPath();

These examples are simplified for conciseness - see examples/UriPatternsExample.php for full executable example.

Caching

HackRouting comes with 4 caching strategies.

HackRouting\Cache\ApcuCache
HackRouting\Cache\FileCache
HackRouting\Cache\MemoryCache
HackRouting\Cache\NullCache

By default, the router will use NullCache strategy, however, in production, it's extremely recommended using another strategy that fits your need.

If your application is running behind a traditional web-server ( i.e: fpm/fast-cgi ), we recommend using ApcuCache strategy if possible, falling back to FileCache.

If your application is used with a long-running process server such as Amphp, ReactPHP, RoadRunner ... etc, it's recommended to use MemoryCache to avoid additional I/O operations, and maximize performance.

Contributing

We welcome GitHub issues and pull requests - please see CONTRIBUTING.md for details.

License

hack-routing is MIT-licensed.

azjezz / hack-routing

Maintainers

Details