sunrise / http-router
HTTP router for PHP 7.1+ based on PSR-7 and PSR-15 with support for annotations/attributes and OpenAPI (Swagger) Specification
Installs: 44 335
Dependents: 10
Suggesters: 0
Security: 0
Stars: 159
Watchers: 4
Forks: 10
Open Issues: 13
Requires
- php: >=8.1
- fig/http-message-util: ^1.1
- psr/container: ^1.0 || ^2.0
- psr/event-dispatcher: ^1.0
- psr/http-factory: ^1.0
- psr/http-message: ^1.0 || ^2.0
- psr/http-server-handler: ^1.0
- psr/http-server-middleware: ^1.0
- psr/log: ^1.0 || ^2.0 || ^3.0
- psr/simple-cache: ^1.0 || ^2.0 || ^3.0
Requires (Dev)
- php-di/php-di: ^7.0
- phpstan/phpstan: ^1.12
- phpunit/phpunit: ^10.5
- squizlabs/php_codesniffer: ^3.10
- sunrise/hydrator: ^3.13
- symfony/console: ^6.4
- symfony/validator: ^6.4
- vimeo/psalm: ^5.26
- dev-master
- v3.0.0-beta.17
- v3.0.0-beta.16
- v3.0.0-beta.15
- v3.0.0-beta.14
- v3.0.0-beta.13
- v3.0.0-beta.12
- v3.0.0-beta.11
- v3.0.0-beta.10
- v3.0.0-beta.9
- v3.0.0-beta.8
- v3.0.0-beta.7
- v3.0.0-beta.6
- v3.0.0-beta.5
- v3.0.0-beta.4
- v3.0.0-beta.3
- v3.0.0-beta.2
- v3.0.0-beta.1
- v2.16.2
- v2.16.1
- v2.16.0
- v2.15.1
- v2.15.0
- v2.14.1
- v2.14.0
- v2.13.0
- v2.12.0
- v2.11.2
- v2.11.1
- v2.11.0
- v2.10.2
- v2.10.1
- v2.10.0
- v2.9.0
- v2.8.0
- v2.7.0
- v2.6.0
- v2.5.0
- v2.4.2
- v2.4.1
- v2.4.0
- v2.3.0
- v2.2.0
- v2.1.0
- v2.0.2
- v2.0.1
- v2.0.0
- 1.x-dev
- v1.0.14
- v1.0.13
- v1.0.12
- v1.0.11
- v1.0.10
- v1.0.9
- v1.0.8
- v1.0.7
- v1.0.6
- v1.0.5
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
- dev-release/v3.0.0
- dev-renovate/phpunit-phpunit-11.x
- dev-renovate/phpunit-phpunit-9.x
- dev-renovate/major-symfony
- dev-renovate/cimg-php-8.x
- dev-renovate/psr-http-message-2.x
- dev-renovate/psr-simple-cache-3.x
- dev-renovate/doctrine-annotations-2.x
- dev-renovate/cimg-php-7.x
- dev-renovate/sunrise-http-factory-2.x
This package is auto-updated.
Last update: 2024-11-07 15:10:13 UTC
README
psr router, router with annotations, router with attributes, php router.
Installation
composer require 'sunrise/http-router:^2.15'
Support for OpenAPI (Swagger) Specification (optional)
composer require 'sunrise/http-router-openapi:^2.0'
More details can be found here: sunrise/http-router-openapi.
QuickStart
This example uses other sunrise packages, but you can use e.g. zend/diactoros
or any other.
composer require sunrise/http-message sunrise/http-server-request
use Sunrise\Http\Message\ResponseFactory; use Sunrise\Http\Router\RouteCollector; use Sunrise\Http\Router\Router; use Sunrise\Http\ServerRequest\ServerRequestFactory; use function Sunrise\Http\Router\emit; $collector = new RouteCollector(); // PSR-15 request handler (optimal performance): $collector->get('home', '/', new HomeRequestHandler()); // or you can use an anonymous function as your request handler: $collector->get('home', '/', function ($request) { return (new ResponseFactory)->createResponse(200); }); // or you can use the name of a class that implements PSR-15: $collector->get('home', '/', HomeRequestHandler::class); // or you can use a class method name as your request handler: // (note that such a class mayn't implement PSR-15) $collector->get('home', '/', [HomeRequestHandler::class, 'index']); // most likely you will need to use PSR-11 container: // (note that only named classes will be pulled from such a container) $collector->setContainer($container); $router = new Router(); $router->addRoute(...$collector->getCollection()->all()); $request = ServerRequestFactory::fromGlobals(); $response = $router->handle($request); emit($response);
Examples of using
Study sunrise/awesome-skeleton to understand how this can be used.
Strategy for loading routes from configs
Please note that since version 2.10.0 class
ConfigLoader
must be used.
use Sunrise\Http\Router\Loader\ConfigLoader; use Sunrise\Http\Router\Router; $loader = new ConfigLoader(); // set container if necessary... $loader->setContainer($container); // attach configs... $loader->attach('routes/api.php'); $loader->attach('routes/admin.php'); $loader->attach('routes/public.php'); // or attach a directory... // [!] available from version 2.2 $loader->attach('routes'); // or attach an array... // [!] available from version 2.4 $loader->attachArray([ 'routes/api.php', 'routes/admin.php', 'routes/public.php', ]); // install container if necessary... $loader->setContainer($container); $router = new Router(); $router->load($loader); // if the router matching should be isolated for top middlewares... // for example for error handling... // [!] available from version 2.8 $response = $router->run($request); // if the router is used as a request handler $response = $router->handle($request); // if the router is used as middleware $response = $router->process($request, $handler);
/** @var Sunrise\Http\Router\RouteCollector $this */ $this->get('home', '/', new CallableRequestHandler(function ($request) { return (new ResponseFactory)->createJsonResponse(200); })); // or using a direct reference to a request handler... $this->get('home', '/', new App\Http\Controller\HomeController());
Please note that since version 2.10.0 you can refer to the request handler in different ways.
/** @var Sunrise\Http\Router\RouteCollector $this */ $this->get('home', '/', function ($request) { return (new ResponseFactory)->createJsonResponse(200); }); $this->get('home', '/', App\Http\Controller\HomeController::class, [ App\Http\Middleware\FooMiddleware::class, App\Http\Middleware\BarMiddleware::class, ]); $this->get('home', '/', [App\Http\Controller\HomeController::class, 'index'], [ App\Http\Middleware\FooMiddleware::class, App\Http\Middleware\BarMiddleware::class, ]);
Strategy for loading routes from descriptors (annotations or attributes)
Install the doctrine/annotations package if you will be use annotations:
composer require doctrine/annotations
Please note that since version 2.10.0 class
DescriptorLoader
must be used.
Please note that since version 2.10.0 you can bind the @Rote() annotation to a class methods.
use Doctrine\Common\Annotations\AnnotationRegistry; use Sunrise\Http\Router\Loader\DescriptorLoader; use Sunrise\Http\Router\Router; // necessary if you will use annotations (annotations isn't attributes)... AnnotationRegistry::registerLoader('class_exists'); $loader = new DescriptorLoader(); // set container if necessary... $loader->setContainer($container); // attach a directory with controllers... $loader->attach('src/Controller'); // or attach an array // [!] available from version 2.4 $loader->attachArray([ 'src/Controller', 'src/Bundle/BundleName/Controller', ]); // or attach a class only // [!] available from 2.10 version. $loader->attach(App\Http\Controller\FooController::class); $router = new Router(); $router->load($loader); // if the router matching should be isolated for top middlewares... // for example for error handling... // [!] available from version 2.8 $response = $router->run($request); // if the router is used as a request handler $response = $router->handle($request); // if the router is used as middleware $response = $router->process($request, $handler);
use Sunrise\Http\Router\Annotation as Mapping; #[Mapping\Prefix('/api/v1')] #[Mapping\Middleware(SomeMiddleware::class)] class SomeController { #[Mapping\Route('foo', path: '/foo')] public function foo() { // will be available at: /api/v1/foo } #[Mapping\Route('bar', path: '/bar')] public function bar() { // will be available at: /api/v1/bar } }
Without loading strategy
use App\Controller\HomeController; use Sunrise\Http\Router\RouteCollector; use Sunrise\Http\Router\Router; $collector = new RouteCollector(); // set container if necessary... $collector->setContainer($container); $collector->get('home', '/', new HomeController()); $router = new Router(); $router->addRoute(...$collector->getCollection()->all()); // if the router matching should be isolated for top middlewares... // for example for error handling... // [!] available from version 2.8 $response = $router->run($request); // if the router is used as a request handler $response = $router->handle($request); // if the router is used as middleware $response = $router->process($request, $handler);
Error handling example
use Sunrise\Http\Message\ResponseFactory; use Sunrise\Http\Router\Exception\MethodNotAllowedException; use Sunrise\Http\Router\Exception\RouteNotFoundException; use Sunrise\Http\Router\Middleware\CallableMiddleware; use Sunrise\Http\Router\RequestHandler\CallableRequestHandler; use Sunrise\Http\Router\RouteCollector; use Sunrise\Http\Router\Router; use Sunrise\Http\ServerRequest\ServerRequestFactory; use function Sunrise\Http\Router\emit; $collector = new RouteCollector(); $collector->get('home', '/', new CallableRequestHandler(function ($request) { return (new ResponseFactory)->createJsonResponse(200); })); $router = new Router(); $router->addRoute(...$collector->getCollection()->all()); $router->addMiddleware(new CallableMiddleware(function ($request, $handler) { try { return $handler->handle($request); } catch (MethodNotAllowedException $e) { return (new ResponseFactory)->createResponse(405); } catch (RouteNotFoundException $e) { return (new ResponseFactory)->createResponse(404); } catch (Throwable $e) { return (new ResponseFactory)->createResponse(500); } })); emit($router->run(ServerRequestFactory::fromGlobals()));
Work with PSR-11 container
Collector
$collector = new RouteCollector(); /** @var \Psr\Container\ContainerInterface $container */ // Pass DI container to the collector... $collector->setContainer($container); // Objects passed as strings will be initialized through the DI container... $route = $collector->get('home', '/', HomeController::class, [ FooMiddleware::class, BarMiddleware::class, ]);
Config loader
$loader = new ConfigLoader(); /** @var \Psr\Container\ContainerInterface $container */ // Pass DI container to the loader... $loader->setContainer($container); // All found objects which has been passed as strings will be initialized through the DI container... $routes = $loader->load();
Descriptor loader
$loader = new DescriptorLoader(); /** @var \Psr\Container\ContainerInterface $container */ // Pass DI container to the loader... $loader->setContainer($container); // All found objects will be initialized through the DI container... $routes = $loader->load();
Descriptors cache (PSR-16)
$loader = new DescriptorLoader(); /** @var \Psr\SimpleCache\CacheInterface $cache */ // Pass a cache to the loader... $loader->setCache($cache);
Route Annotation Example
Minimal annotation view
/** * @Route( * name="api_v1_entry_update", * path="/api/v1/entry/{id<@uuid>}(/{optionalAttribute})", * methods={"PATCH"}, * ) */ final class EntryUpdateRequestHandler implements RequestHandlerInterface
Full annotation
/** * @Route( * name="api_v1_entry_update", * host="api.host", * path="/api/v1/entry/{id<@uuid>}(/{optionalAttribute})", * methods={"PATCH"}, * middlewares={ * "App\Middleware\CorsMiddleware", * "App\Middleware\ApiAuthMiddleware", * }, * attributes={ * "optionalAttribute": "defaultValue", * }, * summary="Updates an entry by UUID", * description="Here you can describe the method in more detail...", * tags={"api", "entry"}, * priority=0, * ) */ final class EntryUpdateRequestHandler implements RequestHandlerInterface
One method only
/** * @Route( * name="home", * path="/", * method="GET", * ) */
Route Attribute Example
Minimal attribute view
use Sunrise\Http\Router\Annotation\Route; #[Route( name: 'api_v1_entry_update', path: '/api/v1/entry/{id<@uuid>}(/{optionalAttribute})', methods: ['PATCH'], )] final class EntryUpdateRequestHandler implements RequestHandlerInterface
Full attribute
use Sunrise\Http\Router\Annotation\Route; #[Route( name: 'api_v1_entry_update', host: 'api.host', path: '/api/v1/entry/{id<@uuid>}(/{optionalAttribute})', methods: ['PATCH'], middlewares: [ \App\Middleware\CorsMiddleware::class, \App\Middleware\ApiAuthMiddleware::class, ], attributes: [ 'optionalAttribute' => 'defaultValue', ], summary: 'Updates an entry by UUID', description: 'Here you can describe the method in more detail...', tags: ['api', 'entry'], priority: 0, )] final class EntryUpdateRequestHandler implements RequestHandlerInterface
Additional annotations
use Sunrise\Http\Router\Annotation\Host; #[Host('admin')] #[Prefix('/api/v1')] #[Postfix('.json')] #[Middleware(SomeMiddleware::class)] final class SomeController { #[Route('foo', '/foo')] public function foo(ServerRequestInterface $request) : ResponseInterface { // this action will be available at: // http://admin.host/api/v1/foo.json // // this can be handy to reduce code duplication... } }
Useful to know
JSON-payload decoding
use Sunrise\Http\Router\Middleware\JsonPayloadDecodingMiddleware; $router->addMiddleware(new JsonPayloadDecodingMiddleware());
Get a route by name
// checks if a route is exists $router->hasRoute('foo'); // gets a route by name $router->getRoute('foo');
Get a current route
Through Router
Available from version 2.12.
$router->getMatchedRoute();
Through Request
Available from version 1.x, but wasn't documented before...
$request->getAttribute('@route'); // or $request->getAttribute(\Sunrise\Http\Router\RouteInterface::ATTR_ROUTE);
Through Event
Available from version 2.13.
$eventDispatcher->addListener(RouteEvent::NAME, function (RouteEvent $event) { $event->getRoute(); });
Generation a route URI
$uri = $router->generateUri('route.name', [ 'attribute' => 'value', ], true);
Run a route
$response = $router->getRoute('route.name')->handle($request);
Route grouping
Example for annotations here.
$collector->group(function ($collector) { $collector->group(function ($collector) { $collector->group(function ($collector) { $collector->get('api.entry.read', '/{id<\d+>}', ...) ->addMiddleware(...); // add the middleware(s) to the route... }) ->addPrefix('/entry') // add the prefix to the group... ->prependMiddleware(...); // add the middleware(s) to the group... }, [ App\Http\Middleware\Bar::class, // resolvable middlewares... ]) ->addPrefix('/v1') // add the prefix to the group... ->prependMiddleware(...); // add the middleware(s) to the group... }, [ App\Http\Middleware\Foo::class, // resolvable middlewares... ]) ->addPrefix('/api') // add the prefix to the group... ->prependMiddleware(...); // add the middleware(s) to the group...
Route patterns
$collector->get('api.entry.read', '/api/v1/entry/{id<\d+>}(/{optional<\w+>})');
Global route patterns
// @uuid pattern $collector->get('api.entry.read', '/api/v1/entry/{id<@uuid>}'); // @slug pattern $collector->get('api.entry.read', '/api/v1/entry/{slug<@slug>}'); // Custom patterns (available from version 2.9.0): \Sunrise\Http\Router\Router::$patterns['@id'] = '[1-9][0-9]*'; // Just use the custom pattern... $collector->get('api.entry.read', '/api/v1/entry/{id<@id>}');
It is better to set patterns through the router:
// available since version 2.11.0 $router->addPatterns([ '@id' => '[1-9][0-9]*', ]);
...or through the router's builder:
// available since version 2.11.0 $builder->setPatterns([ '@id' => '[1-9][0-9]*', ]);
Hosts (available from version 2.6.0)
Note: if you don't assign a host for a route, it will be available on any hosts!
// move the hosts table into the settings... $router->addHost('public.host', 'www.example.com', ...); $router->addHost('admin.host', 'secret.example.com', ...); $router->addHost('api.host', 'api.example.com', ...); // ...or: $router->addHosts([ 'public.host' => ['www.example.com', ...], ... ]); // the route will available only on the `secret.example.com` host... $route->setHost('admin.host'); // routes in the group will available on the `secret.example.com` host... $collector->group(function ($collector) { // some code... }) ->setHost('admin.host');
You can resolve the hostname since version 2.14.0 as follows:
$router->addHost('admin', 'www1.admin.example.com', 'www2.admin.example.com'); $router->resolveHostname('www1.admin.example.com'); // return "admin" $router->resolveHostname('www2.admin.example.com'); // return "admin" $router->resolveHostname('unknown'); // return null
Also you can get all routes by hostname:
$router->getRoutesByHostname('www1.admin.example.com');
Route Holder
$route->getHolder(); // return Reflector (class, method or function)
The router builder
$router = (new RouterBuilder) ->setEventDispatcher(...) // null or use to symfony/event-dispatcher... ->setContainer(...) // null or PSR-11 container instance... ->setCache(...) // null or PSR-16 cache instance... (only for descriptor loader) ->setCacheKey(...) // null or string... (only for descriptor loader) ->useConfigLoader([]) // array with files or directory with files... ->useDescriptorLoader([]) // array with classes or directory with classes... ->setHosts([]) // ->setMiddlewares([]) // array with middlewares... ->setPatterns([]) // available since version 2.11.0 ->build();
CLI commands
use Sunrise\Http\Router\Command\RouteListCommand; new RouteListCommand($router);
Events
Available from version 2.13
composer require symfony/event-dispatcher
use Sunrise\Http\Router\Event\RouteEvent; use Symfony\Component\EventDispatcher\EventDispatcher; $eventDispatcher = new EventDispatcher(); $eventDispatcher->addListener(RouteEvent::NAME, function (RouteEvent $event) { // gets the matched route: $event->getRoute(); // gets the current request: $event->getRequest(); // overrides the current request: $event->setRequest(ServerRequestInterface $request); }); $router->setEventDispatcher($eventDispatcher);
Test run
composer test