facebook / hack-router
URI routing for Hack
Installs: 32 671
Dependents: 5
Suggesters: 0
Security: 0
Stars: 40
Watchers: 18
Forks: 14
Open Issues: 11
Language:Hack
Requires
- hack-psr/psr7-http-message-hhi: ^0.2.0|^1.0.0
- nikic/fast-route: ^1.0.0 || >0.7 <1.0
Requires (Dev)
- 91carriage/phpunit-hhi: ^5.1
- phpunit/phpunit: ^5.1
- zendframework/zend-diactoros: ^1.3
README
Fast, type-safe request routing, parameter retrieval, and link generation, with PSR-7 support.
Components
HTTP Exceptions
Exception classes representing common situations in HTTP applications:
InternalServerError
MethodNotAllowed
NotFoundException
BaseRouter
A simple typed request router. Example:
<?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.
UriPatterns
Generate FastRoute fragments, URIs (for linking), and retrieve URI parameters in a consistent and type-safe way:
<?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:
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.
Codegen
The hhvm/hack-router-codegen project builds on top of of this project to automatically generate:
- 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.
License
hack-router is MIT-licensed.