https://github.com/bugadani/routy

A PHP request router
https://github.com/bugadani/routy

Last synced: 8 months ago
JSON representation

A PHP request router

• Host: GitHub
• URL: https://github.com/bugadani/routy
• Owner: bugadani
• License: mit
• Created: 2015-11-18T14:44:05.000Z (over 10 years ago)
• Default Branch: master
• Last Pushed: 2016-02-15T08:30:34.000Z (over 10 years ago)
• Last Synced: 2025-01-13T02:43:17.465Z (over 1 year ago)
• Language: PHP
• Size: 27.3 KB
• Stars: 0
• Watchers: 4
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
Routy

=============

Routy is a request routing library for PHP. It is designed to be simple to use.

Basic usage

-----------

The `Router` class is the central element of the library that provides a simple API for most of the simple use-cases.

Defining a route is as easy as calling the method with the same name as the route's HTTP method and passing the path as a parameter.

    $router = new Routy\Router();

    $router->get('this/path');

Available methods are:

 * `get($path)`

 * `post($path)`

 * `put($path)`

 * `delete($path)`

 * `head($path)`

You can also define parameters in routes by wrapping a name in curly braces (e.g. `{parameterName}`).

A parameter consists a name and a pattern. By default, a parameter matches anything that is not a forward slash character (`/`),

but this can be overridden in the parameter definition by adding the desired pattern after the name, separated by a colon (`;`). The parameter definition follows the syntax of PHP's built-in PREG engine.

Example route that matches words as parameter: `hello/{name:\w+}`.

*Note*: Routes are identified by their parameters' patterns, not their names. Because of this, two routes may be similar in structure if they have different parameter patterns.

Routing the request is done with `match(Request $request)` or `matchCurrentRequest`. This will either throw an exception or return a `Match` instance that holds information about the matched route.

Using `add`, a route can be defined for multiple HTTP methods at once. To do this, pass the desired method names separated by a pipe ('|') character as the first argument.

    $router->add('GET|POST', 'some/path');

### Options

The above methods return an instance of `Routy\Initializers\RouteInitializerInterface` which can be used to set names

to the routes, specify a callback that will be called if a route is matched or to set extra information.

A more full route definition looks like this:

    $router->get('some/path')

           ->name('demoRoute')

           ->onMatch(function($name) { echo 'Hello ' . $name; })

           ->extras(['name' => 'World']);

 * `setName($name)`

 * `onMatch(callback)`: Because using the `Match` object that is returned by `match` can be cumbersome, a callback function can be supplied for each route that will be called when the route is matched.

 * `extras(array $extras)`: Sets extra information to the route in the form of a key-value pair.

*Note*: adding routes for multiple methods create multiple separate routes. Because one route name can not belong to multiple routes,

when using add to define multiple routes, setting the name using the returned Initializer will throw an exception.

### Route callbacks

Using `onMatch` a callback can be defined for the routes. This is the easiest way to decide, which route was matched and what action should be taken.

By default, the callback will receive the matched parameters (and extras set on the route) in the parameter list. Parameters are passed by their names and are actually optional.

    $callback = function($name = 'World') {echo 'Hello, ' . $name . '!';};

    $router->get('hello)')->onMatch($callback);

    $router->get('hello/me)')->extras('name' => 'Daniel')->onMatch($callback);

    $router->get('hello/{name)')->onMatch($callback);

The mapping of the parameters are done by an instance of `Routy\Invokers\DelegateInterface` and the default

behaviour can be overridden by supplying a subclass of this interface to `onMatch` that wraps the callback function.

### Generating URL-s

Using named routes, Routy can also generate URLs via the `to($routeName, array $parameters)` method. All of the route's parameters

must be supplied as the second argument, and extra ones will be appended to the URL as further GET parameters.

    $router->get('hello/{name}')->name('hello');

    echo $router->to('hello', ['name' => 'World', 'extra' => 'hi']); //prints "hello/World?extra=hi"

### Resources

Routy supports [Rails-like](http://guides.rubyonrails.org/routing.html#resource-routing-the-rails-default) resources.

A resource can be defined by using `resource($name)`, or `resources($singularName, $pluralName)`.

### Notes on HHVM

Routy is tested on HHVM 3.6.6 and it is found that the basic function of the library works with one exception:

Since route generation happens in an object's destructor, any exception thrown in there will crash the whole script.

This is not an issue in PHP, but the HHVM actually issues a fatal error in this case, which makes the thrown exceptions

fatal and not catchable.