Statamic Simple Redirects Laravel Package

Getting Started

This is a small, single-purpose Statamic addon (3 stars, near-zero dependents), so treat the README and the source as the spec — there is no ecosystem of blog posts or Stack Overflow answers to fall back on. Budget 15 minutes to read the src/ directory before wiring anything into production.

Minimal path:

1. Install: composer require ndx/statamic-simple-redirects. Because the package is low-traffic, pin the version in composer.json (e.g. ^1.0) rather than floating on dev-main — you do not want an unreviewed commit silently changing redirect behavior on a live site.
2. Publish assets: run php artisan vendor:publish --provider="Ndx\SimpleRedirects\ServiceProvider" (confirm the exact provider name and tags in the README). This typically publishes a config file and possibly a YAML content file or migration, depending on whether the package stores redirects in files or the database.
3. Locate the CP entry: after install, look for a "Redirects" item in the Statamic control panel nav. If it is not there, check the package's routes/ and resources/views/ to confirm whether the UI is CP-native or whether you're expected to edit a YAML file directly.
4. First use case: create a single 301 from an old URL to a new one in the CP, then hit the old URL in a browser and confirm a 301 with the correct Location header. This one test tells you whether the middleware is registered, whether caching is interfering, and whether the storage layer is writable.

Where to look first, in order: the published config (enable/disable switch, storage path), the middleware class (how requests are matched), then the CP controller (what fields are actually editable). That trio defines 90% of the package's behavior.

Implementation Patterns

CP-driven redirect management for content moves. The primary workflow is editorial: a content editor renames a page slug, and instead of a developer writing a route, they add a redirect in the CP. Establish this as the default process and keep the redirect list small enough to review — a sprawling unreviewed list is how redirect loops happen.

Bulk seeding via the storage file. If redirects are file-backed YAML, the fastest migration path is to generate that file from an existing .htaccess/nginx redirect table with a one-off Artisan command or php artisan tinker script, then commit it. This gives you versioned, reviewable redirect history — a real advantage over a database table. If the storage is database-backed, seed via a migration instead and keep the seeder idempotent.

Environment gating. Redirects are usually only meaningful in production and staging. Wrap the middleware or the config toggle in an environment check so local development returns 404s for old URLs instead of bouncing you to production pages you can't edit. This is the single highest-value config change you'll make.

Layering with Statamic's own routing. Order matters: this middleware should run after session/auth middleware (so it doesn't hijack auth redirects) but before Statamic's content resolution. In practice, register it in the web group and verify ordering with php artisan route:list -v. If the package ships its own middleware registration, confirm it doesn't get preempted by a catch-all route or a custom Route::fallback().

Complement, don't duplicate, 404 handling. Use this package for known, intentional moves (301/302), and use your 404 template plus analytics for discovering broken inbound links. Periodically reconcile: pull top 404s from logs, then add redirects. That feedback loop is where the package earns its keep.

Pair with static caching carefully. If you use Statamic's static caching or a full-page CDN, a new redirect added in the CP will not take effect on already-cached URLs until you clear. Build "add redirect → clear static cache" into your editorial checklist, or hook the package's save event to invalidate the relevant cache key.

Gotchas and Tips

• Middleware registration is the #1 failure mode. Redirects added in the CP that "don't work" almost always mean the middleware isn't registered or is ordered wrongly. Debug with php artisan route:list -v | grep -i redirect and by temporarily dd()-ing at the top of the middleware's handler.
• Trailing slashes, query strings, and case. Most lightweight redirect packages match on a normalized path and may or may not preserve query strings. Test /old-path?utm=x, /Old-Path, and /old-path/ explicitly — the package's matching semantics are not documented in a spec, so verify empirically.
• Redirect loops are silent and painful. Before saving a redirect, check whether the target itself matches an existing rule or a live route. Keep a "last reviewed" date on the list and prune aggressively; a redirect pointing at a deleted page is worse than a 404.
• Caching layers. Laravel config cache (php artisan config:cache), Statamic's Stache, static caching, and any CDN all sit between you and the change. When a redirect "doesn't stick," clear in this order: config → Stache (php artisan statamic:stache:clear) → static cache → CDN.
• Multi-site. If your Statamic install is multi-site, verify whether the package scopes redirects per site or globally. A global-only implementation will send Spanish-site visitors to English URLs; if unsupported, fork and add a site column/field rather than fighting it.
• Storage permissions. File-backed redirects need the storage directory writable by the web user. Permission denied on save in the CP is a common first-day error on hardened servers.
• Low-maintenance risk. With 3 stars and 0 dependents, the last release date is your friend but the bus factor is 1. Pin the version, keep a fork in mind, and prefer the package's storage layer over its UI if you need durability — you can always read a YAML file yourself.
• Extension points to check for in src/: whether the middleware dispatches an event on match (useful for logging/analytics), whether the redirect resolver is bound in the container (swappable for pattern-matching or regex support), and whether the config exposes a custom storage path. Any of these lets you extend without forking; if none exist, a subclassed middleware is the cheapest escape hatch.
• Don't install this to solve auth or HTTPS redirects. It's for content-path redirects. Force-HTTPS and www canonicalization belong in web-server config or a dedicated middleware, where they run before Laravel boots.