Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/UseMuffin/Slug
Slugging for CakePHP
https://github.com/UseMuffin/Slug
cakephp cakephp-plugin php slug
Last synced: 3 months ago
JSON representation
Slugging for CakePHP
- Host: GitHub
- URL: https://github.com/UseMuffin/Slug
- Owner: UseMuffin
- License: mit
- Created: 2015-04-15T21:10:58.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2023-09-27T03:48:58.000Z (9 months ago)
- Last Synced: 2024-03-24T02:03:17.044Z (3 months ago)
- Topics: cakephp, cakephp-plugin, php, slug
- Language: PHP
- Homepage:
- Size: 142 KB
- Stars: 35
- Watchers: 5
- Forks: 16
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Lists
- awesome-cakephp - Muffin/Slug plugin - A plugin for generating slugs and finding records by slug. Uses a pluggable architecture which allows using your own slug generator class. (SEO)
README
# Slug
[](https://github.com/UseMuffin/Slug/actions)
[](https://codecov.io/github/UseMuffin/Slug)
[](https://packagist.org/packages/muffin/slug)
[](LICENSE)
Slugging for CakePHP
## Installation
Using [Composer][composer]:
```bash
composer require muffin/slug
```
Load the plugin using the CLI command:
```bash
./bin/cake plugin load Muffin/Slug
```
## Usage
To enable slugging add the behavior to your table classes in the
`initialize()` method.
```php
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.
```php
// 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()`.
```php
'slugger' => [
'className' => \Muffin\Slug\Slugger\CakeSlugger::class,
'transliteratorId' => ''
]
```
### ConcurSlugger
The `ConcurSlugger` uses [concur/slugify](https://github.com/cocur/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][muffin] and licensed under [The MIT License][mit].
[cakephp]:http://cakephp.org
[composer]:http://getcomposer.org
[mit]:http://www.opensource.org/licenses/mit-license.php
[muffin]:http://usemuffin.com