Search by

pushery / polyslug-for-laravel

pushery

Polymorphic, multilingual routable identity for Eloquent — leak-safe IDs, per-locale slugs, and hreflang out of the box.

Package info

github.com/pushery/polyslug-for-laravel

pkg:composer/pushery/polyslug-for-laravel

Security

Advisories: 0

Aikido package health analysis

Transparency log

Statistics

Installs: 5 492

Dependents: 0

Suggesters: 0

Stars: 6

Open Issues: 0

v0.18.9 2026-09-14 11:23 UTC

Requires

Requires (Dev)

None

Suggests

  • laravel/head: Lets a Polyslug model describe its own <head>: Head::polyslug($model) writes the canonical URL, the reciprocal hreflang set, the Open Graph locale set and the robots directive from the model's own slug data. Needs Laravel 13.17+, which is laravel/head's own floor - Polyslug itself needs only 13.0.

Provides

None

Conflicts

None

Replaces

None

MIT ce39410aa63ca99b27bc8f19baaedf45ffb521b9

laravel

Published on Packagist.org on 2026-09-14 11:23 UTC

This package is auto-updated.

Last update: 2026-09-14 11:23:54 UTC

README

Polyslug

Polyslug

Latest Version PHP Version Laravel Versions License

Tests Coverage Type Coverage PHPStan Code Style Databases Mutation

Polymorphic, multilingual routable identity for Eloquent. Pretty URLs that are safe to expose, safe to rename, and correct across languages — with leak-free IDs, self-healing canonical redirects, and hreflang built in.

/blog/laravel-routing-explained_aB3xK
      └──────── slug ─────────┘ └id─┘
   changeable, localized, SEO-friendly   stable, opaque, resolves the model

A slug should be free to change. A URL should never break. Those two goals usually fight each other. Polyslug settles the fight by splitting a URL into two independent parts — a human-readable slug (pretty, per-locale, editable) and a stable opaque identity (an encoded token that resolves the model). Rename the slug all you like: the identity still resolves, and old URLs redirect themselves to the new canonical one.

Install

composer require pushery/polyslug-for-laravel
php artisan migrate

Mark a model as sluggable, point a route at it, and you are done:

#[Polyslug(source: 'title')]
class Page extends Model implements Sluggable
{
    use HasPolyslug;
}

Route::polyslug('/pages/{page}', [PageController::class, 'show'])->name('pages.show');

Rename the page and the old URL 301s to the new one, by itself.

Why Polyslug?

  • 🔒 Leak-safe IDs by default. URLs carry an encoded token, not /pages/1523. No exposed row counts, no enumerable primary keys. The default encoder issues a random, unguessable token per row — the only shipped encoder that makes that claim true end to end. The choice is yours, though: Sqids, UUID, ULID, the raw key, or your own.
  • 📏 URLs as short as you want them. The URL is {slug}_{token} by default, and both halves are yours to drop or shrink: slugless: true makes it the token alone (/lists/k3f9dlq7), idLess: true makes it the slug alone, and the token's length and alphabet are settings — per application or per model. A length that runs out of tokens widens by a character instead of failing, so a short one is a real choice. Need the shortest URL there is? A counted scheme hands out 0, 1, … z, then 00.
  • ♻️ Self-healing URLs. Rename freely. A stale slug on a GET/HEAD request is 301-redirected to the current canonical URL automatically — no redirect tables to hand-maintain, no dead links, no lost link equity.
  • 🌍 Multilingual with hreflang out of the box. One slug per locale, and a reciprocal hreflang set (plus x-default) generated from the same resolver that builds your canonical URL — so they can never drift apart.
  • 🧩 Polymorphic routing. Serve every content type — pages, articles, products — through a single {type}/{polyslug} route and one registry.
  • 🧭 Stable resolution. Route-model binding decodes the identity, not the slug, so a mistyped or outdated slug still finds the right model (then redirects). An unknown or malformed token is a clean 404 — never a fuzzy match.
  • 🏢 Scoped uniqueness. Uniqueness can be scoped per tenant, per locale, per category — whatever columns you name.
  • 🗂️ History, events & immutability. Superseded slugs are kept so old URLs keep resolving; a SlugChanged event fires on every change; slugs can be frozen.
  • 🤝 Writes its own <head> via laravel/head. Install Laravel's <head> package and Head::polyslug($model) fills in the canonical URL, the hreflang set, the Open Graph locales and a robots directive for models your visibility gate hides. Optional — Polyslug requires nothing beyond slim illuminate/* components either way.
  • ✅ Proven on the databases you deploy to. The one-current-slug guarantee ships as a functional partial unique index on PostgreSQL and SQLite and as generated key columns on MySQL — two genuinely different mechanisms, and the suite proves both against real PostgreSQL 18 and MySQL 8.4 servers rather than inferring one from the other.

Documentation

Full docs at docs.pushery.com/polyslug-for-laravel.

  • Installation — requirements, the migration, publishing
  • Quick start — a sluggable model and a self-healing route
  • Features — encoders, hreflang, nested paths, sitemaps, short links
  • laravel/head — canonical URL, hreflang and indexability in Laravel's <head> package
  • Recipes — twelve app shapes wired end to end
  • Reference — every config key, option, command, event and contract

Requirements

  • PHP 8.4+
  • Laravel 13+ — 13.17+ only for the optional laravel/head integration, which is that package's own floor, not Polyslug's
  • PostgreSQL 18+, MySQL 8.4+, or SQLite — the uniqueness guarantees are enforced natively on each, and the full suite runs against all three. So Polyslug works on Laravel Cloud (serverless Postgres + MySQL 8.4 LTS) with no extra configuration.

Security

Please review the security policy and report vulnerabilities privately rather than opening a public issue.

Built by Pushery

This package is built and maintained by Pushery — a Berlin-based studio building Laravel applications, SaaS products, and open-source tools.

Building a Laravel UI? WireKit, Pushery's open-source Livewire component kit, gives you a polished component library out of the box. Browse the rest of our work at pushery.com.

License

The MIT License (MIT). See LICENSE for details.