Must-Have Redirect Documentation

Current Version: 0.1.2
Text Domain: mhredirect

Must‑Have Redirect detects 404 requests, then either applies your manual rules or finds the most relevant content using similarity matching. It prevents loops, records rule hits, and can serve a custom 404 page when no good target exists.

How it works

Getting Started

Choose the right plan

Must-Have Redirect is an intelligent 404 handling and URL redirection plugin. There are 2 available plans:

Single plan

You can use Must-Have Redirect with Single plan for 1 WordPress site. It's perfect if you have a single site or want to test the plugin's capabilities.

Unlimited plan

We created the Unlimited plan for freelancers and agencies who manage more than 3 sites. This plan can be used on unlimited sites, perfect for managing redirects across multiple WordPress installations.

Install Must-Have Redirect

1. Login to My account on musthaveplugins.com
2. On the next screen you will see all available plugins. Download Must-Have Redirect installer from the Must-Have Redirect box
3. Login to WordPress admin where you would like to install Must-Have Redirect
4. Go to Plugins > Add new and click to upload plugin
5. Select the previously downloaded ZIP file (must-have-redirect.zip) and click to install

Configuration

Configure the basic functionality of the plugin in this section.

Smart 404 Handling

When enabled, the plugin automatically tries to find and redirect to the most relevant content when a 404 error occurs. This feature uses intelligent similarity matching to find the best possible destination.

Similarity Threshold

Choose how strict the plugin should be when matching similar content:

• Close Match (10% difference): Only redirects to very similar URLs, best for catching minor typos
• Likely Relevant (25% difference): Balanced approach, catches moderate URL variations
• Fallback (50% difference): Most lenient, tries to avoid 404s by finding any potentially relevant content

Custom 404 Page

Select any WordPress page to serve as your custom 404 page. This page will be displayed when:

• No matching redirect rule is found
• No similar content is found
• The found destination would create a redirect loop

Redirect Rules

Manage your redirect rules and view automatically generated redirects.

Manual Redirects

Create redirect rules with these options:

• Pattern: The URL pattern to match (supports * wildcards). Each pattern must be unique.
• Destination: Where to redirect matching URLs.
• Status: HTTP status code (301 Permanent, 302 Temporary, 307 Temporary (Strict), 308 Permanent (Strict)).

Smart 404 matches create auto rules with status 302. You can later edit them into permanent rules.

Wildcard Patterns

Use * as a wildcard in your patterns. Internally, each pattern is translated to a case-insensitive regex with anchors (^...$) where * becomes .*. Examples:

• old-product/* → Matches all URLs starting with "old-product/"
• *.html → Matches all URLs ending with ".html"

URL Handling

Learn how the plugin processes and normalizes URLs.

URL Normalization

The plugin automatically normalizes URLs for consistent matching:

• Removes trailing slashes
• Removes tracking parameters (utm_*, fbclid, etc.)
• Sorts remaining query parameters alphabetically

Ignored Query Parameters

These query parameters are automatically removed by default:

• utm_source, utm_campaign, utm_medium, utm_expid, utm_term, utm_content
• fb_action_ids, fb_action_types, fb_source, fbclid
• _ga, _gl, gclid
• age-verified, rdt_cid, li_fat_id

Bot Protection

The plugin automatically detects and skips processing for:

• Empty or suspicious user agents (eg. curl, wget, python-requests, libwww-perl, java, scrapy, okhttp, go-http, jakarta, aiohttp)
• Malicious URL patterns and direct file access attempts (eg. wp-admin, wp-json, cgi-bin, shell, passwd)
• Direct requests to common file types (eg. .php, .sql, .gz, .zip, images, fonts, audio/video, css, js, xml, pdf, txt)

Best Practices

• Start with "Close Match" similarity and adjust based on your needs
• Review auto-generated redirects periodically
• Use wildcards carefully to avoid unintended matches
• Monitor hit counters to identify frequently used redirects
• Consider creating permanent (301) redirects for commonly used patterns

Available Filters

Customize the plugin's behavior using these filters:

// Modify the normalized path
add_filter('mhredirect/current_path', function($path) {
      // Your modifications here
      return $path;
});

// Customize which query parameters to remove
add_filter('mhredirect/remove_query_params', function($params) {
      $params[] = 'my_tracking_param';
      return $params;
});
                        

add_filter('mhredirect/similarity_threshold', function($threshold, $w1, $w2) {
  // e.g. make brand words stricter
  if ($w1 === 'brand' || $w2 === 'brand') return max(1, $threshold - 1);
  return $threshold;
}, 10, 3);

Available Actions

Changelog