Filament Redirects Laravel Package

Getting Started

1. Require the package with Composer, then publish its config and migrations:

   composer require <vendor>/<package>
   php artisan vendor:publish --provider="<Vendor>\\<Package>\\<Package>ServiceProvider"
   php artisan migrate
   

2. Look first at:
   • the published config file for middleware, route prefix, model, and matching options
   • the redirect model/migration to understand stored source, destination, and match type fields
   • the registered admin/list routes or dashboard entry point
   • the middleware/service that resolves incoming requests into redirects
3. Register or verify the redirect middleware in the HTTP stack if the package does not auto-register it.
4. Create your first redirect from the admin form: map an old exact path such as /old-page to /new-page.
5. First real use case: migrate legacy URLs. Use an exact redirect for one-off moves, then use a “match” redirect for families of URLs:

   Source: /blog/{slug}
   Destination: /articles/{slug}
   

   As of v2.4.0, captured groups from match redirects are filled into the destination, so /blog/hello-world resolves to /articles/hello-world.

Implementation Patterns

• Admin-first workflow: Use the redirect list/form for content editors and one-off migrations. The v2.4.0 readability improvements make the list and form better for day-to-day review, but treat the UI as a thin layer over the same model/service API.
• Programmatic redirects: For deploy-time or generated redirects, create records through the package model or service rather than writing directly to the table. This keeps validation and match-type handling consistent.
• Match redirects with captures: Use match redirects for patterned URLs and rely on captured groups in the destination. Keep source patterns narrow enough to avoid overlapping with exact redirects or other match redirects.
• Ordering and priority: Define a clear precedence rule: exact redirects before match redirects, then more specific match patterns before broader ones. If the package exposes ordering, use it; otherwise encode specificity in the source patterns.
• Seeding and deployment: Put permanent redirects in seeders or a data migration so staging and production stay aligned. Keep temporary campaign redirects in the admin UI.
• Testing: Cover redirect resolution with HTTP tests: request the old path, assert the expected status and Location header. Include at least one match redirect test with a captured group to verify destination substitution.
• Integration tips: Place the redirect middleware after session/start and before routes that should not receive legacy traffic. If using route caching or config caching, clear caches after changing redirect configuration.

Gotchas and Tips

• Capture syntax must match the package: Confirm whether match redirects use {slug}, :slug, regex groups, or another placeholder format. The v2.4.0 substitution feature only works when the source capture and destination placeholder align.
• Destination escaping: Captured values inserted into destinations should be treated as path/query data, not raw URLs. Avoid patterns or destinations that allow open redirects or unexpected host changes.
• Trailing slashes and query strings: Decide whether /old and /old/ are distinct, and whether query strings are preserved. Test both before bulk-importing redirects.
• Redirect loops: A redirect from /a to /b plus /b to /a will loop. Add a smoke test or periodic audit for chains and cycles.
• Duplicate sources: Exact duplicate source paths should be prevented or resolved deterministically. For match redirects, overlapping patterns are the usual source of “wrong redirect won” bugs.
• Caching: Cached routes, config, and redirect lookups can hide newly created redirects. Clear relevant caches when debugging and after deployments.
• Middleware position: If another middleware returns a response first, the redirect middleware may never run. Verify placement in the HTTP kernel or route group.
• 404 vs redirect: A redirect package should not mask genuine 404s. Keep fallback behavior explicit and test unmatched paths.
• UI readability is not validation: The v2.4.0 list/form improvements help humans scan records, but still validate source/destination values and match type programmatically.
• Extension points: Prefer the package’s model, service, events, or config over patching vendor files. If you need custom matching, wrap or extend the resolver rather than duplicating redirect logic in controllers.