model-slugs.md

Model Slugs

• Usage
  • Generate Slug
• Customizations
  • Allow Duplicate Slugs
  • Change Separator
  • Disable Slugs On Create
  • Disable Slugs On Update

This functionality allows you to generate slugs for your model records based on other fields.

Usage

Your models should use the Varbox\Traits\HasSlug trait and the Varbox\Options\SlugOptions class. The trait contains an abstract method getSlugOptions() that you must implement yourself.

Here's an example of how to implement the trait:

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Varbox\Options\SlugOptions;
use Varbox\Traits\HasSlug;

class YourModel extends Model
{
    use HasSlug;

    /**
     * The` attributes that are mass assignable.
     *
     * @var array
     */
    protected $fillable = [
        'name',
        'slug',
    ];

    /**
     * Get the options for the HasSlug trait.
     *
     * @return SlugOptions
     */
    public function getSlugOptions(): SlugOptions
    {
        return SlugOptions::instance()
            ->generateSlugFrom('name')
            ->saveSlugTo('slug');
    }
}

Next you should create the table column that you've specified for the saveSlugTo() method.

Schema::table('your_table', function (Blueprint $table) {
    $table->string('slug')->nullable()->unique();
});

Generate Slug

After you've done the above steps, generating a slug for a model record will be done automatically when you'll be saving that model record.

$model = YourModel::create([
    'name' => 'Initial name'
]); // slug is "initial-name"

$model->update([
    'name' => 'Modified name'
]); // slug is "modified-name"

Customizations

The slug functionality offers a variety of customizations to fit your needs.

Allow Duplicate Slugs

By default the generated slugs for a model are unique by appending {slug-separator}{increment} at the end of the already existing value.

You can allow duplicate slug values for your model records by using the allowDuplicateSlugs() method in your definition of the getSlugOptions() method.

/**
 * Get the options for the HasSlug trait.
 *
 * @return SlugOptions
 */
public function getSlugOptions(): SlugOptions
{
    return SlugOptions::instance()
        ->allowDuplicateSlugs();
}

Change Separator

By default the slug is generated by concatenating the words using a dash -

You can change the slug separator by using the usingSeparator() method in your definition of the getSlugOptions() method.

/**
 * Get the options for the HasSlug trait.
 *
 * @return SlugOptions
 */
public function getSlugOptions(): SlugOptions
{
    return SlugOptions::instance()
        ->usingSeparator('_');
}

Disable Slugs On Create

By default, when creating a model record, a slug will be automatically generated for it based on the attribute value from your generateSlugFrom() method.

You can disable this using the doNotGenerateSlugOnCreate() method in your definition of the getSlugOptions() method.

/**
 * Get the options for the HasSlug trait.
 *
 * @return SlugOptions
 */
public function getSlugOptions(): SlugOptions
{
    return SlugOptions::instance()
        ->doNotGenerateSlugOnCreate();
}

Disable Slugs On Update

By default, when updating a model record, the slug will be automatically updated based on the attribute value from your generateSlugFrom() method.

You can disable this using the doNotGenerateSlugOnUpdate() method in your definition of the getSlugOptions() method.

/**
 * Get the options for the HasSlug trait.
 *
 * @return SlugOptions
 */
public function getSlugOptions(): SlugOptions
{
    return SlugOptions::instance()
        ->doNotGenerateSlugOnUpdate();
}