Overview

What it does for you

URL Manager keeps your links working. When a page moves or a URL changes, you send the old address to the new one with a redirect, so visitors and search engines always land in the right place. You can fix one link at a time or import many at once.

Your screens

• Redirects: the list of redirects you have set up, including their match mode, status code, scope, priority, and active state.
• 404 opportunities: pages visitors couldn’t find, ready to redirect.
• Import: the tool for adding many redirects from a spreadsheet.

What you can do

• Create an exact, prefix, or advanced regular-expression redirect from an old URL to a new one.
• Fix a link that moved.
• Preview and import many redirects from a CSV spreadsheet.
• Turn a 404 into a redirect.
• Mark a URL as permanently gone when it has no replacement.
• Export your redirects.

Where to find it

Go to URL Manager in the admin to manage redirects and review 404s.

Access and data visibility

• View:RedirectRulesPage opens the redirect list and allows CSV export and template download. Manage:RedirectRules also opens the page and permits create, edit, import, activate, disable, and delete actions.
• View:NotFoundOpportunitiesPage opens the 404 list. Manage:NotFoundOpportunities permits conversion, ignore, and reopen actions. Converting an opportunity creates a redirect even if the operator does not also have Manage:RedirectRules, so grant this permission only to people trusted to change public routing.
• Neither table applies an operator site scope: both query installation-wide records, including global rules and records assigned to every site and language. The redirect export is installation-wide too. Do not grant either view permission to a site-limited operator who must not see other sites’ paths.

Build and test a rule

1. Choose the narrowest match type and, where needed, its site and language scope.
2. Choose the status code and target. Absolute targets are limited to the application’s host and any developer-configured allowlist; a disallowed external host is rejected again after regex substitution at request time.
3. Decide whether to Preserve query. This is enabled by default and appends the request’s original query string when the target has no query of its own. Turn it off when old links may contain tokens, personal data, or tracking parameters that must not reach the destination.
4. Test the old URL on the intended site and language, including a representative query string. Then check the rule’s hit count and last-hit time.

Exact and prefix sources are normalised to a lowercase path without a trailing slash or query string. Regex rules also run against that normalised path, not the raw URL. This means case-only or query-only variants share a rule.

Import safely

1. Download the template or export the current rules. Use true or false for preserve_query, and keep the supplied column names.
2. Upload a CSV of at most 2 MB or paste its contents, then run Preview import.
3. Correct every reported row. The admin does not start the import while preview validation finds an invalid row.
4. Re-upload or paste the corrected CSV for Import redirects. Uploaded files are bound to the current operator session, consumed once, and deleted after preview or import.
5. Check the imported and skipped counts, then export the rules again for a recovery record.

The admin guide provides a concrete three-row CSV containing a permanent exact redirect, a permanent prefix redirect, and a 410 Gone rule. The 410 row deliberately leaves target_url empty because the retired campaign has no replacement.

Matching source, site, language, and match-type values update the existing rule rather than creating a duplicate. The reviewed import plan is verified again when it is applied, and all valid rows are written in one database transaction. If validation becomes stale or any write fails, none of that plan is applied.

404 capture and retention

Frontend 404 responses are grouped by normalised path unless capture is disabled. Admin, Livewire, debug, clockwork, and storage path prefixes are ignored by default. A managed 410 response is served before 404 capture, so it records a redirect hit rather than creating a 404 opportunity.

Redirect hit rows retain the normalised request path and referring URL in plaintext; IP address and user-agent values are stored as SHA-256 hashes. A 404 opportunity stores its path and context, including the referring URL, in plaintext. Query strings are removed from the managed source path, but a referrer can still contain one. Treat these records as browsing data and restrict database, backup, and admin access accordingly.

The maintenance command url-manager:prune-hits removes both old redirect-hit rows and old 404 opportunities. Their default retention windows are 365 and 180 days respectively; --days applies one override to both. Pruning hit rows does not reset the cumulative hit count or last-hit time shown on the redirect rule.

The package registers url-manager:prune-hits with Laravel’s runtime schedule to run daily without overlapping. Operations only need to keep Laravel’s scheduler running; no separate URL Manager cron entry is required.

Good to know

• Send an old URL to its new home with a redirect, so visitors don’t hit an error. Choose 301, 302, 307, or 308 to match whether the move is permanent or temporary; use 410 only when the URL is intentionally gone and has no target.
• Use Exact for one URL, Prefix when a path and its descendants moved together, and Regex only for an advanced, well-tested pattern. The manager rejects invalid patterns, self-redirects, and resolvable redirect loops.
• Scope a rule to a site or language when the same old path has a different destination elsewhere. A matching site/language rule takes precedence over a global rule; priority resolves remaining overlaps. Inactive rules stay stored but do not serve visitors.
• Use Preview import before importing a CSV. The admin import uses the same rule validation and does not start while any preview row is invalid.
• Page URL changes create a redirect automatically. When a parent path moves, the package can also create a prefix redirect for its children; review these generated rules after a structural move.
• Turn a 404 opportunity into a redirect to recover lost visitors, or mark it ignored when it does not need a route. Redirect hit counts help you review which rules are still used.
• Redirect-hit writes happen after the response by default. If operations enable queued hit recording, a working queue worker becomes required for hit rows and counters to update.

---

For how to use URL Manager, see the admin guide. For developers: see the README.