Routing

• Introduction
• URL Mapping
  • Using the route method
    • List of options
  • Using HTTP verbs as methods
  • List of possibilities
• Mapping methods
  • Mapping with get
  • Mapping with post
  • Mapping with put
  • Mapping with delete
  • Mapping with patch
  • Mapping with options
• Multiple mapping
  • Mapping with match
  • Mapping with any
  • Mapping with prefix
• Customization
  • Capturing variables in the URL
  • Adding criteria and restrictions to URLs
  • Naming routes
  • Middleware association
    • Action composition

Introduction

Routing allows you to map a URL to a specific controller or action. Bow's routing system is grafted directly onto the application instance, so onto the $app variable, which is a super global variable.

The application's routes are located in the app.php file inside the routing folder of your application.

URL Mapping

Using the route method

This method allows you to set up a relatively simple mapping.

$app->route([
  'path' => '/',
  'method' => "GET",
  'handler' => 'handler'
]);

List of options

Parameter	Type	Description
path	String	The URL pattern to match
method	String, Array	HTTP method
handler	String, Array	The action to run
middleware	String, Array	Middleware
where	String, Array	Constraint applied to the URL
name	String, Array	The name of the route

method corresponds to the http verb to associate with the route, either GET, POST, PUT, DELETE, OPTIONS, PATCH.

• With a closure

$app->route([
  'path' => '/',
  'method' => "GET",
  'handler' => function () {
    return "Hello, bow";
  }
]);

• With a controller name.

$app->route([
  'path' => '/',
  'method' => "GET",
  'handler' => 'HomeController::action'
]);

More information about controllers here

• With a controller name and a middleware.

$app->route([
  'path' => '/',
  'method' => "GET",
  'handler' => 'HomeController::show',
  'middleware' => ['auth']
]);

More information about middleware here

• With a controller name, a middleware, and a restriction.

$app->route([
  'path' => '/:name',
  'method' => "GET",
  'handler' => 'HomeController::show',
  'middleware' => ['auth'],
  'where' => ['name' => '[a-z]+']
]);

More information about restrictions here

Using HTTP verbs as methods

Prototype of the routing methods.

$app->[method](url, action);

method corresponds to the http verb to associate with the route, either GET, POST, PUT, DELETE, OPTIONS, PATCH written in lowercase.

Parameter	Type	Description
url	String	The URL pattern to match
action	String, Array	Closure or Callable

• With a closure

$app->get('/', function ()
{
  return 'hello world';
});

A Closure is a so-called anonymous function (More information on the subject).

• With a collection of functions in an array:

$callables = [];

$callables[] = function ()
{
  echo 'hello world';

  return true;
};

$callables[] = function ()
{
  echo 'Bien merci';
};

$app->get('/', $callables);

Note that the first function ends with a return true statement; this statement is essential if you want the next function to run. This means that if it is a return false, the following function will not be executed.

• With a controller name

$app->[method]('/', 'ClassController::action');

• With a controller name and a middleware

$app->[method]('/', ['middleware' => 'ip', 'controller' => 'ClassController::action']);

method corresponds to the http verb to associate with the route, either GET, POST, PUT, DELETE, OPTIONS, PATCH written in lowercase.

List of possibilities

$app->get($url, $action);
$app->post($url, $action);
$app->put($url, $action);
$app->delete($url, $action);
$app->option($url, $action);
$app->patch($url, $action);

Mapping methods

Routing is therefore set up through the following methods:

Mapping with get

This method allows you to map a URL to a GET request.

$app->get('/', function ()
{
  return 'hello world';
});

Mapping with post

This method allows you to map a URL to a POST request.

$app->post('/', function ()
{
  return 'data posted';
});

Mapping with put

This method allows you to map a URL to a PUT request.

$app->put('/', function ()
{
  // Code here
});

Mapping with delete

This method allows you to map a URL to a DELETE request.

$app->delete('/', function ()
{
  // Code here
});

Mapping with patch

This method allows you to map a URL to a PATCH request.

$app->patch('/', function ()
{
  // Code here
});

Mapping with options

This method allows you to map a URL to an OPTIONS request.

$app->options('/', function ()
{
  // Code here
});

The DELELTE, PUT, and PATCH methods are not supported by the browser.

Browsers do not support this method. So in your submission form, you will need to create a field like this:

<input type="hidden" name="_method" value="DELETE">

The purpose of this is to allow Bow to understand your request, and it applies to PUT and PATCH as well.

All the methods defined above return an instance of Bow\Router\Route::class. (More information on the Bow\Router\Route::class)

Multiple mapping

Mapping with match

Allows you to associate http methods with the specified URL.

Prototype of the match method.

$app->match(verbes, url, action);

Parameter	Type	Description
verbes	Array	The list of http methods
url	String	The route's URL
action	String, Array, Closure	The action to run

$app->match(['GET', 'POST'], '/users', function ()
{
  // Code here
});

You could have code that does this.

use Bow\Http\Request;

$app->match(['GET', 'POST'], '/users', function (Request $request)
{
  if ($request->isPost()) {
    // code
  } else {
    // code
  }
});

More information about HTTP requests.

Mapping with any

Allows you to associate all http methods with the specified URL.

Prototype of the any method.

$app->any(url, action);

Parameter	Type	Description
url	String	The route's URL
action	String, Array	Closure - The action to run

$app->any('/', function ()
{
  // Code here
});

Mapping with prefix

Often you will need to group your routes and perform a simple branching to properly organize your logic. URLs can often repeat like this:

$app->get('users', function ()
{
  // Code here
});

$app->get('users/:id', function ($id)
{
  // Code here
});

$app->get('users/:id/delete', function ($id)
{
  // Code here
});

In this case, we have users repeated several times. How do we organize all of this properly? The answer is route prefixing. So the prefix method allows us to group several URLs.

Prototype of the prefix method.

$app->prefix(url, action);

Parameter	Type	Description
url	String	The URL to prefix
action	Closure	This function will take the application instance as a parameter

So to reorganize the previous code, you would do the following:

$app->prefix('/users', function () use ($app)
{
  $app->get('/', function ()
  {
   // Code here
  });
  $app->get('/:id', function ($id)
  {
   // Code here
  });
  $app->get('/:id/delete', function ($id)
  {
   // Code here
  });
});

Note that, currently, prefixing cannot be nested.

Customization

Routing also allows you to customize your URLs. Here is the list of customization possibilities.

• Capturing variables in the URL
• Adding criteria and restrictions to URLs
• Naming routes
• Middleware association
• Action composition

To do the customization, you need to use method chaining. In the following example, we will use the get method.

Capturing variables in the URL

Routing lets you capture variables in URLs. To do this, you must use the :variable_name notation. The captured variable will then be passed as a parameter to the action (the function to execute when the URL is valid), regardless of the number of variables.

$app->get('/:name', function ($name)
{
  return 'Bonjour ' . $name;
});

Adding criteria and restrictions to URLs

Speaking of variable capture, securing these variables is essential, so routing also lets you add validators to the variables. The where method handles this.

Prototype of the where method.

where(name, rule);
// or
where(array rules);

Parameter	Type	Description
name	String	The name of the variable
value	String	The validation criterion
rules	Array	Associative array whose key is the variable to secure and whose value is the validation criterion

$app->get('/:name', function ($name)
{
  return 'Bonjour ' . $name;
})->where('name', '[a-z]+');

// If there are multiple variables
$callable = function ($name, $lastname, $number)
{
  return sprintf(
    'Bonjour <b>%s %s</b>, votre numéro est %s.', $name, $lastname, $number
  );
};

$app->get('/:name/:lastname/:number', $callable)
  ->where([
    'name' => '[a-z]+',
    'lastname' => '[a-z]+',
    'number' => '\d+'
  ]);

Note that where is a method of the Bow\Router\Route instance.

Naming routes

When you are developing a large project, the routes will become numerous and visual management for the developer will become difficult, so Bow lets you give names to your routes so you can reference them more easily afterward. The name method associated with a route instance lets you do this.

Prototype of the name method.

name(name);

Parameter	Type	Description
name	String	The name of the route

$app->get('/:name', function ($name)
{
  return 'Bonjour ' . $name;
})->name('hello');

Middleware association

A middleware is one or more actions that sit between the request and the action to be executed. All modern frameworks are equipped with them.

For more information on the subject, go to this link middleware

$app->get('/:name', ['middleware' => 'ip', function ($name)
{
  return 'Bonjour ' . $name;
}]);

// Or
$app->get('/:name', function ($name) {
  return 'Bonjour ' . $name;
})->middleware('ip');

Action composition

$app->get('/:name', [
  'middleware' => 'ip',
  'controller' => 'NameController::action'
]);

Is something missing?

If you run into problems with the documentation or have suggestions to improve the documentation or the project in general, please open an issue for us, or send a tweet mentioning the Twitter account @bowframework or directly on github.