Download the PHP package justbetter/statamic-detour without Composer

Statamic Detour

This Statamic addon provides a flexible redirect management system for your Statamic projects.

Requirements

• PHP ^8.3
• Laravel ^12.40|^13.0
• Statamic ^6.3

Features

• Performance Mode: Ensure redirects are only checked after Statamic determines a route doesn't exist (prevents slowing down valid hits)
• Multi-Site/Locale Support: Redirects can be global or scoped to a specific site handle
• Storage Driver: Option to store redirects in flat files (YAML) for version control OR Database for performance on massive sites
• Path & Regex Support: Create redirects using simple paths or powerful regex patterns
• Multiple Redirect Codes: Support for 301, 302, 307, and 308 redirect codes
• Query String Handling: Pass through, strip completely, or strip specific keys (for example gclid)
• Control Panel Interface: Manage redirects directly from the Statamic Control Panel

Installation

You can install this addon via Composer:

Configuration

You can publish the config by running:

You can now find the config file at config/statamic-detour.php.

Storage Driver

The package supports two storage drivers:

File Driver (Default)

Store redirects as YAML files in your content directory. This is ideal for version control and smaller sites.

Or set via environment variable:

Eloquent Driver

Store redirects in the database. This is recommended for larger sites with many redirects for better performance.

Or set via environment variable:

When using the Eloquent driver, run the migrations:

Performance Mode

The package supports two modes for checking redirects:

Basic Mode (Default)

Redirects are checked early in the request lifecycle, before Statamic's routing.

Or set via environment variable:

Performance Mode

Redirects are only checked after Statamic determines a route doesn't exist. This prevents slowing down valid route hits.

Or set via environment variable:

Auto create

Redirects are automatically created whenever an entry's slug is changed. If you change the slug of a parent, this change will also be reflected in its children.

Or set via environment variable:

Query string defaults

Set global defaults for query string handling:

You can also configure these from Tools > Detours > Settings in the Control Panel.

Usage

Creating Redirects

Navigate to Tools > Detours in the Statamic Control Panel to manage your redirects.

Path Redirects

Create simple path-based redirects:

• From: /old-page
• To: /new-page
• Type: Path
• Code: 301 (or 302, 307, 308)
• Sites: Leave empty for global, or select specific sites
• Query string handling: Use global default, pass through, strip completely, or strip specific keys

Regex Redirects

Create powerful pattern-based redirects:

• From: /blog/(\d{4})/(\d{2})/(.*)
• To: /articles/$1/$2/$3
• Type: Regex
• Code: 301
• Sites: Select specific sites if needed
• Query string handling: Same options as path redirects

Multi-Site Support

When creating a redirect, you can:

• Leave Sites empty: The redirect will apply globally to all sites
• Select specific sites: The redirect will only apply to the selected site handles

This allows you to manage redirects per site in a multi-site Statamic installation.

Storage Considerations

File Driver

• Redirects are stored as YAML files in content/detours/
• Each redirect is a separate file
• Perfect for version control
• Best for smaller sites (< 100 redirects)

Eloquent Driver

• Redirects are stored in the detours database table
• Better performance for large numbers of redirects
• Recommended for sites with 100+ redirects
• Supports faster lookups and queries

Development

When developing this addon, you'll need to build the Control Panel assets. Node.js 22+ is required for the build process:

For hot reloading during development, run npm run dev in a separate terminal.

Quality

To ensure the quality of this package, run the following command:

This will execute three tasks:

1. Makes sure all tests are passed
2. Checks for any issues using static code analysis
3. Checks if the code is correctly formatted

Credits

• Bob Wezelman
• Niek Boon
• Kevin Meijer
• All Contributors

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

License

The MIT License (MIT). Please see License File for more information.