fyre/router

A URL routing library.

v7.0.1 2024-12-12 14:11 UTC

Requires

• fyre/container: ^1.0
• fyre/error: ^6.0
• fyre/middleware: ^6.0
• fyre/orm: ^10.0
• fyre/server: ^4.0
• fyre/uri: ^3.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.59
• fyre/php-cs-fixer-config: ^1.0
• phpunit/phpunit: ^11

MIT

• elusivecodes

README

FyreRouter is a free, open-source URI routing library for PHP.

Table Of Contents

• Installation
• Basic Usage
• Methods
• Routes
  • Closure
  • Controller
  • Redirect
• Middleware
  • Substitute Bindings

Installation

Using Composer

composer require fyre/router

In PHP:

use Fyre\Router\Router;

Basic Usage

• $container is a Container.
• $modelRegistry is a ModelRegistry.
• $config is a Config.

$router = new Router($container, $modelRegistry, $config);

The base URI will be resolved from the "App.baseUri" key in the Config.

Autoloading

It is recommended to bind the Router to the Container as a singleton.

$container->singleton(Router::class);

Any dependencies will be injected automatically when loading from the Container.

$router = $container->use(Router::class);

Methods

Clear

Clear all routes and aliases.

$router->clear();

Connect

Connect a route.

• $path is a string representing the route path, and can include placeholders (that will be passed to the destination).
• $destination can be either a string representing the destination, an array containing the class name and method or a Closure.
• $options is an array containing configuration options.
  • as is a string representing the route alias, and will default to null.
  • middleware is an array of middleware to be applied to the route, and will default to [].
  • method is an array of strings representing the matching methods, and will default to [].
  • placeholders is an array of regular expression placeholders, and will default to [].
  • redirect is a boolean indicating whether the route is a redirect, and will default to false.

$route = $router->connect($path, $destination, $options);

You can generate the following helper methods to connect specific routes.

$router->delete($path, $destination, $options);
$router->get($path, $destination, $options);
$router->patch($path, $destination, $options);
$router->post($path, $destination, $options);
$router->put($path, $destination, $options);
$router->redirect($path, $destination, $options);

See the Routes section for supported path and destination formats.

You can also pass additional arguments to the middleware by appending a colon followed by a comma-separated list of arguments to the alias string. You can use route placeholders as arguments by referencing the route placeholder surrounded by curly braces.

$router->get('test/{id}', 'test', ['middleware' => 'alias:test,{id}']);

Get Base Uri

Get the base uri.

$baseUri = $router->getBaseUri();

Group

Create a group of routes.

• $options is an array containing the group options.
  • prefix is a string representing the route group path prefix, and will default to null.
  • as is a string representing the route group alias prefix, and will default to null.
  • middleware is an array of middleware to be applied to the route group, and will default to [].
  • placeholders is an array of regular expression placeholders, and will default to [].
• $callback is a Closure with the Router as the first argument.

$router->group($options, $callback);

Load Route

Load a route.

• $request is a ServerRequest.

$request = $router->loadRoute($request);

This method will return a ServerRequest, with the route parameter set to the loaded route.

Url

Generate a URL for a named route.

• $name is a string representing the route alias.
• $arguments is an array containing the route arguments, where the key is the placeholder name.
  • ? is an array containing route query parameters.
  • # is a string representing the fragment component of the URI.
• $options is an array containing the route options.
  • fullBase is a boolean indicating whether to use the full base URI and will default to false.

$url = $router->url($name, $arguments, $options)

Routes

All routes extend the Fyre\Router\Route class, and include the following methods.

Check Method

Check if the route matches a test method.

• $method is a string representing the method to test.

$checkMethod = $route->checkMethod($method);

Check Path

Check if the route matches a test path.

• $path is a string representing the path to test.

$checkPath = $route->checkPath($path);

Get Arguments

Get the route arguments.

$arguments = $route->getArguments();

Get Binding Fields

Get the route binding fields.

$bindingFields = $route->getBindingFields();

Get Destination

Get the route destination.

$destination = $route->getDestination();

Get Middleware

Get the route middleware.

$middleware = $route->getMiddleware();

Get Path

Get the route path.

$path = $route->getPath();

Get Placeholders

Get the route placeholders.

$placeholders = $route->getPlaceholders();

Handle

Handle the route.

• $request is a ServerRequest.
• $response is a ClientResponse.

$response = $route->handle($request, $response);

This method will return a ClientResponse.

Set Middleware

Set the route middleware.

• $middleware is an array containing the route middleware.

$route->setMiddleware($middleware);

Set Placeholder

Set a route placeholder.

• $placeholder is a string representing the route placeholder.
• $regex is a string representing the placeholder regular expression.

$route->setPlaceholder($placeholder, $regex);

Closure

use Fyre\Router\Routes\ClosureRoute;

• $container is a Container.
• $destination is a Closure.
• $path is a string representing the route path, and will default to "".
• $options is an array containing route options.
  • middleware is an array of middleware to be applied to the route, and will default to [].
  • method is an array of strings representing the matching methods, and will default to [].
  • placeholders is an array of regular expression placeholders, and will default to [].

$route = new ClosureRoute($container, $destination, $path, $options);

The $path and $destination can be expressed in the following formats:

$router->get('posts', function(): string {
    return view('Posts.index');
});

$router->get('posts/{post}', function(Post $post): string {
    return view('Posts.view', ['post' => $post]);
}); 

Route parameter entity binding is handled by the Substitute Bindings middleware.

Controller

use Fyre\Router\Routes\ControllerRoute;

• $container is a Container.
• $destination is an array containing the controller class name and method.
• $path is a string representing the route path, and will default to "".
• $options is an array containing route options.
  • middleware is an array of middleware to be applied to the route, and will default to [].
  • method is an array of strings representing the matching methods, and will default to [].
  • placeholders is an array of regular expression placeholders, and will default to [].

$route = new ControllerRoute($container, $destination, $path, $options);

The $path and $destination can be expressed in the following formats:

$router->get('posts', [Posts::class]); // defaults to index method
$router->get('posts/{post}', [Posts::class, 'view']);

Route parameter entity binding is handled by the Substitute Bindings middleware.

Get Action

Get the route controller action.

$action = $route->getAction();

Get Controller

Get the route controller class name.

$controller = $route->getController();

Redirect

use Fyre\Router\Routes\RedirectRoute;

• $container is a Container.
• $destination is a string representing the destination.
• $path is a string representing the route path, and will default to "".
• $options is an array containing route options.
  • middleware is an array of middleware to be applied to the route, and will default to [].
  • method is an array of strings representing the matching methods, and will default to [].
  • placeholders is an array of regular expression placeholders, and will default to [].

$route = new RedirectRoute($container, $destination, $path, $options);

The $path and $destination can be expressed in the following formats:

$router->redirect('test', 'https://test.com/');
$router->redirect('test/{id}', 'https://test.com/{id}');

Middleware

use Fyre\Router\Middleware\RouterMiddleware;

• $container is a Container.
• $middlewareRegistry is a MiddlewareRegistry.
• $router is a Router.

$middleware = new RouterMiddleware($container, $middlewareRegistry, $router);

Any dependencies will be injected automatically when loading from the Container.

$middleware = $container->use(RouterMiddleware::class);

Handle

Handle a ServerRequest.

• $request is a ServerRequest.
• $next is a Closure.

$response = $middleware->handle($request, $next);

This method will return a ClientResponse.

Substitute Bindings

use Fyre\Router\Middleware\SubstituteBindingsMiddleware;

This middleware will automatically resolve entities from route placeholders based on the parameter types of the route destination.

• $container is a Container.
• $middlewareRegistry is a MiddlewareRegistry.
• $entityLocator is an EntityLocator.

$middleware = new SubstituteBindingsMiddleware($container, $middlewareRegistry, $entityLocator);

Any dependencies will be injected automatically when loading from the Container.

$middleware = $container->use(SubstituteBindingsMiddleware::class);

Handle

Handle a ServerRequest.

• $request is a ServerRequest.
• $next is a Closure.

$response = $middleware->handle($request, $next);

This method will return a ClientResponse.