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 app/config directory.
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

Route	Controller	Action	Resulting_url
users_path	users	index	/users/
edit_user_path(3)	users	edit	/users/edit/3
new_user_path	users	new	/users/new
delete_user_path(1)	users	delete	/users/delete/1
view_user_path(1)	users	view	/users/view/1

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

Route	Controller	Action	Resulting_url
users_url	users	index	http://domain.com/users/
edit_user_url(3)	users	edit	http://domain.com/users/edit/3
new_user_url	users	new	http://domain.com/users/new
delete_user_url(1)	users	delete	http://domain.com/users/delete/3
view_user_url(1)	users	view	http://domain.com/users/view/1

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

NamedRoute::set(array( ‘login’ => array(‘controller’ => ‘users’, ‘action’ => ‘login’), ‘logout’ => array(‘controller’ => ‘users’, ‘action’ => ‘logout’) ));

We would then have a the following routes

Route	Controller	Action	Resulting_url
login_path	users	login	/users/login
logout_path	users	logout	/users/logout

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,

routes.php

Router::connect('/login', array('controller' => 'users', 'action' => 'login'));

bootstrap (namedroutes set)
NamedRoute::set(array(
'login' => array('controller' => 'users', 'action' => 'login')
));

We would end up with

Route	Controller	Action	Resulting_url
login_path	users	login	/login

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.
For example,

Based on the above examples, if we wanted to get the login_path we would simple write
url('login_path')

If we wanted the url
url('login_url')

If we wanted to edit user whose id = 1
url('edit_user_path(1)')

If you wanted to get to the index (list all users)

• Note that the index is plural (users), not (user)

url('users_path')

If you wanted to do go to the admin users index (note the . seperation between the prefix and named route)
url('admin.users_path')
which will return /admin/users/

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 NamedRoute::routes()

Route	_ Url	_ Controller	_ Action
root	/home_page/	home_page	index
login	/users/login/	users login
logout	/users/logout/	users	logout
users	/users/	users	index
homes	/homes/	homes	index
view_user	/users/view/	users	view
add_user	/users/add/	users	add
edit_user	/users/edit/	users	edit
delete_user	/users/delete/	users	delete
view_home	/homes/view/	homes	view
add_home	/homes/add/	homes	add
edit_home	/homes/edit/	homes	edit
delete_home	/homes/delete/	homes	delete

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.