Permalink Laravel Package

Getting Started

• Check Laravel compatibility before installing. The last release was 2020-12-17, so treat it as a Laravel 6/7/8-era package until proven otherwise. On Laravel 9+ plan to fork/patch or pin dependencies.
• Install and publish:

  composer require devio/permalink
  php artisan vendor:publish --provider="Devio\Permalink\PermalinkServiceProvider"
  php artisan migrate
  

• Inspect the published config and migration first. Look for the permalink table name, route registration behavior, middleware, locale support, and SEO columns. This tells you whether the package registers a catch-all route automatically or expects you to add one.
• Add a first database-driven permalink mapping a public slug to a named Laravel route:

  use Devio\Permalink\Permalink;
  
  Permalink::create([
      'slug' => 'about-us',
      'route' => 'pages.show',
      'parameters' => ['page' => 1],
      'title' => 'About Us',
      'description' => 'Company overview',
  ]);
  

• Visit /about-us and confirm resolution. If it 404s, inspect php artisan route:list, the package config, and whether the fallback/catch-all route is registered after your normal routes.
• Best first use case: CMS/marketing pages where editors manage slugs, redirects, and SEO metadata without deploys. Start with static pages and a single locale before adding model-bound permalinks or multi-language.

Implementation Patterns

• Seed known permalinks. Put marketing/static page URLs in seeders so local, staging, and production start from the same route map. Use route names, not hard-coded URLs.
• Attach permalinks to Eloquent models. Use the package's model trait/relation if available, or store model_type/model_id yourself and resolve the model in the controller. Generate slugs on create/update, but keep a manual override for editors.
• Build an admin CRUD. Validate slug, route, parameters, locale, canonical, robots, and redirect fields. Whitelist allowed route names and parameter keys rather than accepting arbitrary values.
• Use a single fallback route. Register the package resolver/catch-all at the bottom of routes/web.php so existing routes win. Exclude /admin, /api, auth, and asset paths via middleware or prefix checks.
• Render SEO from the permalink record. In your layout, read title, description, canonical, robots, and Open Graph fields from the resolved permalink. Fall back to model/default metadata when absent.
• Generate sitemaps from the database. Query active permalinks, map to absolute URLs, and include lastmod from the related model or permalink update time. Exclude redirects and noindex entries.
• Handle slug changes with redirects. Store old slugs or a redirect table. On slug update, create a 301 from the old path. Test trailing-slash and case variations explicitly.
• Cache resolution. A database lookup per request is the main cost. Cache slug + locale -> route/parameters and invalidate on save/delete. Cache 404s briefly to avoid repeated misses under bot traffic.
• Multi-language pattern. Store locale with each permalink, prefix routes or use localized domains, and make uniqueness (slug, locale). Keep a canonical/hreflang strategy in the rendering layer.
• Test as HTTP features. Use RefreshDatabase, seed permalinks, and assert status codes, redirects, canonical tags, and 404 behavior. Include tests with route caching enabled.

Gotchas and Tips

• Maintenance risk is the biggest gotcha. With 65 stars, zero dependents, and no release since 2020, expect outdated Laravel constraints and unmaintained internals. Fork it, add CI, and pin versions before relying on it.
• Route caching can break DB-driven routes. If the package registers routes dynamically from the database during boot, php artisan route:cache may freeze or omit them. Test route:cache/route:clear in CI and document the deploy sequence.
• Catch-all routes swallow everything. A permissive fallback can intercept /admin, /api, or missing assets. Keep it last and constrain it by prefix, middleware, or explicit exclusions.
• Enforce slug uniqueness in the database. Application validation is not enough under concurrency. Add a unique index on (slug, locale) and decide how soft deletes interact with reuse.
• Validate route names and parameters before saving. A typo in a route name or a stale model ID creates a permalink that resolves but crashes. Resolve/validate against Route::has() and expected parameter keys.
• Treat stored parameters as untrusted. Do not let editors freely inject route names, model classes, or parameter arrays. Whitelist and cast values.
• Watch performance. Resolving a permalink and then loading its model can become an N+1. Eager-load relations in the controller and cache the resolved route payload.
• Debug with route list and SQL. For 404s, check php artisan route:list, service-provider boot order, middleware groups, and the actual query by slug/locale. For 500s, dump the resolved route/parameters before dispatch.
• Extension points to prefer. Custom resolver/controller, a model trait for slug generation, config overrides for table/route behavior, and model events for cache invalidation. Avoid editing vendor files; wrap or fork instead.
• Migration/table conflicts. The table name may be generic (permalinks). Check existing schemas before migrating and confirm the package migrations are safe to rerun in your deployment pipeline.