Slugable Laravel Package

Getting Started

This release is a refactor of the slug generation internals rather than a feature drop, so the surface API should look familiar if you have used the package before. Start by confirming the public entry point in the package README — typically a facade/helper (e.g. Str::slug() style global helper or a Slug facade) plus a model trait or observer for automatic slug assignment on save.

Minimal setup:

1. composer require the package (already done if upgrading) and check composer show <vendor>/<package> to confirm you are on 2.1.0.
2. Publish any config if the package ships one (php artisan vendor:publish --tag=...) and diff it against your existing published copy — a refactor of slug logic often adds or renames options such as separator, max length, uniqueness suffix strategy, or transliteration source.
3. Run the package's own test suite or a quick tinker check on a handful of real strings from your domain before trusting it in a migration or backfill.

First use case: take one existing model with a slug column, generate a slug for a title containing accents, mixed case, and punctuation, and compare the output with what your current production data looks like. This immediately tells you whether the refactor changed behaviour for your inputs.

Implementation Patterns

Manual generation in a form request or action. Generate the slug explicitly when you need control over the source field, then persist it:

$slug = $slugs->generate($request->input('title'));
$post = Post::create([...$request->validated(), 'slug' => $slug]);

Keep the slug generation in a single service/action rather than scattering calls across controllers — a refactor like this one is much easier to absorb when there is one call site per concept.

Model-level automation. If the package provides a trait/observer for auto-slugging, wire it up behind a saving hook and make it idempotent: only regenerate when the source attribute is dirty, or when the slug is empty. This avoids surprise slug churn on unrelated updates — important after a refactor, since uniqueness handling may now append suffixes differently.

Uniqueness and collision handling. Treat uniqueness as a database concern as well as a package concern: keep a unique index on the slug column, and wrap creation in a retry or firstOrCreate-style loop. If the refactor changed the suffix format (-1, -2 versus timestamp or random suffix), existing rows will not collide with new ones, but your tests asserting exact slug strings will.

Backfills and migrations. For existing data, do not bulk-regenerate slugs silently. Write a one-off command that computes the new slug, logs diffs, and only updates rows where the slug is empty or explicitly flagged. Preserve old slugs in a redirects table if URLs are public.

Testing pattern. Add a data-provider test with the exact inputs you care about — accented characters, CJK, emoji, very long titles, all-punctuation titles, duplicate titles — and assert the generated value. This is your cheapest guard against future refactors.

Gotchas and Tips

• Refactor means possible silent behaviour change. The release notes give no changelog detail on transliteration, separator handling, or truncation. Diff the package source for the slug method (or read the updated tests) — the tests are the specification here, and "updated tests" is a hint that expected outputs moved.
• Cached config. If you have run php artisan config:cache, stale published config can mask new defaults. Clear config and opcache after upgrading.
• Existing data drift. New slugs generated post-upgrade may not match slugs generated pre-upgrade for the same title. That is fine for new records but will break tests, seeders, and any fixtures asserting literal slug strings. Regenerate fixtures rather than loosening assertions.
• Uniqueness edge cases. Check what happens when the base slug plus suffix exceeds the column length — truncation order matters and is a common regression in slug refactors. Test a title right at your varchar(255) boundary.
• Locale/transliteration dependency. If slugs are locale-sensitive, confirm the refactor did not change the default locale source (app locale vs. explicit argument). Set it explicitly at the call site rather than relying on the default.
• Idempotency. Verify that generating a slug from an already-slugged string is stable. If it is not, guard against double-slugging in your observer/trait.
• Extension point. If you previously extended or overrode the package's slug generator (custom method, bound interface), this refactor is the moment to re-verify your override still receives the same inputs and is still called. Re-run your own integration tests, not just the package's.
• Rollback plan. Since output format may have shifted, deploy behind a feature flag or with a reversible migration, and keep the old slug values in a column or audit table until you have confirmed redirects/SEO are unaffected.