Oc Redirect Plugin Laravel Package

Getting Started

This release (4.2.0) is the first to target October CMS 4.2 + Vue 3 for its backend UI. Before anything else, confirm your platform version — the plugin's admin screens are compiled Vue assets, so running it against an older October build will give you a blank or broken Redirects page rather than a graceful error.

Minimal install path:

composer require vdlp/oc-redirect-plugin
php artisan october:migrate

In a dev environment you can also php artisan plugin:refresh Vdlp.Redirect to rebuild tables from scratch. Once installed, the entry point is the Redirects item in the backend main menu — that's where all day-to-day work happens, and it's the first place to look when a redirect "isn't working", before you reach for code.

First use case, the one that justifies the plugin's existence: a content editor renames /pricing to /plans and you need the old URL to keep working without a deploy. Create the redirect in the backend (From: pricing, To: plans, Type: 301), then verify from the CLI:

curl -I https://example.test/pricing
# HTTP/2 301, location: https://example.test/plans

Two things to internalise early:

• Redirects are matched on the path (relative to the site root), not the full URL. Leave the scheme/host off.
• The plugin only sees requests that reach October's router. Static files served directly by nginx/Apache, and 404s handled by the web server, are invisible to it.

Implementation Patterns

Backend-first, code-second. The healthy pattern with this plugin is that redirects are data, managed by marketers, and your code never hardcodes them. Resist the temptation to sprinkle Redirect::create() calls in a service provider; you'll end up with duplicate rows and no audit trail.

Seeding for reproducible environments. For staging/CI you do want programmatic creation, but scope it to a one-off seeder or a migration rather than boot-time logic. The model is a standard Eloquent model, so Vdlp\Redirect\Models\Redirect::create([...]) works — but note the plugin caches the redirect map, so after bulk inserts you must clear the cache (php artisan cache:clear) or nothing takes effect.

404-log-driven workflow. The strongest day-to-day pattern: enable 404 logging, let it accumulate for a week, then triage the list in the backend and promote real misses into redirects in one click. This turns redirect maintenance from reactive firefighting into a scheduled chore. Pair it with a cron that prunes old log rows so the table doesn't bloat.

Bulk import over hand-entry. When migrating a legacy site (hundreds of URLs), use the import feature with a CSV/plain list of from,to pairs, then spot-check ordering. Bulk import is the integration seam most teams use to bring in rules from an old .htaccess or a SEO audit spreadsheet.

Layering with your own routes. Keep application routes in routes.php and let the plugin handle legacy/inbound URLs. If you need a redirect that depends on business logic (e.g. feature flag, user role), do it in a middleware before the plugin's own middleware runs — the plugin's rules are unconditional by design.

Multi-site awareness. If you run October's multisite feature, decide early whether a rule is global or site-scoped; retrofitting scoping across hundreds of existing rows is painful. Test each rule against every site host, not just the primary.

Verification pattern. Treat redirects as testable behaviour: an integration test that hits the old path and asserts assertRedirect($newUrl, 301) catches the classic regressions (typo in to, wrong status code, rule shadowed by a broader wildcard).

Gotchas and Tips

• This is an October CMS plugin, not a vanilla Laravel package. It depends on the October backend (controllers, list widgets, Vue assets, October\Rain\Database\Model). You cannot composer require it into a plain Laravel app and expect anything to work. If you're a Laravel dev inheriting an October site, budget time to learn the plugin registration/Plugin.php model before debugging anything.
• Vue 3 asset caching after the 4.2 upgrade. Because the backend UI was rewritten, browsers and October's compiled-asset cache can serve stale JS after composer update. If the Redirects page misbehaves post-upgrade, run php artisan october:util compile assets (or clear the backend asset cache) and hard-refresh before filing a bug.
• Version pinning. 4.2.0 raises the platform floor to October 4.2. Pin "vdlp/oc-redirect-plugin": "^4.2" and ensure your october/* constraints match, otherwise Composer may resolve a combination that installs cleanly but renders a broken admin page.
• Ordering is the #1 source of "broken" redirects. Matching is first-hit-wins. A wildcard like blog/* placed above blog/old-post will swallow the specific rule. Keep specific rules above general ones; re-check order after every bulk import, since imports append.
• Trailing slashes and query strings. /pricing and /pricing/ may not be treated as the same source path, and the query string is generally not part of the match. Decide on a canonical form and be consistent, or handle trailing-slash normalisation at the web-server layer.
• Hit counters write on every request. Convenient for reporting, but on high-traffic sites it means a database write per redirect hit. If you see write contention, disable hit tracking for the noisy rules or move counting to a queued/analytics layer.
• Cache invalidation is manual for out-of-band changes. Edits through the backend invalidate the redirect cache automatically; direct SQL, seeders, or imports executed outside the UI may not. Always clear the cache after touching the table by other means.
• Redirect loops and chains. The plugin does not detect a → b → a. When retiring a URL, grep for rules that already target it. Chains (a → b, later b → c) work but cost a round trip per hop — flatten them periodically.
• 404 log growth. Unbounded if you never prune; it's the table that eventually makes the backend list slow. Schedule deletion of rows older than N days.
• Extension points. For custom behaviour, hook the Eloquent events on the redirect model (saved/deleted) to push changes into your own cache or CDN purge, and use the backend list's column/field extension hooks to surface extra metadata rather than forking the plugin. Prefer events over overriding classes — a Vue 3-era rewrite is exactly the kind of release that breaks class overrides.
• Don't fight the web server. Canonical-host, www/non-www, HTTP→HTTPS and trailing-slash rules belong in nginx/Apache config. Doing them in PHP adds a full framework boot to every misdirected request.