Skip to content
master
Go to file
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
src
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Slug

Build Status Coverage Total Downloads License

Slugging for CakePHP

Installation

Using Composer:

composer require muffin/slug

Load the plugin using the CLI command:

./bin/cake plugin load Muffin/Slug

Usage

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 the field configuration option.

Searching

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]);

Configuration

Slug comes with the following configuration options:

  • field: name of the field (column) to hold the slug. Defaults to slug.
  • 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 the Muffin\Slug\SlugInterface. Defaults to Muffin\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 to true.
  • 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 the displayField fields to make them required on record creating. If you don't want these auto added validations you can set implementedEvents to just ['Model.beforeSave' => 'beforeSave'].
  • onUpdate: Boolean indicating whether slug should be updated when updating record, defaults to false.
  • onDirty: Boolean indicating whether slug should be updated when slug field is dirty (has a preset value custom value), defaults to false.

Sluggers

The plugin contains two sluggers:

CakeSlugger

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>'
]

ConcurSlugger

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.

Patches & Features

  • 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.

Bugs & Feedback

http://github.com/usemuffin/slug/issues

License

Copyright (c) 2015-Present, Use Muffin and licensed under The MIT License.

You can’t perform that action at this time.