---
Hoa is a modular, extensible and
structured set of PHP libraries.
Moreover, Hoa aims at being a bridge between industrial and research worlds.
# Hoa\Router
[](https://webchat.freenode.net/?channels=#hoaproject)
[](https://gitter.im/hoaproject/central)
[](https://central.hoa-project.net/Documentation/Library/Router)
[](https://waffle.io/hoaproject/router)
This library allows to find an appropriated route and extracts data from a
request. Conversely, given a route and data, this library is able to build a
request.
For now, we have two routers: HTTP (routes understand URI and subdomains) and
CLI (routes understand a full command-line).
[Learn more](https://central.hoa-project.net/Documentation/Library/Router).
## Installation
With [Composer](https://getcomposer.org/), to include this library into
your dependencies, you need to
require [`hoa/router`](https://packagist.org/packages/hoa/router):
```sh
$ composer require hoa/router '~3.0'
```
For more installation procedures, please read [the Source
page](https://hoa-project.net/Source.html).
## Testing
Before running the test suites, the development dependencies must be installed:
```sh
$ composer install
```
Then, to run all the test suites:
```sh
$ vendor/bin/hoa test:run
```
For more information, please read the [contributor
guide](https://hoa-project.net/Literature/Contributor/Guide.html).
## Quick usage
We propose a quick overview of two usages: in a HTTP context and in a CLI
context.
### HTTP
We consider the following routes:
* `/hello`, only accessible with the `GET` and `POST` method;
* `/bye`, only accessible with the `GET` method;
* `/hello_` only accessible with the `GET` method.
There are different ways to declare routes but the more usual is as follows:
```php
$router = new Hoa\Router\Http();
$router
->get('u', '/hello', function () {
echo 'world!', "\n";
})
->post('v', '/hello', function (Array $_request) {
echo $_request['a'] + $_request['b'], "\n";
})
->get('w', '/bye', function () {
echo 'ohh :-(', "\n";
})
->get('x', '/hello_(?\w+)', function ($nick) {
echo 'Welcome ', ucfirst($nick), '!', "\n";
});
```
We can use a basic dispatcher to call automatically the associated callable of
the appropriated rule:
```php
$dispatcher = new Hoa\Dispatcher\Basic();
$dispatcher->dispatch($router);
```
Now, we will use [cURL](http://curl.haxx.se/) to test our program that listens
on `127.0.0.1:8888`:
```sh
$ curl 127.0.0.1:8888/hello
world!
$ curl -X POST -d a=3\&b=39 127.0.0.1:8888/hello
42
$ curl 127.0.0.1:8888/bye
ohh :-(
$ curl -X POST 127.0.0.1:8888/bye
// error
$ curl 127.0.0.1:8888/hello_gordon
Welcome Gordon!
$ curl 127.0.0.1:8888/hello_alyx
Welcome Alyx!
```
This simple API hides a modular mechanism that can be foreseen by typing
`print_r($router->getTheRule())`.
To unroute, i.e. make the opposite operation, we can do this:
```php
var_dump($router->unroute('x', array('nick' => 'gordon')));
// string(13) "/hello_gordon"
```
### CLI
We would like to recognize the following route `[:]?
` in the `Router.php` file:
```php
$router = new Hoa\Router\Cli();
$router->get(
'g',
'(?\w+):(?\w+)(?.*?)'
function ($group, $subcommand, $options) {
echo
'Group : ', $group, "\n",
'Subcommand: ', $subcommand, "\n",
'Options : ', trim($options), "\n";
}
);
```
We can use a basic dispatcher to call automatically the associated callable:
```php
$dispatcher = new Hoa\Dispatcher\Basic();
$dispatcher->dispatch($router);
```
And now, testing time:
```sh
$ php Router.php foo:bar --some options
Group : foo
Subcommand: bar
Options : --some options
```
The use of the [`Hoa\Console`
library](https://central.hoa-project.net/Resource/Library/Console) would be a
good idea to interprete the options and getting some comfortable services for
the terminal.
## Documentation
The
[hack book of `Hoa\Router`](https://central.hoa-project.net/Documentation/Library/Router)
contains detailed information about how to use this library and how it works.
To generate the documentation locally, execute the following commands:
```sh
$ composer require --dev hoa/devtools
$ vendor/bin/hoa devtools:documentation --open
```
More documentation can be found on the project's website:
[hoa-project.net](https://hoa-project.net/).
## Getting help
There are mainly two ways to get help:
* On the [`#hoaproject`](https://webchat.freenode.net/?channels=#hoaproject)
IRC channel,
* On the forum at [users.hoa-project.net](https://users.hoa-project.net).
## Contribution
Do you want to contribute? Thanks! A detailed [contributor
guide](https://hoa-project.net/Literature/Contributor/Guide.html) explains
everything you need to know.
## License
Hoa is under the New BSD License (BSD-3-Clause). Please, see
[`LICENSE`](https://hoa-project.net/LICENSE) for details.