Slugging for CakePHP
Using Composer:
composer require muffin/slug
Load the plugin using the CLI command:
./bin/cake plugin load Muffin/Slug
To enable slugging add the behavior to your table classes in the
initialize()
method.
public function initialize(array $config): void
{
//etc
$this->addBehavior('Muffin/Slug.Slug', [
// Optionally define your custom options here (see Configuration)
]);
}
Please note that Slug expects a database column named
slug
to function. If you prefer to use another column make sure to specify thefield
configuration option.
If you want to find a record using its slug, a custom finder is provided by the plugin.
// src/Controller/ExamplesController.php
$example = $this->Examples->find('slugged', slug: $slug);
Slug comes with the following configuration options:
field
: name of the field (column) to hold the slug. Defaults toslug
.displayField
: name of the field(s) to build the slug from. Defaults to the\Cake\ORM\Table::displayField()
.separator
: defaults to-
.replacements
: hash of characters (or strings) to custom replace before generating the slug.maxLength
: maximum length of a slug. Defaults to the field's limit as defined in the schema (when possible). Otherwise, no limit.slugger
: class that implements theMuffin\Slug\SlugInterface
. Defaults toMuffin\Slug\Slugger\CakeSlugger
.unique:
: tells if slugs should be unique. Set this to a callable if you want to customize how unique slugs are generated. Defaults totrue
.scope
: extra conditions used when checking a slug for uniqueness.implementedEvents
: events this behavior listens to. Defaults to['Model.buildValidator' => 'buildValidator', 'Model.beforeSave' => 'beforeSave']
. By default the behavior adds validation for thedisplayField
fields to make them required on record creating. If you don't want these auto added validations you can setimplementedEvents
to just['Model.beforeSave' => 'beforeSave']
.onUpdate
: Boolean indicating whether slug should be updated when updating record, defaults tofalse
.onDirty
: Boolean indicating whether slug should be updated when slug field is dirty (has a preset value custom value), defaults tofalse
.
The plugin contains two sluggers:
The CakeSlugger
uses \Cake\Utility\Text::slug()
to generate slugs. In the
behavior config you can set the slugger
key as shown below to pass options to
the $options
arguments of Text::slug()
.
'slugger' => [
'className' => \Muffin\Slug\Slugger\CakeSlugger::class,
'transliteratorId' => '<A valid ICU Transliterator ID here>'
]
The ConcurSlugger
uses concur/slugify to generate slugs.
You can use config array similar to the one shown above to pass options to
Cocur\Slugify\Slugify
's constructor.
- Fork
- Mod, fix
- Test - this is important, so it's not unintentionally broken
- Commit - do not mess with license, todo, version, etc. (if you do change any, bump them into commits of their own that I can ignore when I pull)
- Pull request - bonus point for topic branches
To ensure your PRs are considered for upstream, you MUST follow the CakePHP coding standards.
https://github.com/usemuffin/slug/issues
Copyright (c) 2015-Present, Use Muffin and licensed under The MIT License.