Routing

Routes are declared in config/routes.raku with a declarative DSL. A routes block builds a router that maps an incoming method and path to a controller action or an inline handler.

use MVC::Keayl::Routing;

routes {
  root to => 'home#index';

  get  '/users', to => 'users#index';
  post '/users', to => 'users#create';

  match '/search', to => 'search#run', via => <get post>;
}

The draw block

routes (and its alias draw) takes a block and returns a MVC::Keayl::Router. Inside the block the verb helpers register routes on that router.

At boot the application loads the routes file with load-routes:

my $router = load-routes('config/routes.raku');

load-routes evaluates the file and returns the router its routes block built.

Verb helpers

get, post, put, patch, delete, and options each declare a route for that method. The target is given with to:

get '/users', to => 'users#index';   # controller#action
get '/ping',  to => sub { 'pong' };  # inline callable

A 'controller#action' string target is split into a controller and an action. A Callable target is kept as an inline handler. A GET route also answers HEAD.

match and via

match registers one path for several verbs. via accepts a single verb, a list of verbs, the string 'all', or * for every verb:

match '/search', to => 'search#run', via => <get post>;
match '/health', to => 'health#show', via => 'all';
match '/any',    to => 'catch#all',   via => *;

root

root maps GET / to a target and names the route root:

root to => 'home#index';

Path patterns

A path can carry dynamic segments, a glob, optional groups, a format, and per-segment constraints. The matched values become params on recognition.

get '/users/:id',          to => 'users#show';     # :id captures one segment
get '/files/*path',        to => 'files#serve';    # *path captures the rest, slashes included
get '/users(/:id)',        to => 'users#index';    # (...) is an optional group
get '/users/:id(.:format)', to => 'users#show';    # (.:format) peels off an extension

A :segment matches a single path segment, stopping at a / or a .. A *glob matches everything that remains, including slashes. Anything inside (...) is optional.

format => True appends an optional (.:format) segment without writing it out:

get '/users/:id', to => 'users#show', format => True;

defaults supplies values for params that are absent from the path, and constraints restricts a segment to a pattern. A request whose segment fails the constraint falls through to the next route:

get '/users/:id', to => 'users#show',
  constraints => { id => /^\d+$/ },
  defaults    => { format => 'html' };

Resources

resources declares the seven REST routes for a resource in one call:

resources 'users';

Pass several names to declare more than one resource at once:

resources 'users', 'posts';

Limiting actions

only and except choose which of the seven actions to generate:

resources 'users', :only<index show>;
resources 'photos', :except<destroy>;

Member and collection routes

A block adds extra routes. member routes act on a single record (/:id), collection routes act on the set:

resources 'photos', {
  member {
    get 'preview', to => 'photos#preview';      # GET /photos/:id/preview
  }
  collection {
    get 'search', to => 'photos#search';        # GET /photos/search
  }
}

on does the same for a single route without a block:

resources 'photos', {
  get 'stats', to => 'photos#stats', on => 'collection';
}

Member route names are suffixed with the singular (preview-photo), collection routes with the plural (search-photos).

Resource options

resources 'people',
  path        => 'team',
  controller  => 'staff',
  param       => 'slug',
  path-names  => { new => 'neu', edit => 'bearbeiten' };

Singular resources

resource declares a resource with no index and no :id, for a thing there is only one of per request (a profile, an account):

resource 'profile';

The controller defaults to the plural (profiles). resource takes the same options as resources (only, except, path, as, controller, module, path-names, and member/collection blocks).

Nesting

Resources nest inside a resource block. A nested resource is scoped under the parent member, and its key is named after the parent:

resources 'magazines', {
  resources 'ads';
}

This produces /magazines/:magazine_id/ads, /magazines/:magazine_id/ads/:id, and so on, with helper names prefixed by the parent singular (magazine-ads, magazine-ad, new-magazine-ad, edit-magazine-ad). Plural and singular resources nest either way, and nesting can go more than one level deep, though nesting more than one level deep is usually a sign the routes want flattening.

Shallow nesting

shallow keeps the collection routes (index, new, create) nested but lifts the member routes (show, edit, update, destroy) to the top level, so member URLs stay short:

resources 'magazines', :shallow, {
  resources 'ads';
}

Collection routes stay at /magazines/:magazine_id/ads, while member routes move to /ads/:id. The member helpers drop the parent prefix (ad rather than magazine-ad). shallow-path overrides the shallow member segment and shallow-prefix overrides the shallow member name prefix:

resources 'ads', :shallow, :shallow-path<a>, :shallow-prefix<x>;

Namespaces and scopes

namespace prefixes the path, the controller module, and the helper name all at once:

namespace 'admin', {
  resources 'users';        # /admin/users => admin/users, named admin-users
}

scope controls each of those independently:

scope(path => 'api', module => 'v1', as => 'api', {
  get '/ping', to => 'ping#show', as => 'ping';   # /api/ping => v1/ping#show, named api-ping
});

controller sets the controller for the routes inside, so a target can be just an action and a bare path defaults its action:

controller 'photos', {
  get '/preview', to => 'show';   # photos#show
  get '/list';                    # photos#list
}

An optional scope segment is written with parentheses, which suits an i18n locale prefix that may or may not be present:

scope('(:locale)', {
  get '/about', to => 'pages#about';   # matches /about and /en/about
});

Scopes nest and compose their prefixes.

Concerns

A concern is a reusable block of routes. Define it once with concern, then mix it into resources with the concerns option or a concerns call inside a block:

concern 'commentable', { resources 'comments' };

resources 'posts', concerns => 'commentable';
resources 'photos', { concerns 'commentable' };

Concern routes nest under the resource that mixes them in, so /posts/:post_id/comments and /photos/:photo_id/comments both appear.

Constraints and defaults

A constraints block restricts the routes inside it. Segment keys constrain path params, while subdomain, host, format, protocol, port, and method constrain request attributes:

constraints(:id(/^\d+$/), {
  get '/items/:id', to => 'items#show';        # /items/42 matches, /items/abc does not
});

constraints(:subdomain<api>, {
  get '/data', to => 'data#index';             # only when the request subdomain is api
});

A custom constraint is a callable that receives the request context, or an object with a matches method:

constraints(-> %context { %context<host>.ends-with('.internal') }, {
  get '/admin', to => 'admin#index';
});

Request constraints are checked during recognition against a context hash:

$router.recognize('GET', '/data', context => { subdomain => 'api' });

A defaults block supplies default params for the routes inside it:

defaults(format => 'json', {
  get '/api/users', to => 'users#index';       # params include format => 'json'
});

Redirects and mounting

A route can redirect instead of dispatching to a controller. redirect takes a string or a block that computes the location from the params, and an optional status:

get '/stories',     to => redirect('/articles');
get '/movies/:id',  to => redirect(-> %params { '/films/' ~ %params<id> }, status => 302);

mount attaches a sub-app at a path. The mount matches the mount point and everything below it, capturing the remainder as mounted_path:

mount $rack-app, at => '/legacy';   # matches /legacy and /legacy/...

URL helpers

MVC::Keayl::Routing::UrlHelpers generates paths and URLs from named routes. path-for fills the segments, turns leftover params into a sorted query string, and handles anchor and trailing-slash:

my $helpers = MVC::Keayl::Routing::UrlHelpers.new(:$router);

$helpers.path-for('user', 5);                       # /users/5
$helpers.path-for('user', 5, page => 2);            # /users/5?page=2
$helpers.path-for('user', 5, anchor => 'comments'); # /users/5#comments

url-for builds an absolute URL from default-url-options (host, protocol, port), each overridable per call. The name-path and name-url helpers also resolve through FALLBACK:

my $helpers = MVC::Keayl::Routing::UrlHelpers.new(:$router, :default-url-options({ host => 'example.com' }));

$helpers.url-for('user', 5);    # http://example.com/users/5
$helpers.user-path(5);          # /users/5
$helpers.users-url;             # http://example.com/users

Custom and polymorphic helpers

direct registers a helper computed by a block. polymorphic-path and url-for dispatch a record to its route by class name and persistence state, and resolve customizes that mapping:

direct 'homepage', -> { 'https://example.com' };
resolve 'Basket', -> $basket { ('cart',) };

$helpers.homepage-url;                        # https://example.com
$helpers.polymorphic-path($persisted-post);   # /posts/7
$helpers.polymorphic-path($new-post);         # /posts
$helpers.url-for($post);                       # dispatches polymorphically

Recognition

The router answers recognize($method, $path), returning a match or an undefined match when nothing fits. A context hash supplies request attributes for request constraints:

my $match = $router.recognize('GET', '/users/42');

$match.controller;   # 'users'
$match.action;       # 'show'
$match.params;       # { id => '42' }
$match.callable;     # the inline handler, or an undefined Callable
$match.route;        # the matched route

recognition-status distinguishes a hit from a wrong method and from an unknown path, and allowed-methods lists the verbs a path answers:

$router.recognition-status('GET', '/about');    # 'found'
$router.recognition-status('POST', '/about');   # 'method-not-allowed'
$router.recognition-status('GET', '/missing');  # 'not-found'

$router.allowed-methods('/about');              # ('GET', 'HEAD')

route-named($name) looks a route up by its name, and route-table returns the name / verbs / pattern / target of every route, which keayl routes prints.