facebook/hack-router

URI routing for Hack

Hack-Router

, _(*1)

Fast, type-safe request routing, parameter retrieval, and link generation, with PSR-7 support., _(*2)

Components

HTTP Exceptions

Exception classes representing common situations in HTTP applications: - InternalServerError - MethodNotAllowed - NotFoundException, _(*3)

BaseRouter

A simple typed request router. Example:, _(*4)

<?hh // strict
/** TResponder can be whatever you want; in this case, it's a
 * callable, but classname<MyWebControllerBase> is also a
 * common choice.
 */
type TResponder = (function(ImmMap<string, string>):string);

final class BaseRouterExample extends BaseRouter<TResponder> {
  protected function getRoutes(
  ): ImmMap<HttpMethod, ImmMap<string, TResponder>> {
    return ImmMap {
      HttpMethod::GET => ImmMap {
        '/' =>
          ($_params) ==> 'Hello, world',
        '/user/{user_name}' =>
          ($params) ==> 'Hello, '.$params['user_name'],
      },
      HttpMethod::POST => ImmMap {
        '/' => ($_params) ==> 'Hello, POST world',
      },
    };
  }
}

Simplified for conciseness - see examples/BaseRouterExample.php for full executable example., _(*5)

UriPatterns

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

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

Parameters can be retrevied, with types checked at runtime both against the values, and the definition:, _(*7)

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

You can also generate links to controllers:, _(*8)

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

These examples are simplified for conciseness - see examples/UriPatternsExample.php for full executable example., _(*9)

Codegen

The hhvm/hack-router-codegen project builds on top of of this project to automatically generate:, _(*10)

• Full request routing objects and URI maps based on UriPatterns defined in the controllers
• Per-controller parameter classes, allowing $params->getFoo() instead of $params->getString('Foo'); this allows the typechecker to catch more errors, and IDE autocomplete functionality to support parameters.
• Per-controller UriBuilder classes, with similar benefits

Contributing

We welcome GitHub issues and pull requests - please see CONTRIBUTING.md for details., _(*11)

License

hack-router is MIT-licensed., _(*12)