Slugger
Slugger is a plugin that basically rewrites cake urls (using routing) into slugged urls automatically using normal passed arguments
'/posts/view/1'
automatically becomes
'/posts/view/my-post-title'
This avoids the need to store a slug in the db, manage it, check for duplicates,
etc. It also avoids the Model::findBySlug()
solution that many people use.
Search for your post using the primary key instead! (Initial development sparked
by Mark Story's blog).
Requirements
- CakePHP 2.x (check tags for older versions of CakePHP)
Usage
App::uses('SluggableRoute', 'Slugger.Routing/Route');
Router::connect(/posts/:Post,
array('controller' => 'posts', 'action' => 'view'),
array(
'routeClass' => 'SluggableRoute',
'models' => array('Post')
)
);
As you can see, you need to match the special regex params :Model
with the
models
key in the third argument. You can use as many models as you like. You don't
need to change the usual urls produced by a cake bake, for example:
array(
'controller' => 'posts',
'action' => 'view',
12
)
turns into a url string like /posts/my-post-title
, then back into the
proper request for your controller to handle by putting 12
back
into the the passed arguments. In your controller, get the post id by checking
passedArgs
.
function view($id) {
$post = $this->Post->read(null, $id);
// do controller stuff
}
By default, the field used for the slug is the model's displayField
. To change
this, change your connection to:
Router::connect('/posts/:Post',
array('controller' => 'posts', 'action' => 'view'),
array(
'routeClass' => 'SluggableRoute',
'models' => array('Post' => 'different_field')
)
);
Custom slug function
You can define a custom function to use when slugging your urls by setting the 'slugFunction' key in the route options. This key accepts a php callback and passes one argument, the string to slug. It expects a string to be returned.
For example, to use a custom function:
function my_custom_iconv_slugger($str) {
$str = preg_replace('/[^a-z0-9 ]/i', '', iconv('UTF-8', 'ASCII//TRANSLIT//IGNORE', $str));
$quotedReplacement = preg_quote($replacement, '/');
$merge = array(
'/[^\s\p{Ll}\p{Lm}\p{Lo}\p{Lt}\p{Lu}\p{Nd}]/mu' => ' ',
'/\\s+/' => $replacement,
sprintf('/^[%s]+|[%s]+$/', $quotedReplacement, $quotedReplacement) => '',
);
return strtolower(preg_replace(array_keys($merge), array_values($merge), $str));
}
Router::connect('/posts/:Post',
array('controller' => 'posts', 'action' => 'view'),
array(
'routeClass' => 'SluggableRoute',
'models' => array('Post'),
'slugFunction' => 'my_custom_iconv_slugger'
)
);
iconv is a PHP module that encodes strings in a different character set, thereby stripping invalid characters. It's much faster but depends on your system's setup.
Note: This functionality replaces the briefly available 'iconv' option. Use the iconv example above instead.
Caching
Slugger caches by default. When you update records that the Sluggable route uses, you'll need to remove the cache. For example, updating a User's username
$this->User->id = 3;
$this->User->saveField('username', 'newUsername');
SluggableRoute::invalidateCache('User', $this->User->id);
Invalidating after saves and deletions is a good idea. You can also remove all of the cache for an entire model like so:
SluggableRoute::invalidateCache('User');
Notes and Features
- More than one model can be passed via the
models
param in the route options. - If a model has (what will become) duplicate slugs, sluggable route will automatically prepend the id to the slug so it doesn't conflict
- If no slug is found, it will fall back to the original
12
url so you don't have to change anything in your database - Don't think of this as permalinks! These are just to make your url's a little prettier
Limitations
- Hasn't been tested with large amounts of data (use at your own risk to
preformance!), but it is cached so hits on the db should be minimal. The cache
config is
Slugger.short
if you need to clear it. The biggest bottleneck, if any, would be in writing a ton of urls on the same page. I'm testing ways to improve this. - Can conflict with multiple models with the same slug. A solution would be not to slug more than one model per route
- If someone was to bookmark a slugged url and after the fact you added a post
with the same name, the bookmarked url would no longer work because the id
would be prepended to it. In order to avoid this from ever happening, pass
'prependPk' => true
to the route options and the id will always be prepended to the slug
License
Licensed under The MIT License http://www.opensource.org/licenses/mit-license.php Redistributions of files must retain the above copyright notice.
Authors
- Pierre Martin (real34) - Cache invalidation
- Jose Lorenzo Rodriguez (lorenzo) - Got rid of named parameters