Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
14 changed files
with
499 additions
and
941 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,123 @@ | ||
# Defining routes | ||
|
||
There are few ways to define routes. You can build the [Route][] instances yourself or use the route | ||
collector. Whatever you choose you will end up with a variant of [RouteProvider][]. | ||
|
||
## Defining routes by hand | ||
|
||
To define your routes and hand, you need to create instance of [Route][] and store them in an | ||
instance of either [RouteProvider\Mutable][] or [RouteProvider\Immutable][], depending on whether you | ||
want to be able to add routes later or not. | ||
|
||
```php | ||
<?php | ||
|
||
namespace ICanBoogie\Routing; | ||
|
||
use ICanBoogie\Routing\RouteProvider\Mutable; | ||
|
||
$routes = new Mutable(); | ||
$routes->add_routes( | ||
new Route('/', 'page:home'), | ||
new Route('/about.html', 'page:about'), | ||
); | ||
|
||
use ICanBoogie\Routing\RouteProvider\Mutable; | ||
|
||
$routes = new Imutable([ | ||
new Route('/', 'page:home'), | ||
new Route('/about.html', 'page:about'), | ||
]); | ||
``` | ||
|
||
## Defining routes using the collector | ||
|
||
The route collector offers a convenient fluent interface to define your routes. | ||
|
||
```php | ||
<?php | ||
|
||
namespace ICanBoogie\Routing; | ||
|
||
$routes = (new RouteCollector()) | ||
->route('/', 'page:home') | ||
->get('/contact.html', 'contact:new') | ||
->post('/contact.html', 'contact:create') | ||
->resource('photos') | ||
->collect(); | ||
``` | ||
|
||
#### Defining resource routes using `RouteMaker` | ||
|
||
Given a resource name and a controller, the `RouteMaker::resource()` method makes the various | ||
routes required to handle a resource. Options can be specified to filter the routes to create, | ||
specify the name of the _key_ property and/or it's regex constraint, or name routes. | ||
|
||
The following example demonstrates how to create routes for an _article_ resource: | ||
|
||
```php | ||
<?php | ||
|
||
namespace App; | ||
|
||
use ICanBoogie\Routing\RouteMaker as Make; | ||
|
||
// create all resource actions definitions | ||
$definitions = Make::resource('articles', ArticlesController::class); | ||
|
||
// only create the _list_ definition | ||
$definitions = Make::resource('articles', ArticlesController::class, [ | ||
|
||
Make::OPTION_ONLY => Make::ACTION_LIST | ||
|
||
]); | ||
|
||
// only create the _list_ and _show_ definitions | ||
$definitions = Make::resource('articles', ArticlesController::class, [ | ||
|
||
Make::OPTION_ONLY => [ Make::ACTION_LIST, Make::ACTION_SHOW ] | ||
|
||
]); | ||
|
||
// create definitions except _destroy_ | ||
$definitions = Make::resource('articles', ArticlesController::class, [ | ||
|
||
Make::OPTION_EXCEPT => Make::ACTION_DELETE | ||
|
||
]); | ||
|
||
// create definitions except _updated_ and _destroy_ | ||
$definitions = Make::resource('articles', PhotosController::class, [ | ||
|
||
Make::OPTION_EXCEPT => [ Make::ACTION_UPDATE, Make::ACTION_DELETE ] | ||
|
||
]); | ||
|
||
// specify _key_ property name and its regex constraint | ||
$definitions = Make::resource('articles', ArticlesController::class, [ | ||
|
||
Make::OPTION_ID_NAME => 'uuid', | ||
Make::OPTION_ID_REGEX => '{:uuid:}' | ||
|
||
]); | ||
|
||
// specify the identifier of the _create_ definition | ||
$definitions = Make::resource('articles', ArticlesController::class, [ | ||
|
||
Make::OPTION_AS => [ | ||
|
||
Make::ACTION_CREATE => 'articles:build' | ||
|
||
] | ||
|
||
]); | ||
``` | ||
|
||
> **Note:** It is not required to define all the resource actions, only define the one you actually need. | ||
|
||
|
||
[Route]: ../lib/Route.php | ||
[RouteProvider]: ../lib/RouteProvider.php | ||
[RouteProvider\Mutable]: ../lib/RouteProvider/Mutable.php | ||
[RouteProvider\Immutable]: ../lib/RouteProvider/Immutable.php |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,35 @@ | ||
# Route Providers | ||
|
||
Route providers are used to find the route that matches a predicate. Several route provider | ||
implementations are available, for flexibility and performance. And several predicate implementation | ||
are available to match routes by an action or a URI. Simple route providers are often decorated with | ||
more sophisticated ones that can improve performance. | ||
|
||
## Predicates | ||
|
||
Route providers implement the [RouteProvider][] interface. The `route_for_predicate()` method is used to find a route | ||
that matches a predicate. A predicate can be as simple as a callable. The following predicates come built-in: | ||
|
||
- [RouteProvider\ById][]: Matches a route against an identifier. | ||
- [RouteProvider\ByAction][]: Matches a route against an action. | ||
- [RouteProvider\ByUri][]: Matches a route against a URI and an optional method. Path parameters and query parameters | ||
are captured in the predicate. | ||
|
||
The following example demonstrates how to find route matching a URL and method, using the `ByUri` predicate: | ||
|
||
```php | ||
<?php | ||
|
||
use ICanBoogie\HTTP\RequestMethod; | ||
use ICanBoogie\Routing\RouteProvider\ByUri; | ||
|
||
/* @var ICanBoogie\Routing\RouteProvider $route_provider */ | ||
|
||
$route = $route_provider->route_for_predicate($predicate = new ByUri('/?singer=madonna')); | ||
echo $route->action; // "home" | ||
var_dump($predicate->query_params); // [ 'singer' => 'madonna' ] | ||
|
||
$route = $route_provider->route_for_predicate($predicate = new ByUri('/articles/123', RequestMethod::METHOD_DELETE)); | ||
echo $route->action; // "articles:show" | ||
var_dump($predicate->path_params); // [ 'nid' => 123 ] | ||
``` |
Oops, something went wrong.