Routing

A route is a rule that connects a page address to a controller method. All routes of a project are described in one file, config/routes.php. A new project already has it, so there is nothing to create.

A simple route

// config/routes.php
use Cake\Routing\RouteBuilder;
 
return function (RouteBuilder $routes): void {
    $routes->scope('/', function (RouteBuilder $builder): void {
        $builder->connect('/hi', ['controller' => 'Hello', 'action' => 'index']);
 
        $builder->fallbacks();
    });
};

connect() takes an address and an array with the controller and method names. Now the page from the first lesson also opens at /hi: this address calls the index() method of HelloController.

Default routes

The fallbacks() line enables the general rule "controller/method/arguments":

This is why the /hello page from the first lesson worked without a route. Your own routes are written only when a different address is needed.

Parameters

A part of the address in curly braces is a parameter:

$builder->connect('/articles/{id}', ['controller' => 'Articles', 'action' => 'view'])
    ->setPass(['id'])
    ->setPatterns(['id' => '\d+']);

setPass() passes the parameter to the argument of the view($id) method. setPatterns() restricts it with a regular expression: /articles/5 matches and /articles/abc does not.

Route name

$builder->connect(
    '/articles/{id}',
    ['controller' => 'Articles', 'action' => 'view'],
    ['_name' => 'articles:view', 'pass' => ['id'], 'id' => '\d+'],
);

The third argument holds route options; the _name key sets a name that can be used to refer to the route.

Groups of addresses

scope() sets a common beginning of the address for several routes:

$routes->scope('/blog', function (RouteBuilder $builder): void {
    $builder->connect('/', ['controller' => 'Articles', 'action' => 'index']);
    $builder->connect('/new', ['controller' => 'Articles', 'action' => 'add']);
});

The result is the addresses /blog and /blog/new.

Building links

An address is not written as a string; it is built from the same data as the route:

use Cake\Routing\Router;
 
$url = Router::url(['controller' => 'Articles', 'action' => 'view', 5]);
$url = Router::url(['_name' => 'articles:view', 'id' => 5]);

Both lines return /articles/5. If the address in the route changes, the links change with it. In templates the Html helper does the same; see the lesson about layouts.

Checking

bin/cake routes

The command prints a table of all routes: name, address, controller and method.

Common mistake

CakePHP checks routes from top to bottom and takes the first match. If fallbacks() or a route with a parameter stands above a specific address, the lower one is never reached. Put specific addresses at the top and fallbacks() on the last line.