Hack-Routing

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.

Comments

/user/Hans8 matches /user/{username:[a-z]+}
Describe the bug /user/Hans8 matches /user/{username:[a-z]+}, which shouldn't be the case

To Reproduce Code to reproduce the behavior: https://github.com/azjezz/hack-routing/blob/main/examples/simple.php#L42

Expected behavior i would expect a 404 route not found

Environment (please complete the following information):

OS: Ubuntu

PHP version 8.0.7

Version main branch

Additional context
bug
opened by dominikzogg 7
Path generation from string pattern

Is your feature request related to a problem? Please describe. No problem,

Describe the solution you'd like I would love to be able generate a path from a pattern and an array for the variable parts. Something like: https://github.com/chubbyphp/chubbyphp-framework-router-hack-routing/blob/master/src/UrlGenerator.php

Describe alternatives you've considered The alternative would be keep the custom implementation as mentioned in describe the solution

Additional context Add any other context or screenshots about the feature request here.

opened by dominikzogg 3