Download the PHP package proteins/route without Composer

Protein | Route

A simple and fast URL router

Install

Require the global class via :

URL mapping

You can define a route via the on method.

This is the simplest form to define an HTTP GET route responding on URL /hello.
You can map the same route to multiple request methods using the fluent api interface.

The via method accepts an array of string for handled HTTP request methods.

The with method binds a callable function to the route.

If you need to map various HTTP methods to different callbacks for a single URL (like exposing a resource via a REST API) the map method allows you to pass a method => callback dictionary.

The any shorthand will trigger the route responding on URL /hello for any HTTP verb.

This is the same as doing :

URL pattern matching and parameters extraction

The route pattern is essentially a Regular Expression with some slight differencies.

The pattern is ALWAYS matched against the end of the REQUEST_URI parameter (stripped of the query string).

Rules:

• every (...) group becomes optional
• you can extract parameters via :named_parameter
• the pattern can't contain the # character

Examples:

In this example the optional (is in a (...) group) :id is extracted when present, and the route can be optionally terminated by a /.

This route handles all of these request:

• /element
• /element/
• /element/123
• /element/123/
• /element/1919191
• /element/462635
• etc..

But, as you can see, this example handles also /element/fooo. If we want to give format rules to an extracted parameters we can use the rules method.

The rules method accepts a named_parameter => regex dictionary.

rules([ 'parameter_name' => 'parameter_regex_pattern' ])

We can strenghten the former example adding rules to the id parameter for accepting only integer values (defined by the \d+ regex pattern).

Example:

Route groups

You can encapsulate routes based on a prefix pattern. If the current request doesn't match the group URL pattern, relative routes definition are not registered.

Note: This behaviour is controlled by the core.route.pruning flag.

This feature can be used for response-time optimization and for mounting route trees to a dynamic URL prefix.

You can define multiple nested route groups.

Examples:

Admin section

Route groups with dynamic parameters

RouteGroups can have dynamic parameters that will be extracted like normal Routes.

Route middlewares

You can append a list of middlewares before and after a Route, or a RouteGroup.

If a middleware returns false the entire route execution halts.

Middlewares can be chained, the befores will be executed in reverse declaration order (FIFO), the afters in direct declaration order (LIFO).

Gives this output :

You can apply a middleware to multiple routes a single time using a RouteGroup :

Dispatching routes

Remember to invoke the dispatch method before script end for route execution.

You can override the request URI and method passing them as parameters to the dispatch method :

Example :

The matched (if any) route can be returned without being automatically executed passing true to the return_route parameter :

Route can't find a match. (HTTP 404)

When no routes matches the current request, the 404 event is triggered.

You can append a view to the Response to show a courtesy page.

Render shortcuts

Instead of the rendering callback, you can also pass a string or a view, for direct rendering.

Closure

A View

A string (not a callable one)

An object

HTTP/2 Resource Push

You can push resources directly from the Route and RouteGroup definitions.
The syntax is the same as for the Response::push method.

URL tagging and Reverse Routing

You can add a name tag to a route via the tag method :

A named route is retrieved via the Route::tagged($name) method :

To get the URL for a route use the getURL($params = []) method :

As a shorthand, you can obtain the URL for the named route via the Route::URL($name, $params = []) helper :

You can also pass an array to map and assign the dynamic values of the route.

Note: The returned value of the Route::URL method is an [[URL]] object.

Events and Filters

Route has the Events trait behaviour, the only difference is that the Events::on method is renamed to onEvent to avoid collisions with the Route::on handler.

Available Events

Available Filters