eberfreitas/cakephp-slugomatic

CakePHP behavior to automatically create slugs for your URLs from database records

Slugomatic Plugin

, _(*1)

Slugomatic is a CakePHP plugin that automatically generate slugs based on your database fields. That way you can easily generate user and SEO friendly URLs for your resources. You can read more about Semantic URLs on Wikipedia., _(*2)

Example, _(*3)

If you have a record on your database with the title "How to grow a beard", the plugin will generate a slug like "how-to-grow-a-beard". That way you can create links like this:, _(*4)

http://example.com/post/1234/how-to-grow-a-beard, _(*5)

Requirements

• CakePHP 2.x (tested on 2.4 and 2.5 but should work on every 2.x release)
• PHP 5.3 or later (should work on 5.2 but it is not tested)

Installation

Using Composer, _(*6)

Add the plugin to your project's composer.json - something like this:, _(*7)

{
    "require": {
        "eberfreitas/cakephp-slugomatic": "dev-master"
    }
}

Because this plugin has the type cakephp-plugin set in it's own composer.json, composer knows to install it inside your /Plugins directory, rather than in the usual vendors file. It is recommended that you add /Plugins/Slugomatic to your .gitignore file. Why? read this., _(*8)

Manual, _(*9)

• Download this: http://github.com/eberfreitas/cakephp-slugomatic/zipball/master
• Unzip that download
• Copy the resulting folder to app/Plugins
• Rename the folder you just copied to Slugomatic

GIT Submodule, _(*10)

In your app directory type:, _(*11)

git submodule add git://github.com/eberfreitas/cakephp-slugomatic.git plugins/Slugomatic
git submodule init
git submodule update

GIT Clone, _(*12)

In your plugin directory type:, _(*13)

git clone git://github.com/eberfreitas/cakephp-slugomatic.git Slugomatic

Usage

First of all you need to enable the plugin on your application. On your app/Config/bootstrap.php add the following line:, _(*14)

CakePlugin::load('Slugomatic');

You can read more about enabling plugins and the different ways of doing it on Cake's Book., _(*15)

After that, go to the model where you want to use the plugin and attach the behavior like this:, _(*16)

public $actsAs = array(
    'Slugomatic.Slugomatic'
);

The plugin will assume that your have a field called title. The slug will be created using the data from that field. If you have a different field name, just configure the behavior like this:, _(*17)

public $actsAs = array(
    'Slugomatic.Slugomatic' => array(
        'fields' => 'name'
    )
);

The plugin will also assume that you have a slug field where the generated slug will be stored. Take a look at the options below if you need to change that., _(*18)

If by any means you have two records with the same title, Slugomatic will identify those records and generate indexed slugs avoiding duplication, like this:, _(*19)

• how-to-grow-a-beard
• how-to-grow-a-beard-1
• how-to-grow-a-beard-2
• how-to-grow-a-beard-x

Options

When configuring the behavior, you have the following options:, _(*20)

public $actsAs = array(
    'Slugomatic.Slugomatic' => array(
        'fields' => 'title',
        'scope' => false,
        'conditions' => false,
        'slugfield' => 'slug',
        'separator' => '-',
        'overwrite' => false,
        'length' => 256,
        'lower' => true
    )
);

• fields: Specify the source fields for the slug. Defaults to title. If you need, you can specify more than one field like this:, _(*21)

  array('title', 'product_code');
  

  That way, if you have a record with the title "Strawberry Cake" and a product_code like "CK 073", the slug will be something like "strawberry-cake-ck-073"., _(*22)

• slugfield: The field on your database that will store the generated slug. Defaults to slug.
• overwrite: Only applied when updating a record. If overwrite is true, then when you update the record with a different value, the slug will also be updated/overwrited. Defaults to false. Important! Ideally, this value should always be false. You don't want to break links everywhere with a modified slug from a previously defined resource, so use this with caution.
• length: Defines the length of the slug. Defaults to 256.
• lower: When true, transforms the slug text to lowercase. If false, the behavior will preserve the text the way it was defined.
• separator: The character used to separate words. Defaults to '-'.

Additional options for deduplication

Like stated before, Slugomatic will identify duplicated slugs and generate a properly indexed new slug to avoid that. The plugin also provides two different options that enables you to control the way it identifies duplicated slugs:, _(*23)

• conditions: In this option you can define conditions to the query that will identify duplicates just like you define conditions to your regular queries. Example:, _(*24)

  array(
    'conditions' => array('product_type' => 'box')
  );
  

  That way, Slugomatic will only find duplicates if product_type is box., _(*25)

• scope: This option is very similar to conditions but it uses dynamic values. The value will always be the one present on the data being saved. That way you just need to define the field being used for the condition, like this:, _(*26)

  array(
    'scope' => array('deleted')
  );
  

  So, if you are saving a record with the following data:, _(*27)

  $data = array(
    'title' => 'How to grow a beard',
    'text' => 'Lorem ipsum...',
    'deleted' => 0
  )
  

  Slugomatic will only look for duplicates where the field deleted is also 0., _(*28)

Credits & thanks

This plugin is heavily based on Mariano's SluggableBehavior from the Syrup package. A big thanks to Friends of Cake for providing the awesome boilerplate for travis-ci integration. And finally, thanks to Jose Diaz-Gonzalez and his CakeAdvent series which helped me to create this plugin properly., _(*29)