Download the PHP package oliwol/laravel-slugify without Composer

🌀 Laravel Slugify

Documentation | Migrating from Spatie

A lightweight package that gives your Eloquent models clean, automatic slugs — without setup, ceremony, or extra weight.

Attach a PHP attribute or use the HasSlug trait, define the source (an attribute, multiple attributes, or a method), and the package quietly handles generation, updates and uniqueness.

🚀 Installation

Requirements: PHP 8.4+, Laravel 11+

Install the package via Composer:

⚡️ Quick Start

Using the PHP Attribute (recommended)

Using method overrides

Priority: Method overrides always take precedence over the #[Slugify] attribute.

Without any trait (attribute-only)

For simpler models that don't need findBySlug, slug history, or translatable slugs — you can skip the trait entirely:

Publish the config and register your models in the models array:

The service provider then automatically generates slugs for these models on every save event. findBySlug, slug history, and translatable slugs require HasSlug — use the trait when you need those features.

🛠️ Usage

Add the trait to any Eloquent model where a slug should be automatically generated.

Configuration via #[Slugify] Attribute

The #[Slugify] attribute accepts the following parameters:

• from (required) — the source for the slug. Accepts a single attribute name (e.g. 'name'), an array of attribute names (e.g. ['first_name', 'last_name']), or a method name on the model (e.g. 'getFullTitle'). When a method name is given, it is called to produce the slug string and dirty detection is skipped (the slug is always regenerated on save).
• to (optional) — the column to save the slug to. Falls back to getRouteKeyName() if omitted.
• separator (optional) — the character used to separate words in the slug. Defaults to '-'.
• maxLength (optional) — maximum number of characters for the slug. Truncates at word boundaries. Defaults to null (no limit).
• regenerateOnUpdate (optional) — whether to regenerate the slug when the source attribute changes on update. Defaults to true. Set to false to only generate slugs on creation (useful for SEO).
• routeBinding (optional) — when true, automatically sets getRouteKeyName() to the slug column. Requires to: to be set explicitly. Defaults to false.

Route model binding: Use routeBinding: true to automatically configure getRouteKeyName() without a manual override. Requires to: to be set.

Configuration via methods

Alternatively, you can configure slug generation by overriding methods:

• — the attribute(s) used to generate the slug. Return a string or array<string>.
• — the slug column for route model binding (e.g. slug).
• Optionally — a different column to save the slug.
• Optionally — the separator character (default '-').
• Optionally — maximum slug length, truncated at word boundaries (default null).
• Optionally — return false to only generate slugs on creation (default true).
• Optionally override — scoping for uniqueness (e.g. per team).

Make sure your table contains the slug column:

If you use scoping, you probably don’t want a global unique index. Example: slugs must be unique per tenant:

⚙️ How it works

With HasSlug trait

The trait hooks into the Eloquent saving event per model class:

With attribute-only usage

The service provider registers a wildcard listener that fires on every Eloquent saving event. It skips models that already use HasSlug (to avoid double processing) and models not listed in config('slugify.models').

In both cases, the slug pipeline:

1. Resolve the source — from the #[Slugify] attribute or a getAttributeToCreateSlugFrom() override. Supports a single attribute, multiple attributes, or a model method name.
2. Generate a slug — if the source is a method, call it; otherwise combine filled attribute values (null/empty values are skipped).

3. Skip regeneration if:

   1. Using attribute source(s) and none are dirty (unchanged), or
   2. The slug has been manually set and differs from the original.

   Note: When using a method source, dirty detection is skipped — the slug is always regenerated on save, since the package cannot track the method's dependencies.

4. Ensure uniqueness by incrementing existing slugs (my-post, my-post-2, my-post-3, …).

🔎 Finding Models by Slug

The trait provides two static methods to look up models by their slug:

Both methods respect the configured slug column (to / getAttributeToSaveSlugTo()) and apply scopeSlugQuery() for scoped lookups.

📜 Slug History

When slugs change (e.g. because a title was updated), old URLs break. The optional HasSlugHistory trait keeps track of previous slugs so you can implement 301 redirects from old URLs to new ones — critical for SEO.

Setup

Publish and run the migration:

This creates a slug_history table that stores old slugs with a polymorphic relation to your models.

Usage

Add the HasSlugHistory trait alongside HasSlug:

When a slug changes, the old slug is automatically recorded in the slug_history table. Duplicate entries are prevented — if a model cycles back to a previous slug, it won't be stored again.

Finding models by current or historical slug

Use findBySlugWithHistory() to look up a model by its current slug or any previous slug:

Implementing 301 redirects

The easiest way is the slug.redirect middleware. Add it to any route that uses slug-based route model binding — it handles the redirect automatically:

The redirect status defaults to 301. Publish the config to change it:

Alternatively, handle the redirect manually in the controller:

Accessing slug history

You can access all previous slugs of a model via the slugHistory relationship:

🌍 Translatable Slugs

For multilingual applications, the optional HasTranslatableSlug trait integrates with spatie/laravel-translatable to generate one slug per locale (e.g. /en/hello-world and /de/hallo-welt).

Setup

Install spatie/laravel-translatable:

In your migration, define the source and slug columns as json:

Usage

Use HasTranslatableSlug instead of HasSlug and add spatie's HasTranslations trait:

Generating slugs per locale

When the model is saved, a slug is generated for each locale that has a value in the source attribute:

Per-locale uniqueness

Uniqueness is checked per locale using JSON-path queries. Two models can share the same English slug as long as their other locales differ — but within a single locale, suffixes are appended:

Finding models by translated slug

findBySlug() accepts an optional $locale parameter (defaults to app()->getLocale()):

Method sources

Method sources work too — the method is called once per locale with the locale context active:

Note: When using a method source with HasTranslatableSlug, the available locales are gathered from all translatable attributes on the model (excluding the slug target). For attribute sources, locales come from the source attribute itself.

Limitation: HasTranslatableSlug only supports a single attribute name or a method name as source. Array sources (e.g. from: ['first_name', 'last_name']) are not supported — use a method source instead to combine multiple translatable values.

📡 Events

The package dispatches events during the slug lifecycle, allowing you to hook in for logging, cache invalidation, or redirect management.

Available events

Events are only dispatched when the slug actually changes — if a save results in the same slug value, no event is fired.

Listening to events

Register listeners in your EventServiceProvider or use closures:

Combining with Slug History

When using both HasSlugHistory and events, the slug history is recorded automatically by the trait while events give you additional flexibility for custom logic. They work independently and can be used together or separately.

🔧 Artisan Command

The package provides an Artisan command to generate or regenerate slugs for existing database records — useful when adding the package to an existing project or after changing slug configuration.

Generate missing slugs

This processes all records where the slug column is null or empty, generates a slug from the configured source attribute(s), and saves the result. Records that already have a slug are skipped.

The command works for both HasSlug models and attribute-only models registered in config/slugify.php.

Overwrite existing slugs

Use --force to regenerate slugs for all records, including those that already have one:

Preview changes

Use --dry-run to see how many slugs would be generated without actually saving anything:

Performance

The command processes records in chunks of 200 and displays a progress bar, making it safe to use on large datasets without running into memory issues.

✅ Validation

The package provides two complementary validation rules:

Format: SlugFormat

Use SlugFormat to validate that a string is a proper slug — lowercase, alphanumeric, no leading/trailing/consecutive separators:

Uniqueness: SlugRule

Use SlugRule to validate that a slug doesn't already exist in the database — respecting the configured slug column and scoping automatically:

Both rules can be combined:

SlugRule uses the model's configured slug column (to / getAttributeToSaveSlugTo()) and applies scopeSlugQuery() automatically. Use ->ignore($model) for update scenarios and ->scope($column, $value) for additional constraints.

🧪 Testing

When using model factories, slugs are generated automatically via the saving hook on create(). For make() — which does not persist the model — no slug is generated. Use the withSlug() macro to control slug generation explicitly in tests:

The macro is registered automatically via the service provider and works with any factory for a model that uses HasSlug or has a #[Slugify] attribute.

✅ Best practices & caveats

• Ensure the route key column () is present in your table and is not the primary key (unless intentionally designed).
• If you manually set a slug, the trait will not override it. Use this to allow user-edited slugs.

🔍 Custom Scoping Example

To ensure slugs are unique per tenant, override the scopeSlugQuery() method:

This will append a WHERE tenant_id = ? clause when checking for existing slugs.

📄 License

This package is open-sourced software licensed under the MIT license.