Download the PHP package chevere/router without Composer

Router

Summary

Router is a library for creating routing systems for chevere/http. It is compatible with the following PHP-FIG PSR:

• PSR-7: HTTP message interfaces
• PSR-11: Container interface
• PSR-15: HTTP Server Request Handlers
• PSR-17: HTTP Factories

Installing

Router is available through Packagist and the repository source is at chevere/router.

Quick start

What it does

The Router library allows you to bind paths to HTTP methods and logic. It maps paths to their corresponding HTTP controller actions, views, and middleware pipelines. It also collects and validates the views and dependencies used in the routing process.

For example, to resolve this:

You need to write the following route code:

And the HTTP controllers may look like this:

Bind

A Bind is the conjunction of a controller, its middleware pipeline and a view. Use helper function bind($view, $controller, ...$middleware) to explicitly create a binding.

Use method controllerName() to access the ControllerName API.

Use method view() to access the view string.

Use method middlewares() to access the Middlewares collection API.

Headless

Use helper function headless($controller, ...$middleware) to define a bind without a view, only the controller and middleware.

Route

Use the helper function route($path, ...) to define path endpoints. An endpoint is defined as the conjunction of a path, an HTTP method and a controller.

View route

When no controller is needed you can bind the HTTP method to the target view, without indicating a controller.

Headless route

When no view is needed you can bind the HTTP method to the target controller, without indicating a view.

Dynamic route

Dynamic routes use variable wildcards ({variable} syntax) to denote variable path components.

Where MyController class method __invoke() parameters must match the defined wildcards:

Path variables implicit match against [^/]+. To customize use _string on main’s function parameters.

The view argument

Use the view argument to define the same view for all endpoints.

Use helpers like bind() or headless() to override the base view argument definition.

The middleware argument

Use the middleware argument to define the same middleware pipeline for all endpoints.

Use helpers like bind() or headless() to override the base middleware argument definition.

The exclude argument

The exclude argument enables to define middleware names that should be excluded from the pipeline.

Middlewares

The Middlewares API enables you to organize PSR-15 middleware for your routes. Use the helper function middlewares(...$middleware) to create a Middlewares collection.

You can use this collection in route definitions to apply middleware to specific routes.

Routes

The Routes API enables to collect, assert, inspect and organize Route objects.

Use helper function routes(...$route|$routes) to create a Routes object.

Managing routes

Use method withRoute(...$route) to add Route objects, use method withRoutes(...$routes) to add Routes objects.

Use method has(...$path) to tell if the path is already routed. Use get($path) to retrieve the route for a given path.

Middleware pipelines

Use method withPrependMiddleware($midlewares) to prepend middleware to the begin of the pipeline. Use this for middleware that must resolve early in execution order.

Use method withAppendMiddleware($middlewares) to append middleware to the end of the pipeline. Use this for middleware that must resolve last in execution order.

Views

The Views API enables to assert the views collected for all routes. Use assert($viewsDir) method to assert that the views directory contains the view names defined in routes.

Container

Use new Container(...) to create the dependency container by passing entries you may need to manually create.

Adding entries

Use method with(...$entries) to add one or more named entries to the container.

Accessing entries

Use method has($name) to tell if the container has an entry by name. Use method get($name) to retrieve the entry value.

Automatic dependency injection

Use method withAutoInject($deps, ...$ignore) to automatically inject missing dependencies recursively.

The ignore argument allows you to define dependencies that should be ignored, which is useful for dependencies that must be late injected after the middleware pipeline resolves.

Dependencies

The Dependencies API enables to interact with the dependencies detected for all routing participants. The Router will collect every __construct on both controllers and middleware, to provide a collection where you can use your own dependency injection logic.

Assert dependencies

Use method assert($container) to assert that the PSR-11 $container meets the required dependencies.

This is an additional guard that can be used to static detect missing dependencies. On runtime, the system will throw an exception before even reach the middleware layer.

Routed

The Routed API enables to interact with the outcome result of the routing process. Use method routed(...) to resolve routing.

Late dependency injection

The $callback argument enables to pass logic that will resolve after the middleware pipeline and before the controller layer.

Routed outcome

Use method hasThrowable() to tell if routing throws an exception. Use method throwable() to access the exception (if any).

The system is flexible as it enables to define catch-all strategies. For example, you may want to catch ControllerException objects and pass-by everything else.

Use method response() to access the routed PSR-7 response object.

Use method bind() to access the routed Bind API, which enables to tell the controller, view and middleware.

Use method return() to access to the controller return value. This is the value after Action I/O guard layer.

Documentation

Documentation is available at chevere.org.

License

Copyright Rodolfo Berrios A.

Chevere is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.