PHP
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src Doc block fix May 16, 2018
tests phpcs fix May 15, 2018
.gitattributes Add .gitattributes Apr 26, 2015
.gitignore initial commit Apr 16, 2015
.travis.yml Test with lowest dep. versions. May 17, 2018
LICENSE Update license Apr 16, 2015
README.md Update README.md Nov 28, 2017
composer.json Update to Cake 3.5. Apr 15, 2018
phpunit.xml.dist Update travis config Jan 10, 2016

README.md

Slug

Build Status Coverage Total Downloads License

Slugging for CakePHP 3.x

Requirements

  • CakePHP 3.2.7+ (for lower CakePHP versions use plugin version 1.0.*)

Installation

Using Composer:

composer require muffin/slug

or if your CakePHP is less than 3.2.7 use

composer require muffin/slug:1.0.*

To make your application load the plugin either run:

./bin/cake plugin load Muffin/Slug

or add the following line to config/bootstrap.php:

Plugin::load('Muffin/Slug');

Usage

To enable slugging add the behavior to your table classes in the initialize() method.

public function initialize(array $config)
{
    //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',
    '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. A pre-commit hook has been included to automatically run the code sniffs for you:

ln -s ../../contrib/pre-commit .git/hooks/.

Bugs & Feedback

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

License

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