Laravel Sluggable

https://github.com/spatie/laravel-sluggable
Admin
Laravel Sluggable is a package that automatically generates unique URL-friendly slugs from Eloquent...
Tokens:62,342
Snippets:476
Trust Score:10
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example: create() with generateSlugsFrom and saveSlugsTo

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/slug-options.md

Example usage of SlugOptions::create() with generateSlugsFrom and saveSlugsTo.

```php
use Spatie\Sluggable\SlugOptions;

public function getSlugOptions(): SlugOptions
{
    return SlugOptions::create()
        ->generateSlugsFrom('title')
        ->saveSlugsTo('slug');
}
```

--------------------------------

### slugifySource usage example

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/generate-slug-action.md

Example showing how to call slugifySource with a SlugOptions instance. Outputs 'hello-world'.

```php
$action = app(GenerateSlugAction::class);
$action->slugifySource('Hello, World!', SlugOptions::create()->generateSlugsFrom('title')->saveSlugsTo('slug'));
// "hello-world"
```

--------------------------------

### Example: createWithLocales() with closure

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/slug-options.md

Example usage of createWithLocales() with a closure for generateSlugsFrom.

```php
SlugOptions::createWithLocales(['en', 'nl'])
    ->generateSlugsFrom(fn (Article $article, string $locale) => "{$locale} {$article->id}")
    ->saveSlugsTo('slug');
```

--------------------------------

### Start slug suffix counter at a different number with startSlugSuffixFrom()

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/advanced-usage/uniqueness.md

Sets the first numeric suffix used on a collision. The example starts the counter at 2, so slugs would be 'this-is-an-example', 'this-is-an-example-2', etc.

```php
SlugOptions::create()
    ->generateSlugsFrom('name')
    ->saveSlugsTo('slug')
    ->startSlugSuffixFrom(2);
```

--------------------------------

### Direct use of makeUnique()

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/generate-slug-action.md

Direct usage example of makeUnique(). Returns the base slug if available, or appends a numeric suffix (starting at startSlugSuffixFrom) on collisions.

```php
$unique = $action->makeUnique('hello-world', $post, $post->getSlugOptions());
// "hello-world" or "hello-world-1" / "hello-world-2" on collisions
```

--------------------------------

### getRouteKey usage example

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/has-slug.md

Example showing the route key output for a post with id 5 and slug 'hello-world', and how it changes after updating the title.

```php
$post = Post::create(['title' => 'Hello World']); // id 5, slug "hello-world"
$post->getRouteKey(); // "hello-world-5"

$post->update(['title' => 'Hello Universe']);
$post->getRouteKey(); // "hello-universe-5"
```

--------------------------------

### Install laravel-sluggable via Composer

Source: https://github.com/spatie/laravel-sluggable/blob/main/README.md

Install the package via Composer.

```bash
composer require spatie/laravel-sluggable
```

--------------------------------

### Usage example for BuildSelfHealingRouteKeyAction

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/self-healing-actions.md

Example of using the BuildSelfHealingRouteKeyAction via the application container. Shows how to call execute with different separators and empty slugs, producing the expected route key strings.

```php
use Spatie\Sluggable\Actions\BuildSelfHealingRouteKeyAction;

$action = app(BuildSelfHealingRouteKeyAction::class);
$action->execute('hello-world', 5, '-');       // "hello-world-5"
$action->execute('', 5, '-');                  // "5"
$action->execute('hello-world', 5, '--');      // "hello-world--5" (selfHealingSeparator: '--')
```

--------------------------------

### Example: resolving a mistyped action key

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/support.md

Shows how to catch InvalidConfig when calling Config::getAction with an unknown key. The example uses 'generate_slugg' and expects the error message "No action class is configured for key `generate_slugg`."

```php
use Spatie\Sluggable\Actions\GenerateSlugAction;
use Spatie\Sluggable\Exceptions\InvalidConfig;
use Spatie\Sluggable\Support\Config;

try {
    Config::getAction('generate_slugg', GenerateSlugAction::class); // unknown key
} catch (InvalidConfig $e) {
    // "No action class is configured for key `generate_slugg`."
}
```

--------------------------------

### Basic usage examples for execute()

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/self-healing-actions.md

Shows how to instantiate the action via the container and call execute with different inputs. The comments show the expected return values for each case.

```php
use Spatie\Sluggable\Actions\ExtractIdentifierFromSelfHealingRouteKeyAction;

$action = app(ExtractIdentifierFromSelfHealingRouteKeyAction::class);
$action->execute('hello-world-5', '-');
// ['slug' => 'hello-world', 'identifier' => '5']

$action->execute('hello-world', '-');
// ['slug' => 'hello-world', 'identifier' => null]

$action->execute('hello-world-', '-');
// ['slug' => 'hello-world-', 'identifier' => null]
```

--------------------------------

### shouldSkipBasedOnSkipWhen usage example

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/generate-slug-action.md

Example used by HasTranslatableSlug::shouldSkipGeneration() to skip slug generation for draft states.

```php
if ($this->generateSlugAction()->shouldSkipBasedOnSkipWhen($this->slugOptions)) {
    return; // draft states never get slugs
}
```

--------------------------------

### getSlugOptions implementation example

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/has-slug.md

Example implementation that generates slugs from the 'title' field and saves them to the 'slug' field.

```php
public function getSlugOptions(): SlugOptions
{
    return SlugOptions::create()->generateSlugsFrom('title')->saveSlugsTo('slug');
}
```

--------------------------------

### startSlugSuffixFrom(int $startSlugSuffixFrom)

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/slug-options.md

Sets the starting number for slug suffixes, clamped to at least 1.

```APIDOC
## startSlugSuffixFrom(int $startSlugSuffixFrom)

### Description
Sets the starting suffix number for duplicate slugs (e.g., `slug-1`, `slug-2`), clamped with `max(1, ...)`.

### Method
startSlugSuffixFrom(int $startSlugSuffixFrom): static

### Parameters
- **startSlugSuffixFrom** (int) - Required - Starting suffix value.

### Return
`$this` (chainable).
```

--------------------------------

### generateSlug usage example

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/has-slug.md

Example of calling generateSlug() and then saving the model to persist the regenerated slug.

```php
$post->generateSlug();
$post->save();
```

--------------------------------

### Example of slug generation from multiple columns

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/advanced-usage/source-fields.md

Shows the resulting slug when creating an author with first and last name. The slug is 'john-doe'.

```php
$author = Author::create(['first_name' => 'John', 'last_name' => 'Doe']);
$author->slug; // "john-doe"
```

--------------------------------

### getLocalizedRouteKey usage example

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/has-translatable-slug.md

Shows how to retrieve localized route keys for different languages.

```php
$article->getLocalizedRouteKey('en'); // "english-title-5"
$article->getLocalizedRouteKey('nl'); // "nederlandse-titel-5"
```

--------------------------------

### Install laravel-sluggable v4

Source: https://github.com/spatie/laravel-sluggable/blob/main/UPGRADING.md

Command to install version 4 of the package. Requires PHP 8.3+, Laravel 12+, and spatie/laravel-translatable v6+ when using HasTranslatableSlug.

```bash
composer require spatie/laravel-sluggable "^4.0.0"
```

--------------------------------

### findBySlug with constraints

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/has-translatable-slug.md

Example of finding a model by slug while applying additional query constraints.

```php
$draft = Article::findBySlug('mijn-artikel', ['id', 'slug'], fn ($query) => $query->where('status', 'draft'));
```

--------------------------------

### Get route key with self-healing

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/basic-usage/self-healing-urls.md

With default options, a Post with id 5 and title 'Hello World' exposes a route key of 'hello-world-5'.

```php
$post = Post::create(['title' => 'Hello World']);
$post->getRouteKey(); // "hello-world-5"
```

--------------------------------

### skipGenerateWhen() closure example

Source: https://github.com/spatie/laravel-sluggable/blob/main/UPGRADING.md

Example of skipGenerateWhen() usage that works in both v3 and v4. In v4 the closure is stored and re-evaluated on every save, so it can see model state changes.

```php
// Both v3 and v4
return SlugOptions::create()
    ->generateSlugsFrom('title')
    ->saveSlugsTo('slug')
    ->skipGenerateWhen(fn () => $this->state === 'draft');
```

--------------------------------

### Catching StaleSelfHealingUrl Exception Example

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/self-healing.md

Example of catching StaleSelfHealingUrl in a custom route or middleware wrapper, accessing the exception properties and calling render to get the default 308 response.

```php
use Spatie\Sluggable\Exceptions\StaleSelfHealingUrl;

try {
    $post = Post::resolveRouteBinding('outdated-title-5');
} catch (StaleSelfHealingUrl $e) {
    // $e->model         → the Post (id 5)
    // $e->staleRouteKey → "outdated-title-5"
    $e->render($request); // → Response (default 308)
}
```

--------------------------------

### Direct handleStaleUrl call example

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/self-healing.md

Direct call to handleStaleUrl() with a non-default handler. The comment shows the expected default 308 redirect to the canonical URL.

```php
$manager = app(SelfHealingManager::class);

$response = $manager->handleStaleUrl($post, 'outdated-title-5', $request);
// 308 redirect to ".../hello-universe-5" by default

```

--------------------------------

### findBySlug basic usage

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/has-translatable-slug.md

Example of finding a model by slug, which matches the current locale or the fallback locale.

```php
$article = Article::findBySlug('mijn-artikel'); // matches current locale, then app.fallback_locale
```

--------------------------------

### Basic HasSlug trait setup with SlugOptions

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/basic-usage/using-the-has-slug-trait.md

Add the HasSlug trait and implement getSlugOptions() to configure slug generation. This is equivalent to the #[Sluggable(from: 'title', to: 'slug')] attribute.

```php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Spatie\Sluggable\HasSlug;
use Spatie\Sluggable\SlugOptions;

class Post extends Model
{
    use HasSlug;

    public function getSlugOptions(): SlugOptions
    {
        return SlugOptions::create()
            ->generateSlugsFrom('title')
            ->saveSlugsTo('slug');
    }
}
```

--------------------------------

### Always append a suffix with useSuffixOnFirstOccurrence()

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/advanced-usage/uniqueness.md

Adds a suffix even when the slug would otherwise be unique. Instead of 'this-is-an-example', 'this-is-an-example-1', you get 'this-is-an-example-1', 'this-is-an-example-2'.

```php
SlugOptions::create()
    ->generateSlugsFrom('name')
    ->saveSlugsTo('slug')
    ->useSuffixOnFirstOccurrence();
```

--------------------------------

### TraitDetector::uses and flushCache example

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/support.md

Example usage of TraitDetector::uses() to check if a model instance or class uses the HasSlug trait, and TraitDetector::flushCache() to empty the cache. The comments indicate the expected return values and caching behavior.

```php
use Spatie\Sluggable\Support\TraitDetector;

TraitDetector::uses($post, HasSlug::class);          // true
TraitDetector::uses(Post::class, HasSlug::class);    // true (cached)
TraitDetector::flushCache();
```

--------------------------------

### Custom separator via trait

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/basic-usage/self-healing-urls.md

Configure a custom separator using the SlugOptions trait. The example shows the resulting route key format.

```php
SlugOptions::create()
    ->generateSlugsFrom('title')
    ->saveSlugsTo('slug')
    ->selfHealing(separator: '--');

// route key: "hello-world--5"
```

--------------------------------

### makeUnique() - Generate unique slug

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/generate-slug-action.md

Generates a unique slug. Fast path uses a single LIKE 'base%' query and picks the lowest unused numeric suffix starting from startSlugSuffixFrom, skipping gaps (e.g., base, base-1, base-2). Slow path (when cannotUseSlugVariantQuery is true) uses iterative probing with otherRecordExistsWithSlug().

```php
public function makeUnique(string $slug, Model $model, SlugOptions $options): string
{
    if ($this->cannotUseSlugVariantQuery($slug, $options)) {
        return $this->makeUniqueIterative($slug, $model, $options);
    }

    $existing = $this->fetchExistingSlugVariants($slug, $model, $options);
    $originalIsTaken = in_array($slug, $existing, true);

    if (! $options->useSuffixOnFirstOccurrence) {
        if (! $originalIsTaken) {
            return $slug;
        }
    }

    $prefix = $slug.$options->slugSeparator;
    $usedSuffixes = $this->extractNumericSuffixes($existing, $prefix);

    $candidate = $options->startSlugSuffixFrom;
    while (isset($usedSuffixes[$candidate])) {
        $candidate++;
    }

    return $prefix.$candidate;
}
```

--------------------------------

### resolveRouteBindingQuery route configuration

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/has-translatable-slug.md

Example of using implicit route binding with a slug column in Laravel routes.

```php
// routes/web.php
Route::get('/articles/{article:slug}', fn (Article $article) => $article);
```

--------------------------------

### Register a closure with SelfHealing to customize redirect behavior

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/basic-usage/self-healing-urls.md

Register a closure in the boot() method of a service provider. The closure receives the resolved model, the stale route key, and the incoming request, and returns the response. This example returns a 307 temporary redirect instead of the default 308.

```php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Http\Request;
use Spatie\Sluggable\Facades\SelfHealing;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        SelfHealing::onStaleSelfHealingUrl(function (Model $model, string $staleRouteKey, Request $request) {
            return redirect()->route('posts.show', $model, status: 307);
        });
    }
}
```

--------------------------------

### Create and update Post to see slug generation

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/basic-usage/getting-started.md

Slugs are written when the model is created and regenerated whenever the source field changes. The example shows the resulting slug values for create and update operations.

```php
$post = Post::create(['title' => 'Hello World']);
$post->slug; // "hello-world"

$post->update(['title' => 'Hello Universe']);
$post->slug; // "hello-universe"

```

--------------------------------

### Custom stale URL handler with SelfHealing facade

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/self-healing.md

Example of registering a custom handler via the SelfHealing facade. It returns a 307 redirect to the posts.show route, overriding the default 308 behavior.

```php
SelfHealing::onStaleSelfHealingUrl(function (Model $model, string $staleRouteKey, Request $request) {
    return redirect()->route('posts.show', $model, status: 307);
});

```

--------------------------------

### Manual validation of SlugOptions with InvalidOption

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/generate-slug-action.md

Error handling example: manually validating options before a save. Uses an empty source list to trigger an InvalidOption exception with message 'Could not determine which fields should be sluggified'.

```php
use Spatie\Sluggable\Exceptions\InvalidOption;
use Spatie\Sluggable\SlugOptions;

$options = SlugOptions::create()->generateSlugsFrom([]); // empty source list

try {
    app(GenerateSlugAction::class)->ensureValidOptions($options);
} catch (InvalidOption $e) {
    // "Could not determine which fields should be sluggified"
}
```

--------------------------------

### Custom GenerateSlugAction subclass with underscore separator

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/generate-slug-action.md

Advanced example: a subclass of GenerateSlugAction that changes the separator to underscore at generation time. The replacement must extend the default action (enforced by Config::getActionClass).

```php
namespace App\Sluggable;

use Spatie\Sluggable\Actions\GenerateSlugAction;

class UnderscoreSlugAction extends GenerateSlugAction
{
    public function slugifySource(string $source, SlugOptions $options): string
    {
        return parent::slugifySource($source, $options->usingSeparator('_'));
    }
}
```

```php
// config/sluggable.php
'generate_slug' => App\Sluggable\UnderscoreSlugAction::class,
```

--------------------------------

### SluggableAttributeResolver basic usage and error handling

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/support.md

Shows how to use SluggableAttributeResolver to resolve slug options and perform self-healing resolution, including error handling for models that enable selfHealing without the HasSlug trait. The example also demonstrates flushing the resolver cache.

```php
use Spatie\Sluggable\Exceptions\SelfHealingRequiresTrait;
use Spatie\Sluggable\Support\SluggableAttributeResolver;

$options = SluggableAttributeResolver::resolveOptions(Post::class); // ?SlugOptions

if ($options !== null) {
    // equivalent of SlugOptions::create()->generateSlugsFrom(...)->saveSlugsTo(...)->...
}

try {
    SluggableAttributeResolver::resolve(BrokenPost::class); // selfHealing without trait
} catch (SelfHealingRequiresTrait $e) {
    // "Model `...BrokenPost` enables `selfHealing` via the `#[Sluggable]` attribute
    //  but does not use the `...HasSlug` trait. ..."
}

SluggableAttributeResolver::flushCache();
```

--------------------------------

### Custom separator for selfHealing route key

Source: https://github.com/spatie/laravel-sluggable/blob/main/resources/boost/skills/sluggable-development/SKILL.md

Use the separator parameter to change the delimiter between the slug and primary key. The example uses '--' to produce a route key like 'hello-world--5'.

```php
->selfHealing(separator: '--'); // route key: "hello-world--5"
```

--------------------------------

### Route definition for custom stale handling

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/has-slug.md

Example route definition that uses the model binding. The 308 redirect behavior is handled automatically by StaleSelfHealingUrl::render() and SelfHealingManager::handleStaleUrl(), requiring no controller code.

```php
// routes/web.php
Route::get('/posts/{post}', fn (Post $post) => $post);
```

--------------------------------

### Run the test suite

Source: https://github.com/spatie/laravel-sluggable/blob/main/README.md

Run the package's test suite.

```bash
composer test
```

--------------------------------

### boot(): void - Publish config and register attribute listeners

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/service-provider.md

Publishes the configuration file to config/sluggable.php under the 'sluggable-config' tag when running in the console, enabling customization of actions. Also registers attribute listeners via registerAttributeListeners().

```php
public function boot(): void
{
    if ($this->app->runningInConsole()) {
        $this->publishes([
            __DIR__.'/../config/sluggable.php' => config_path('sluggable.php'),
        ], 'sluggable-config');
    }

    $this->registerAttributeListeners();
}
```

--------------------------------

### startSlugSuffixFrom() method signature

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/slug-options.md

Signature of startSlugSuffixFrom() method.

```php
public function startSlugSuffixFrom(int $startSlugSuffixFrom): static
```

--------------------------------

### SlugOptions::create()

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/slug-options.md

Static factory method returning a new SlugOptions instance.

```APIDOC
## SlugOptions::create()

### Description
Creates a new SlugOptions instance with late static binding (`new static`).

### Method
static create(): static

### Parameters
None.

### Return
A new SlugOptions instance.

### Example
```php
use Spatie\Sluggable\SlugOptions;

public function getSlugOptions(): SlugOptions
{
    return SlugOptions::create()
        ->generateSlugsFrom('title')
        ->saveSlugsTo('slug');
}
```
```

--------------------------------

### IdFirstBuildAction class

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/advanced-usage/overriding-actions.md

Builds a route key with the identifier first, e.g., 5-hello-world instead of hello-world-5. Returns just the identifier when the slug is empty.

```php
namespace App\Sluggable;

use Spatie\Sluggable\Actions\BuildSelfHealingRouteKeyAction;

class IdFirstBuildAction extends BuildSelfHealingRouteKeyAction
{
    public function execute(string $slug, int|string $identifier, string $separator): string
    {
        if ($slug === '') {
            return (string) $identifier;
        }

        return "{$identifier}{$separator}{$slug}";
    }
}
```

--------------------------------

### Publish the sluggable config

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/advanced-usage/overriding-actions.md

Run this artisan command to publish the configuration file before pointing any action key at a custom class.

```bash
php artisan vendor:publish --tag=sluggable-config
```

--------------------------------

### create() method signature

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/slug-options.md

Signature of the create() method. Returns a new SlugOptions instance using late static binding.

```php
public static function create(): static
```

--------------------------------

### Config for swapping both actions

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/self-healing-actions.md

This configuration snippet shows how to set both the build and extract actions to the custom classes. Both must be swapped together for the {id}-{slug} format to work.

```php
// config/sluggable.php
'build_self_healing_route_key' => App\Sluggable\IdFirstBuildAction::class,
'extract_identifier_from_self_healing_route_key' => App\Sluggable\IdFirstExtractAction::class,
```

--------------------------------

### onCreate method

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/generate-slug-action.md

Adds a slug when creating a model, unless generateSlugsOnCreate is false or generation is skipped. Writes to the slug field.

```php
public function onCreate(Model $model, SlugOptions $options): void
{
    if (! $options->generateSlugsOnCreate) {
        return;
    }

    if ($this->shouldSkipGeneration($model, $options)) {
        return;
    }

    $this->addSlug($model, $options);
}
```

--------------------------------

### Bind Post model to route with self-healing

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/basic-usage/getting-started.md

Bind the model to a route the usual way; the package handles the route key for you. A request to /posts/hello-world-5 resolves the post, and renaming it later doesn't break the link.

```php
// routes/web.php
Route::get('/posts/{post}', fn (Post $post) => view('posts.show', compact('post')));

```

--------------------------------

### Advanced configuration with scoped uniqueness, conditional skip, custom suffix generator, and self-healing

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/slug-options.md

Demonstrates advanced SlugOptions configuration: generating slugs from a closure combining author name and title, scoping uniqueness to a tenant, skipping generation for drafts, using a custom suffix generator that produces random hex strings, and enabling self-healing with a custom separator.

```php
public function getSlugOptions(): SlugOptions
{
    return SlugOptions::create()
        ->generateSlugsFrom(fn (Post $post) => "{$post->author->name} {$post->title}")
        ->saveSlugsTo('slug')
        ->skipGenerateWhen(fn () => $this->state === 'draft')
        ->extraScope(fn ($query) => $query->where('tenant_id', $this->tenant_id))
        ->usingSuffixGenerator(fn (string $slug, int $iteration) => bin2hex(random_bytes(4)))
        ->selfHealing(separator: '--');
}
```

--------------------------------

### Generate slugs from a callable per locale with createWithLocales()

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/translatable-slugs.md

Generate slugs from a callable per locale. Instantiate SlugOptions with createWithLocales() and the callable receives the model and the current locale.

```php
public function getSlugOptions(): SlugOptions
{
    return SlugOptions::createWithLocales(['en', 'nl'])
        ->generateSlugsFrom(fn (Article $article, string $locale) => "{$locale} {$article->id}")
        ->saveSlugsTo('slug');
}
```

--------------------------------

### Override generate_slug in config/sluggable.php

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/service-provider.md

After publishing the config, you can override the 'generate_slug' key to use your custom action class. This is a PHP configuration snippet shown as an example of the overridable setting.

```php
// config/sluggable.php — now overridable
'generate_slug' => App\Sluggable\MyGenerateSlugAction::class,
```

--------------------------------

### onCreate(Model $model, SlugOptions $options): void

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/generate-slug-action.md

Generates a slug for a model when it is being created, unless generation is disabled or skipped. Writes the slug to the model's slug field.

```APIDOC
## onCreate(Model $model, SlugOptions $options): void

### Description
Generates a slug for a model when it is being created, unless generation is disabled or skipped. Writes the slug to the model's slug field.

### Method
onCreate

### Signature
`public function onCreate(Model $model, SlugOptions $options): void`

### Parameters
- **$model** (Model) - Required - The Eloquent model being created.
- **$options** (SlugOptions) - Required - The governing SlugOptions.

### Return
void - Writes `$model->{$options->slugField}` unless `generateSlugsOnCreate` is false or generation is skipped.

### Throws
- **InvalidOption** - via `addSlug()` → `ensureValidOptions()`.

### Example
```php
$action = app(GenerateSlugAction::class);
$action->onCreate($model, $options);
```
```

--------------------------------

### Generate migration for slug column

Source: https://github.com/spatie/laravel-sluggable/blob/main/resources/boost/skills/sluggable-development/SKILL.md

Run this artisan command to create a new migration file for adding a slug column to the posts table.

```bash
php artisan make:migration add_slug_to_posts_table
```

--------------------------------

### Basic #[Sluggable] attribute usage

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/sluggable-attribute.md

Basic usage of the #[Sluggable] attribute to generate a slug from the 'title' column into the 'slug' column on create and update. The example shows the resulting slug value for a sample title.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Sluggable\Attributes\Sluggable;

#[Sluggable(from: 'title', to: 'slug')]
class Post extends Model
{
}

$post = Post::create(['title' => 'activerecord is awesome']);
$post->slug; // "activerecord-is-awesome"
```

--------------------------------

### useSuffixOnFirstOccurrence() method signature

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/slug-options.md

Signature of useSuffixOnFirstOccurrence() method.

```php
public function useSuffixOnFirstOccurrence(): static
```

--------------------------------

### Generate a slug with the #[Sluggable] attribute

Source: https://github.com/spatie/laravel-sluggable/blob/main/README.md

Add the #[Sluggable] attribute to an Eloquent model to automatically generate a unique slug from the 'title' attribute into the 'slug' attribute on create and update. The example shows creating a Post and accessing the resulting slug.

```php
use Spatie\Sluggable\Attributes\Sluggable;

#[Sluggable(from: 'title', to: 'slug')]
class Post extends Model
{
}

$post = Post::create(['title' => 'activerecord is awesome']);
$post->slug; // "activerecord-is-awesome"
```

--------------------------------

### class-string<T> template parameter in Config methods

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/types.md

Shows the template parameter usage in Config::getActionClass() and Config::getAction(). The $mustBeOrExtend parameter names the default action class (e.g., GenerateSlugAction::class); the configured class must be or extend it (is_a(..., true)). getAction() returns a container instance typed as that class.

```php
/**
 * @template T of object
 *
 * @param  class-string<T>  $mustBeOrExtend
 * @return class-string<T>
 */
public static function getActionClass(string $actionKey, string $mustBeOrExtend): string

/**
 * @template T of object
 *
 * @param  class-string<T>  $mustBeOrExtend
 * @return T
 */
public static function getAction(string $actionKey, string $mustBeOrExtend): object
```

--------------------------------

### usingSeparator() and usingLanguage() signatures

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/slug-options.md

Signatures of usingSeparator() and usingLanguage() methods.

```php
public function usingSeparator(string $separator): static

public function usingLanguage(string $language): static
```

--------------------------------

### Make a field sluggable with the #[Sluggable] attribute

Source: https://github.com/spatie/laravel-sluggable/blob/main/resources/boost/skills/sluggable-development/SKILL.md

Use the #[Sluggable] attribute on a model to automatically generate a slug from a source column into a destination column. Creating a model writes the slug into the configured column; the example shows the resulting slug value.

```php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Spatie\Sluggable\Attributes\Sluggable;

#[Sluggable(from: 'title', to: 'slug')]
class Post extends Model
{
}

```

```php
$post = Post::create(['title' => 'Hello World']);
$post->slug; // "hello-world"

```

--------------------------------

### slugifySource method

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/generate-slug-action.md

Slugifies a source string using Str::slug with the configured separator and language.

```php
public function slugifySource(string $source, SlugOptions $options): string
{
    return Str::slug($source, $options->slugSeparator, $options->slugLanguage);
}
```

--------------------------------

### Suffix-generator closure and usingSuffixGenerator()

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/types.md

Suffix-generator closure shape and its builder. The closure takes the base slug and collision iteration (starting at 0) and returns the suffix appended as "{base}{separator}{suffix}". A non-null suffixGenerator forces the iterative uniqueness path.

```php
/** @var (Closure(string, int): string)|null */
public ?Closure $suffixGenerator = null;
```

```php
/**
 * @param  Closure(string $slug, int $iteration): string  $generator
 */
public function usingSuffixGenerator(Closure $generator): static
```

--------------------------------

### Basic slug generation with SlugOptions

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/generate-slug-action.md

Basic usage of the trait path that implicitly uses GenerateSlugAction. Sets up slug generation from the 'title' field to the 'slug' field. Defaults: maximumLength = 250, uniqueness on, numeric -1/-2 suffixes.

```php
use Spatie\Sluggable\SlugOptions;

public function getSlugOptions(): SlugOptions
{
    return SlugOptions::create()->generateSlugsFrom('title')->saveSlugsTo('slug');
}
// SlugOptions::$maximumLength = 250, uniqueness on, numeric -1/-2 suffixes
```

--------------------------------

### Configure custom action classes in config/sluggable.php

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/advanced-usage/overriding-actions.md

Edit the published config file to point the action keys at your own classes. Replacement classes must extend the default action so the package can type-check the override.

```php
// config/sluggable.php
return [
    'actions' => [
        'generate_slug' => App\Sluggable\MyGenerateSlugAction::class,
        'build_self_healing_route_key' => Spatie\Sluggable\Actions\BuildSelfHealingRouteKeyAction::class,
        'extract_identifier_from_self_healing_route_key' => Spatie\Sluggable\Actions\ExtractIdentifierFromSelfHealingRouteKeyAction::class,
    ],
];
```

--------------------------------

### Catching SelfHealingRequiresTrait when resolving options

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/sluggable-attribute.md

Error handling example showing that a model with selfHealing: true but missing the HasSlug trait throws SelfHealingRequiresTrait when the resolver inspects the class. The exception also surfaces inside the event listener during the first create; catch it when resolving options manually.

```php
use Spatie\Sluggable\Exceptions\SelfHealingRequiresTrait;
use Spatie\Sluggable\Support\SluggableAttributeResolver;

#[Sluggable(from: 'title', to: 'slug', selfHealing: true)]
class BrokenPost extends Model
{
    // missing: use HasSlug;
}

try {
    SluggableAttributeResolver::resolveOptions(BrokenPost::class);
} catch (SelfHealingRequiresTrait $e) {
    // message: "Model `...BrokenPost` enables `selfHealing` via the
    // `#[Sluggable]` attribute but does not use the `...HasSlug` trait. ..."
    error_log($e->message());
}
```

--------------------------------

### Get localized route key with getLocalizedRouteKey()

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/translatable-slugs.md

Retrieve the route key for a given locale without permanently changing the model's active locale. The method swaps in the requested locale, calls getRouteKey(), and restores the original locale via try/finally, so the model is always left as it was found, including when getRouteKey() throws.

```php
$article->getLocalizedRouteKey('nl'); // "nederlandse-titel-5"
```

--------------------------------

### Full Config class definition

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/support.md

The complete source of Spatie\Sluggable\Support\Config, which resolves action classes from config('sluggable.actions.*') and validates them against required parent classes. It throws InvalidConfig exceptions for missing, non-existent, or incompatible action classes.

```php
<?php

namespace Spatie\Sluggable\Support;

use Spatie\Sluggable\Exceptions\InvalidConfig;

class Config
{
    public const ACTION_GENERATE_SLUG = 'generate_slug';

    public const ACTION_BUILD_SELF_HEALING_ROUTE_KEY = 'build_self_healing_route_key';

    public const ACTION_EXTRACT_IDENTIFIER_FROM_SELF_HEALING_ROUTE_KEY = 'extract_identifier_from_self_healing_route_key';

    /**
     * @template T of object
     *
     * @param  class-string<T>  $mustBeOrExtend
     * @return class-string<T>
     */
    public static function getActionClass(string $actionKey, string $mustBeOrExtend): string
    {
        $actionClass = config("sluggable.actions.{$actionKey}");

        if (! $actionClass) {
            throw InvalidConfig::actionKeyNotFound($actionKey);
        }

        if (! class_exists($actionClass)) {
            throw InvalidConfig::actionClassDoesNotExist($actionClass);
        }

        if (! is_a($actionClass, $mustBeOrExtend, true)) {
            throw InvalidConfig::actionClassDoesNotExtend($actionClass, $mustBeOrExtend);
        }

        return $actionClass;
    }

    /**
     * @template T of object
     *
     * @param  class-string<T>  $mustBeOrExtend
     * @return T
     */
    public static function getAction(string $actionKey, string $mustBeOrExtend): object
    {
        $actionClass = self::getActionClass($actionKey, $mustBeOrExtend);

        return app($actionClass);
    }
}
```

--------------------------------

### Register stale-URL handler in AppServiceProvider boot()

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/service-provider.md

Use this snippet in your own service provider's boot() method to register a handler for stale self-healing URLs. The SelfHealing facade forwards to the singleton registered by this provider. The callback receives the model, stale route key, and request, and returns a redirect with status 307.

```php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Spatie\Sluggable\Facades\SelfHealing;

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        SelfHealing::onStaleSelfHealingUrl(function ($model, $staleRouteKey, $request) {
            return redirect()->route('posts.show', $model, status: 307);
        });
    }
}
```

--------------------------------

### Non-trivial #[Sluggable] configuration with selfHealing

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/sluggable-attribute.md

Non-trivial configuration using multiple source columns, a max length of 100, overwrite prevention, and a custom self-healing separator. The HasSlug trait is mandatory when selfHealing is enabled.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Sluggable\Attributes\Sluggable;
use Spatie\Sluggable\HasSlug;

#[Sluggable(
    from: ['first_name', 'last_name'],
    to: 'slug',
    separator: '-',
    maxLength: 100,
    preventOverwrite: true,
    selfHealing: true,
    selfHealingSeparator: '--',
)]
class Author extends Model
{
    use HasSlug;
}
```

--------------------------------

### usingSeparator(string $separator) / usingLanguage(string $language)

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/slug-options.md

Configures the slug separator and language used during slug generation.

```APIDOC
## usingSeparator(string $separator) / usingLanguage(string $language)

### Description
Sets the separator used in the slug (e.g., `-`) and the language for transliteration, respectively.

### Methods
- `usingSeparator(string $separator): static`
- `usingLanguage(string $language): static`

### Parameters
- **separator** (string) - Required - Separator to use in slug.
- **language** (string) - Required - Language code for slug generation.

### Return
`$this` (chainable).

### Effects
- Sets `slugSeparator` / `slugLanguage`.
```

--------------------------------

### UppercaseRouteKeyAction class

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/advanced-usage/overriding-actions.md

Extends the default BuildSelfHealingRouteKeyAction and overrides execute() to wrap the parent call with strtoupper on the slug.

```php
namespace App\Sluggable;

use Spatie\Sluggable\Actions\BuildSelfHealingRouteKeyAction;

class UppercaseRouteKeyAction extends BuildSelfHealingRouteKeyAction
{
    public function execute(string $slug, int|string $identifier, string $separator): string
    {
        return parent::execute(strtoupper($slug), $identifier, $separator);
    }
}
```

--------------------------------

### createWithLocales() method signature

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/slug-options.md

Signature of createWithLocales() with docblock. Accepts an array of locale codes.

```php
/**
 * @param  array<int, string>  $locales
 */
public static function createWithLocales(array $locales): static
```

--------------------------------

### extraScope() method signature

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/slug-options.md

Signature of extraScope() method.

```php
public function extraScope(Closure $callbackMethod): static
```

--------------------------------

### Default config file contents

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/installation-setup.md

The published config file lists overridable actions. It maps action keys to default action classes. See the 'Overriding actions' documentation for details.

```php
return [
    'actions' => [
        'generate_slug' => Spatie\Sluggable\Actions\GenerateSlugAction::class,
        'build_self_healing_route_key' => Spatie\Sluggable\Actions\BuildSelfHealingRouteKeyAction::class,
        'extract_identifier_from_self_healing_route_key' => Spatie\Sluggable\Actions\ExtractIdentifierFromSelfHealingRouteKeyAction::class,
    ],
];
```

--------------------------------

### Config::getAction(string $actionKey, string $mustBeOrExtend): object

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/support.md

Resolves and instantiates the configured action class through the container, returning an instance of the configured action. Throws the same InvalidConfig errors as getActionClass.

```APIDOC
## Config::getAction(string $actionKey, string $mustBeOrExtend): object

### Description
Resolves and instantiates the configured action class through the container, returning an instance of the configured action. Throws the same InvalidConfig errors as getActionClass.

### Method
static

### Signature
public static function getAction(string $actionKey, string $mustBeOrExtend): object

### Parameters
- **actionKey** (string) - Required - One of the three action keys (or a custom key you added to the config file).
- **mustBeOrExtend** (string, class-string<T>) - Required - The default action class the configured class must be or extend.

### Return
object (T) - The container instance of the configured action class (app($actionClass)).

### Throws
- **Spatie\Sluggable\Exceptions\InvalidConfig** - If config("sluggable.actions.{$actionKey}") is falsy (actionKeyNotFound).
- **Spatie\Sluggable\Exceptions\InvalidConfig** - If class_exists() is false (actionClassDoesNotExist).
- **Spatie\Sluggable\Exceptions\InvalidConfig** - If is_a($actionClass, $mustBeOrExtend, true) is false (actionClassDoesNotExtend).

### Example (error handling — resolving a mistyped key)
```php
use Spatie\Sluggable\Actions\GenerateSlugAction;
use Spatie\Sluggable\Exceptions\InvalidConfig;
use Spatie\Sluggable\Support\Config;

try {
    Config::getAction('generate_slugg', GenerateSlugAction::class); // unknown key
} catch (InvalidConfig $e) {
    // "No action class is configured for key `generate_slugg`."
}
```
```

--------------------------------

### doNotGenerateSlugsOnCreate() and doNotGenerateSlugsOnUpdate() signatures

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/slug-options.md

Signatures of doNotGenerateSlugsOnCreate() and doNotGenerateSlugsOnUpdate() methods.

```php
public function doNotGenerateSlugsOnCreate(): static

public function doNotGenerateSlugsOnUpdate(): static
```

--------------------------------

### register(): void - Merge config and register SelfHealingManager

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/service-provider.md

Merges the package configuration file into the application config under the 'sluggable' key and registers SelfHealingManager as a singleton. This makes config('sluggable.actions.*') available to Config::getActionClass().

```php
public function register(): void
{
    $this->mergeConfigFrom(__DIR__.'/../config/sluggable.php', 'sluggable');

    $this->app->singleton(SelfHealingManager::class);
}
```

--------------------------------

### allowDuplicateSlugs() method signature

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/slug-options.md

Signature of allowDuplicateSlugs() method.

```php
public function allowDuplicateSlugs(): static
```

--------------------------------

### Full SlugOptions class definition

Source: https://github.com/spatie/laravel-sluggable/blob/main/_autodocs/api-reference/slug-options.md

The complete class definition for SlugOptions, including all chainable configuration methods and default settings.

```php
<?php

namespace Spatie\Sluggable;

use Closure;

class SlugOptions
{
    public const DEFAULT_SEPARATOR = '-';

    public const DEFAULT_LANGUAGE = 'en';

    public const DEFAULT_MAX_LENGTH = 250;

    /** @var array<int, string>|Closure */
    public array|Closure $generateSlugFrom;

    public ?Closure $skipGenerateWhen = null;

    public ?Closure $extraScopeCallback = null;

    /** @var (Closure(string, int): string)|null */
    public ?Closure $suffixGenerator = null;

    public string $slugField;

    public bool $generateUniqueSlugs = true;

    public int $maximumLength = self::DEFAULT_MAX_LENGTH;

    public bool $generateSlugsOnCreate = true;

    public bool $generateSlugsOnUpdate = true;

    public bool $preventOverwrite = false;

    public string $slugSeparator = self::DEFAULT_SEPARATOR;

    public string $slugLanguage = self::DEFAULT_LANGUAGE;

    /** @var array<int, string> */
    public array $translatableLocales = [];

    public int $startSlugSuffixFrom = 1;

    public bool $useSuffixOnFirstOccurrence = false;

    public bool $selfHealingUrls = false;

    public string $selfHealingSeparator = self::DEFAULT_SEPARATOR;

    public static function create(): static
    {
        return new static;
    }

    /**
     * @param  array<int, string>  $locales
     */
    public static function createWithLocales(array $locales): static
    {
        $slugOptions = static::create();
        $slugOptions->translatableLocales = $locales;

        return $slugOptions;
    }

    /**
     * @param  string|array<int, string>|Closure  $fieldName
     */
    public function generateSlugsFrom(string|array|Closure $fieldName): static
    {
        if (is_string($fieldName)) {
            $fieldName = [$fieldName];
        }

        $this->generateSlugFrom = $fieldName;

        return $this;
    }

    public function saveSlugsTo(string $fieldName): static
    {
        $this->slugField = $fieldName;

        return $this;
    }

    public function allowDuplicateSlugs(): static
    {
        $this->generateUniqueSlugs = false;

        return $this;
    }

    public function slugsShouldBeNoLongerThan(int $maximumLength): static
    {
        $this->maximumLength = $maximumLength;

        return $this;
    }

    public function skipGenerateWhen(Closure $callable): static
    {
        $this->skipGenerateWhen = $callable;

        return $this;
    }

    public function doNotGenerateSlugsOnCreate(): static
    {
        $this->generateSlugsOnCreate = false;

        return $this;
    }

    public function doNotGenerateSlugsOnUpdate(): static
    {
        $this->generateSlugsOnUpdate = false;

        return $this;
    }

    public function preventOverwrite(): static
    {
        $this->preventOverwrite = true;

        return $this;
    }

    public function usingSeparator(string $separator): static
    {
        $this->slugSeparator = $separator;

        return $this;
    }

    public function usingLanguage(string $language): static
    {
        $this->slugLanguage = $language;

        return $this;
    }

    public function extraScope(Closure $callbackMethod): static
    {
        $this->extraScopeCallback = $callbackMethod;

        return $this;
    }

    public function startSlugSuffixFrom(int $startSlugSuffixFrom): static
    {
        $this->startSlugSuffixFrom = max(1, $startSlugSuffixFrom);

        return $this;
    }

    public function useSuffixOnFirstOccurrence(): static
    {
        $this->useSuffixOnFirstOccurrence = true;

        return $this;
    }

    public function selfHealing(string $separator = self::DEFAULT_SEPARATOR): static
    {
        $this->selfHealingUrls = true;
        $this->selfHealingSeparator = $separator;

        return $this;
    }

    /**
     * @param  Closure(string $slug, int $iteration): string  $generator
     */
    public function usingSuffixGenerator(Closure $generator): static
    {
        $this->suffixGenerator = $generator;

        return $this;
    }
}
```

--------------------------------

### Find by slug with selected columns

Source: https://github.com/spatie/laravel-sluggable/blob/main/docs/basic-usage/finding-models-by-slug.md

The second argument is a list of columns to select, matching Eloquent's find() method.

```php
Article::findBySlug('my-article', ['id', 'slug', 'title']);
```
Tokens:
Raw