BREAKING CHANGE The original Slugger used named parameters exclusively. It now defaults to passed arguments. The configuration array has also changed. Please read the README for information on the new configuration. To use the original version, checkout the version 1.0 tag.
Slugger is a plugin that basically rewrites cake urls (using routing) into slugged urls automatically:
'/posts/view/12'
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).
The slug is then transparently reverted back into the proper format for your controller action.
- CakePHP 2.0.x (check tags for older versions of CakePHP)
- Download this: http://github.com/jeremyharris/slugger/zipball/master
- Unzip that download.
- Copy the resulting folder to app/Plugin/Slugger/
In your app directory type:
git submodule add git://github.com/jeremyharris/slugger.git Plugin/Slugger
git submodule update --init
Ensure require is present in composer.json. This will install the plugin into Plugin/Slugger:
{
"require": {
"jeremyharris/slugger": "dev-master"
}
}
If you need the old version of slugger, make sure to replace "dev-master" with "1.0".
App::uses('SluggableRoute', 'Slugger.Routing/Route');
Router::connect(/posts/:action/:Post,
array(),
array(
'routeClass' => 'Slugger.SluggableRoute',
'models' => array('Post')
)
);
This is the minimal default configuration. We're using the SluggableRoute class
for this route, and checking for the Post model to generate slugs. The :Post
key is our passed key ($id in the action).
Router::connect(/posts/:action/:Post,
array(),
array(
'routeClass' => 'Slugger.SluggableRoute',
'models' => array(
'<MODEL_NAME>' => array(
'slugField' => '<FIELD_TO_SLUG>',
'param' => '<SLUG_PARAM>'
)
),
'slugFunction' => '<SLUG_FUNCTION>'
)
);
<MODEL_NAME>Required At least one model name is required. These models will be searched when pulling and generating the slug.<FIELD_TO_SLUG>By default, Slugger slugs the$displayFieldset on the model. If you wish to use a different field as the slug, define it here.<SLUG_PARAM>By default,:<MODEL_NAME>is taken from the route and replaced with a slug. If it is undefined, it assumes the first passed arg. You can also configure it to use named parameters.<SLUG_FUNCTION>A callable. By default, usesInflector::slug.
The slug parameter is what Slugger pulls from the routed URL and replaces with
your slug. By default, it checks for the :<MODEL_NAME> passed key.
:Post Slugs the :Post route element:
/post/view/5 --> /post/view/my-post-title
Post Slugs the Post named param:
/post/view/Post:5 --> /post/view/my-post-title
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/:action/*',
array(),
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.
Create links using Cake's helpers and Router to take advantage of automatically generated slugs:
array(
'controller' => 'posts',
'action' => 'view',
12
)
turns into a url string like /posts/view/my-post-title, then back into the
proper request for your controller to handle by putting 12 back into the passed
arguments. In your controller, get the post id by checking:
function view($id = null) {
$post = $this->Post->read(null, $id);
// do controller stuff
}
If you have defined a custom <SLUG_PARAM>, Slugger will replace whatever
parameter type you chose and put the original route array back together.
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
App::uses('SlugCache', 'Slugger.Cache');
$this->User->id = 3;
$this->User->saveField('username', 'newUsername');
// invalidate user slugs
SlugCache::invalidate('User');
To invalidate a single user you must regenerate the slug yourself and save it in the cache:
$this->User->id = 3;
$newSlug = 'my-new-slug';
$userSlugs = SlugCache::get('User');
$userSlugs[$this->User->id] = $newSlug;
SlugCache::set('User', $userSlugs);
Slugger uses the 'Slugger' cache config to cache, so customize that configuration to change caching engines.
Router::connect(/posts/:action/*,
array(),
array(
'routeClass' => 'Slugger.SluggableRoute',
'models' => array('Post')
)
);
Using the above route
array(
'controller' => 'posts',
'action' => 'view',
12
)
Becomes the /posts/view/sluggable-is-cool, and is accessed in the
controller as so:
function view($id) {
$post = $this->Post->read(null, $id);
// do controller stuff
}
Router::connect(/posts/:action/:post_id/*,
array(),
array(
'pass' => array('post_id'),
'routeClass' => 'Slugger.SluggableRoute',
'models' => array(
'Post' => array(
'param' => ':post_id'
)
)
)
);
Using the above route
array(
'controller' => 'posts',
'action' => 'view',
'anotherArg',
'post_id' => 12
)
Becomes the /posts/view/anotherArg/sluggable-is-cool, and is accessed in the
controller as so:
function view($id, $anotherArgWillBeHere) {
$post = $this->Post->read(null, $id);
// do controller stuff
}
A couple of things to note if using keyed passed args in your routes.
- You cannot use regex to validate route elements using this method because routes are parsed before Slugger rewrites them, and they would fail due to the url string not matching an expected integer regex
- Missing slugs (i.e.,
/posts/missing-titlewheremissing-titleisn't found as a slug) will still add the:keyparameter to the route params because regex validation cannot be done
Router::connect(/posts/:action/*,
array(),
array(
'routeClass' => 'Slugger.SluggableRoute',
'models' => array(
'Post' => array(
'slugField' => 'post_title',
'param' => 'Post'
),
'Author' => array(
'param' => 'Author'
)
)
)
);
Using the above route
array(
'controller' => 'posts',
'action' => 'view',
'Post' => 12,
'Author' => 1
)
Becomes the /posts/view/jeremy/sluggable-is-cool, and is accessed in the
controller as so:
function view() {
$post = $this->Post->read(null, $this->request->params['named']['Post']);
$author = $this->Post->Author->read(null, $this->request->params['named']['Author']);
// do controller stuff
}
- More than one model can be passed via the
modelsparam 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 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
- 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' => trueto the route options and the id will always be prepended to the slug
Licensed under The MIT License http://www.opensource.org/licenses/mit-license.php Redistributions of files must retain the above copyright notice.