Routing

Starting the router
Registering routes
Available placeholders
Creating routing filters
Run the router

Starting the router

$router = new Router();

Registering routes

Registering a single route

$router->register('api/users/(:any)', array(
  'method' => 'GET',
  'action' => function($username) {
    // the router action code
  }
));

Registering multiple routes

$router->register(array(
  array(
    'pattern' => 'api/users/(:any)',
    'method'  => 'GET',
    'action'  => function($username) {
      // the router action code
    }
  ),
  array(
    'pattern' => 'api/users/(:any)',
    'method'  => 'DELETE',
    'action'  => function($username) {
      // the router action code
    }
  )
));

Registering a route for multiple request methods

$router->register('api/users/(:any)', array(
  'method' => 'GET|POST|DELETE',
  'action' => function($username) {
    // the router action code
  }
));

Registering a route for all incoming requests

$router->register('api/users/(:any)', array(
  'method' => 'ALL',
  'action' => function($username) {
    // the router action code
  }
));

2.4.0 +

Restricting a route to a specific host

$router->register('api/users/(:any)', array(
  'method' => 'GET',
  'host'   => 'getkirby.com',
  'action' => function($username) {
    // the router action code
  }
));

Available placeholders

URL patterns for routes can be static, relative URLs: some/static/url or parts of the URL can be defined by dynamic placholders:

Placeholder	Matches
(:any)	Matches any character and stops at the next /
(:num)	Matches any number and stops at the next /
(:all)	Matches everything from here on until the end or the next placeholder

Placeholders can also contain expressions. I.e. ([a-z]+)
Placeholders will be passed as arguments in the order they appear.

// my/awesome/pattern/(:any)/(:num)/(:all)
function($anyPlaceholder, $numPlaceholder, $allPlaceholder) {

};

Optional placeholders

Optional attributes can be defined by adding a question mark to the placeholder:

- (:any?)
- (:num?)
- (:all?)

Creating routing filters

Routing filters are run before the route function. They can be used to check for user authentication/authorization or they can check if a route is applicable for the current environment.

Registering routing filters globally

You can register routing filters globally to use them in many of your routes at once:

$router->filter('auth', function($route) {
  // some authentication checks
  // $route is the route array
});

Applying a global filter to a route

$router->register('api/users/(:any)', array(
  'method' => 'ALL',
  'filter' => 'auth',
  'action' => function($username) {
    // the router action code
  }
));

Applying multiple global filters to a route

$router->register('api/users/(:any)', array(
  'method' => 'ALL',
  'filter' => 'auth|someotherfilter',
  'action' => function($username) {
    // the router action code
  }
));

You can also use this syntax:

$router->register('api/users/(:any)', array(
  'method' => 'ALL',
  'filter' => ['auth', 'someotherfilter'],
  'action' => function($username) {
    // the router action code
  }
));

2.5.3 +

Using a routing filter for just one route

You can also pass an anonymous function to a route directly if the filter is supposed to be applied to only that route:

$router->register('api/users/(:any)', array(
  'method' => 'ALL',
  'filter' => function($route) {
    // some checks
    // $route is the route array
  },
  'action' => function($username) {
    // the router action code
  }
));

Skipping routes from a routing filter

A routing filter can return false. This will tell the router to skip the route and try the next matching one.

Run the router

if($route = $router->run()) {
  $response = call($route->action(), $route->arguments());
}