URL Manager Overview
URL Manager is Capell’s package-owned redirect and broken-link remediation layer. It stores redirect rules, records lightweight hit evidence, captures repeated 404 opportunities, imports SEO Suite broken-link rows, and exposes admin pages for editors to review and convert redirect candidates.
Runtime Flow
Section titled “Runtime Flow”UrlManagerRedirectResolver decorates Core’s RedirectResolver contract. Core decisions win first; if Core has no redirect decision and the current PageUrl is not a real page, URL Manager resolves active exact, prefix, and regex rules for the current site and language. Exact rules match by a normalized path hash. Prefix rules use bounded candidate paths and priority ordering. Regex rules are validated at write time, ordered by priority, and capped by capell-url-manager.redirects.regex.max_rules_checked.
Hit recording is deferred by default. The redirect response can return immediately, then the application terminating callback writes url_manager_redirect_hits and updates the rule counter. Set capell-url-manager.hit_recording.defer to false only for diagnostics or tests that need synchronous writes.
Redirect Safety
Section titled “Redirect Safety”Source URLs are lowercased and stripped of query strings before matching. Query strings are only reattached by UrlManagerRedirectResolver when preserve_query is enabled and the target URL has no query string of its own.
Absolute targets are constrained to configured hosts plus the app.url host by default. Configure extra hosts through capell-url-manager.redirects.absolute_target_allowed_hosts. Exact redirect chains are collapsed to their final active target when a rule is saved, and loops or cycles are rejected before persistence. Regex sources are bounded by maximum pattern length and validated before a rule is saved.
Changed URLs And 404 Capture
Section titled “Changed URLs And 404 Capture”RecordRedirectForChangedPageUrl listens for Core PageUrlChanged events. It creates an exact redirect for the changed path and, for parent moves, a prefix redirect so child URLs continue to resolve.
RecordNotFoundOpportunityMiddleware registers with Capell Frontend’s middleware registry and records public 404 responses as NotFoundOpportunity rows. Ignored path prefixes, such as admin and Livewire paths, live in capell-url-manager.not_found.ignored_path_prefixes.
Package tests cover the installed-provider wiring for both UrlManagerRedirectResolver and the frontend 404 capture middleware, so these capabilities are verified at the package boundary rather than only by action-level tests.
Canonical URLs
Section titled “Canonical URLs”BuildCanonicalUrlAction provides the package canonical URL policy. It can force a scheme or host, lowercase paths, add or remove trailing slashes, and strip configured tracking query parameters. The action does not render tags by itself; consumers can call it when they need URL Manager’s canonical policy.
Admin And CSV
Section titled “Admin And CSV”The Redirect Rules admin table supports create, edit, enable, disable, delete, bulk lifecycle actions, CSV import/export, and template download. CSV rows include priority so migration exports preserve overlap ordering. The 404 Opportunities page lets editors ignore, reopen, or convert opportunities into redirect rules.
Retention
Section titled “Retention”PruneRedirectHitsAction deletes old per-hit evidence according to capell-url-manager.hit_recording.retention_days. Operators can run url-manager:prune-hits or pass --days= for a one-off retention window.