, (*1)
, (*2)
Hoa is a modular, extensible and
structured set of PHP libraries.
Moreover, Hoa aims at being a bridge between industrial and research worlds.
, (*3)
Hoa\Router
, (*4)
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., (*5)
For now, we have two routers: HTTP (routes understand URI and subdomains) and
CLI (routes understand a full command-line)., (*6)
Learn more., (*7)
Installation
With Composer, to include this library into
your dependencies, you need to
require hoa/router
:, (*8)
$ composer require hoa/router '~3.0'
For more installation procedures, please read the Source
page., (*9)
Testing
Before running the test suites, the development dependencies must be installed:, (*10)
$ composer install
Then, to run all the test suites:, (*11)
$ vendor/bin/hoa test:run
For more information, please read the contributor
guide., (*12)
Quick usage
We propose a quick overview of two usages: in a HTTP context and in a CLI
context., (*13)
HTTP
We consider the following routes:, (*14)
-
/hello
, only accessible with the GET
and POST
method;
-
/bye
, only accessible with the GET
method;
-
/hello_<nick>
only accessible with the GET
method.
There are different ways to declare routes but the more usual is as follows:, (*15)
$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_(?<nick>\w+)', function ($nick) {
echo 'Welcome ', ucfirst($nick), '!', "\n";
});
We can use a basic dispatcher to call automatically the associated callable of
the appropriated rule:, (*16)
$dispatcher = new Hoa\Dispatcher\Basic();
$dispatcher->dispatch($router);
Now, we will use cURL to test our program that listens
on 127.0.0.1:8888
:, (*17)
$ 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())
., (*18)
To unroute, i.e. make the opposite operation, we can do this:, (*19)
var_dump($router->unroute('x', array('nick' => 'gordon')));
// string(13) "/hello_gordon"
CLI
We would like to recognize the following route [<group>:]?<subcommand>
<options>
in the Router.php
file:, (*20)
$router = new Hoa\Router\Cli();
$router->get(
'g',
'(?<group>\w+):(?<subcommand>\w+)(?<options>.*?)'
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:, (*21)
$dispatcher = new Hoa\Dispatcher\Basic();
$dispatcher->dispatch($router);
And now, testing time:, (*22)
$ php Router.php foo:bar --some options
Group : foo
Subcommand: bar
Options : --some options
The use of the Hoa\Console
library would be a
good idea to interprete the options and getting some comfortable services for
the terminal., (*23)
Documentation
The
hack book of Hoa\Router
contains detailed information about how to use this library and how it works., (*24)
To generate the documentation locally, execute the following commands:, (*25)
$ composer require --dev hoa/devtools
$ vendor/bin/hoa devtools:documentation --open
More documentation can be found on the project's website:
hoa-project.net., (*26)
Getting help
There are mainly two ways to get help:, (*27)
Contribution
Do you want to contribute? Thanks! A detailed contributor
guide explains
everything you need to know., (*28)
License
Hoa is under the New BSD License (BSD-3-Clause). Please, see
LICENSE
for details., (*29)