CakePHP Named Routes
CakePHP although it allows for custom routes to change the URL in the users address bar, there wasn’t a suitable solution for developers to have “aliases” for the routes. Inspired by Ruby on Rails’ named routes CakePHP Named Routes was created.
So Seriously, what is it?
It allows for developers to give an alias to their controllers and actions in a simply and intuitive kind of way. For example, previously if we wanted to link to a the users controller and edit action, we would have to write
<?= $html->link('Edit User', array('controller' => 'users', 'action' => 'edit', 5)) ?>
With some simply setup of NamedRoute
<?= $html->link('Edit User', url('edit_user_path(5)')); ?>
The nice thing about this is edit_user_path refers back to a controller and action defined once elsewhere. If you’ve ever had to change the url, or move an action into another controller you’ll understand the headaches that it can cause.
Doesn’t routes.php do this sort of thing?
The routes.php file allows you to alias the address in the users browser, but we the lowly developers still have to type long verbose lines of code to reference the controller, actions.
NamedRoute works along side (actually referencing the routes.php file) to bring the seperation that routes.php brings to the browser, to the developer.
Ok, but how do I use it?
Well quiet simply really.
First download and move
named_route.php into your
You’ll need to include in your bootstrap
config('named_route'); to ensure the config file gets loaded.
Next in your bootstrap (or wherever you want to) start setting things up.
Setting up your named routes
NamedRoute offers a helper function called
set to define controller actions, and map them to named routes.
There are two ways to do this..
Firstly, if you stick to the standard bake actions (index, edit, delete, view, new) then you can simply do a
NamedRoute::set(array('users' => array('controller' => 'users') ));
This will give you the following routes
You’re most likely asking why “path” has to be appended to each NamedRoute, well its because its interchangeable with “url” to append the host to the start
so for the last example, the output will be as follows
If your bucking the trend and giving your controller different action names then you have to write a little bit more code,
lets say for instance that we have “login” and “logout” actions that belong to the “users” controller, your namedroute will look like this
We would then have a the following routes
What about if I have custom routes set up in my routes.php file?
We take care of that, by referencing the controller/action to the routes.php file and finding the correct url.
So for example,
Router::connect('/login', array('controller' => 'users', 'action' => 'login'));
bootstrap (namedroutes set)
'login' => array('controller' => 'users', 'action' => 'login')
We would end up with
How to use named routes in your views or controllers? (or anywhere)
Its ever so simply! All you need to do is use the “url” alias function to retrieve the url for the named route.
Based on the above examples, if we wanted to get the login_path we would simple write
If we wanted the url
If we wanted to edit user whose id = 1
If you wanted to get to the index (list all users)
- Note that the index is plural (users), not (user)
If you wanted to do go to the admin users index (note the . seperation between the prefix and named route)
which will return
You can replace admin with anything else, i.e.
url('sales.users_path') just as long as you have the prefix set up in your routes.php file.
So sum it up for me
Ok well, to put it simply, in your
route.php file, add what you want the user to see
In your NamedRoute setup, add what you want to write.
Debugging and relevant output
There are methods which will assist in debugging / building your named routes.
The first is
NamedRoute::debug() which will output the NamedRoute object. This is usefull if you want to see how the routes are stored
The second is
NamedRoute::routes() which will output a HTML table, showing all of the named routes, the corresponding url from the routes.php file, and the controller and action associated
An example output of
|Route||_ Url||_ Controller||_ Action|
So why did you write this?
I moved a few actions from one controller to the next, and links were scattered everywhere through out the site. Coming from Rails, I knew how namedRoutes would of made sure I didn’t have this problem, so I set out to recreate the functionality.
Bugs/Feautres we should know about?
None that I know of, but I’m sure you guys and girls out there will let me know when you find something.