amdadulhaq/unique-slug-laravel

Unique slug generator for Laravel

v2.0.1 2026-01-02 19:38 UTC

Requires

• php: ^8.2|^8.3|^8.4|^8.5
• illuminate/contracts: ^10.0|^11.0|^12.0

Requires (Dev)

• driftingly/rector-laravel: ^1.0|^2.0
• larastan/larastan: ^2.0|^3.0
• laravel/pint: ^1.26
• orchestra/testbench: ^8.0|^9.0|^10.0
• pestphp/pest: ^2.0|^3.0|^4.0
• pestphp/pest-plugin-laravel: ^2.0|^3.0|^4.0

MIT

• Amdadul Haq

• laravel
• Amdadul Haq
• unique-slug-laravel

README

A powerful and flexible unique slug generator package for Laravel with advanced features.

Installation

You can install the package via composer:

composer require amdadulhaq/unique-slug-laravel

Publish the configuration file:

php artisan vendor:publish --tag=unique-slug-config

Usage

Basic Usage

namespace App\Models;

use AmdadulHaq\UniqueSlug\HasSlug;
use Illuminate\Database\Eloquent\Model;

class Article extends Model
{
    use HasSlug;

    protected $fillable = ['name', 'slug'];
}

Article::create(['name' => 'Hello World']);
// Generates slug: hello-world

Article::create(['name' => 'Hello World']);
// Generates slug: hello-world-1

Configuration Options

Custom Source and Slug Fields

class Article extends Model
{
    use HasSlug;

    public function getSlugSourceAttribute(): string
    {
        return 'title'; // Generate slug from title field
    }

    public function getSlugNameAttribute(): string
    {
        return 'slug'; // Store slug in slug field
    }

    public function getSlugSeparator(): string
    {
        return '_'; // Use underscore separator
    }
}

Using Configuration File

// config/slug.php
return [
    'update_on_update' => env('SLUG_UPDATE_ON_UPDATE', false),
    'case' => env('SLUG_CASE', 'lower'),
    'max_length' => env('SLUG_MAX_LENGTH', 255),
    'reserved_slugs' => ['admin', 'dashboard', 'api'],
    'suffix_separator' => env('SLUG_SUFFIX_SEPARATOR', '-'),
    'skip_on_empty' => env('SLUG_SKIP_ON_EMPTY', false),
    'include_soft_deleted' => env('SLUG_INCLUDE_SOFT_DELETED', false),
];

Advanced Features

Custom Slug Generation

class Article extends Model
{
    use HasSlug;

    protected function generateCustomSlug(string $source): string
    {
        return 'article-'.strtolower($source);
    }
}

Conditional Slug Generation

class Article extends Model
{
    use HasSlug;

    public function shouldSkipSlug(): bool
    {
        return $this->published === false;
    }
}

Case Transformation

Available cases: lower, upper, title, camel, snake

config(['slug.case' => 'upper']);
Article::create(['name' => 'Hello World']);
// Generates slug: HELLO-WORLD

Maximum Length

config(['slug.max_length' => 50]);
Article::create(['name' => 'Very Long Title That Should Be Truncated']);
// Truncates slug to 50 characters

Reserved Slugs

config(['slug.reserved_slugs' => ['admin', 'dashboard']]);
Article::create(['name' => 'admin']);
// Generates slug: admin-1

Query Scopes

Article::whereSlug('hello-world')->first();
Article::orWhereSlug('another-slug')->get();
Article::whereSlugLike('hello')->get();

Soft Delete Support

class Article extends Model
{
    use HasSlug;
    use \Illuminate\Database\Eloquent\SoftDeletes;
}

// Include soft deleted records in uniqueness check
config(['slug.include_soft_deleted' => true]);

Environment Variables

SLUG_UPDATE_ON_UPDATE=false
SLUG_CASE=lower
SLUG_MAX_LENGTH=255
SLUG_RESERVED_SLUGS=admin,dashboard,api
SLUG_SUFFIX_SEPARATOR=-
SLUG_SKIP_ON_EMPTY=false
SLUG_INCLUDE_SOFT_DELETED=false

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Amdadul Haq
• All Contributors

License

The MIT License (MIT). Please see License File for more information.