Pantry Redirects

301 and 302 redirects with a 404 log.

A redirect list you can read at a glance and a 404 log that shows what to fix. Add exact-path redirects, see how often they fire, and turn a logged 404 into a redirect. Import and export as CSV.

Built to the Pantry Standard.

Where it lives

Plugin Pantry > Redirects. One screen with three tabs:

• Redirects - the add or edit form, the redirect list, and CSV import and export.
• 404 log - paths that returned a 404, with a clear button.
• Settings - matching and logging options.

Everything needs the manage_options capability.

Adding a redirect

1. Source path is a path on this site, starting with a slash: /old-page. A trailing slash and letter case are ignored, so /Old-Page/ and /old-page are the same redirect. A source may carry a query string (/product?id=12) when you want to redirect one exact address.
2. Target is either a path on this site (/new-page) or a full address somewhere else (https://example.com/new-page).
3. Type is 301 (permanent), 302 (found, temporary) or 307 (temporary).
4. Enabled turns the redirect on. A disabled redirect stays in the list and does nothing.

The form refuses a source that is empty or is the home page, a target that is neither a path nor an http or https address, a source that already has a redirect, a redirect that points at itself, and a redirect that would send a visitor round in a loop. Loop checking follows the chain of redirects on this site for up to ten hops.

Redirects are matched on template_redirect at priority 1, before WordPress decides the request is a 404, so a redirect wins over an existing page at the same path.

The 404 log

Every front-end request that ends in a 404 has its path written to the log with a hit count and the time it was last seen. Nothing else is stored: no IP address, no user agent, no referrer, no user id.

These are never logged:

• Admin, AJAX, cron, REST and WP-CLI requests.
• The home page.
• Anything starting with /wp-.
• Anything ending in a common asset ending (.css, .js, .png, .woff2 and so on).

Create redirect on a log row opens the Redirects tab with that path already in the source box. Fill in the target and save. Delete removes one row, and Clear the log empties it.

When the log passes the limit in Settings, the paths seen longest ago are dropped.

Settings

Setting	Default	What it does
Query strings	On	With this on, /old-page?utm_source=news matches a redirect whose source is /old-page. With it off, only a redirect whose source carries the same query string matches. A source with its own query string always wins over the bare path either way.
Default type	301	Pre-selected in the add form, and used for CSV rows that leave the type column out.
Logging	On	Turns 404 logging off without touching what is already logged.
Paths to keep	200	How many unique paths the log holds. Between 20 and 1000.

CSV

Export CSV downloads every redirect as source,target,type,enabled, newest id last.

Import CSV reads the same four columns. A header row is optional and is skipped when the first cell reads source. A row whose source already exists updates that redirect rather than adding a second one. The type column may be left empty, in which case the default type from Settings is used. The enabled column accepts 1, yes, true, on or enabled; anything else is off, and a missing column is on.

Rows that fail the same validation as the form are skipped and counted in the notice. The file must be under one megabyte and at most 5000 rows are read.

source,target,type,enabled
/old-page,/new-page,301,1
/brochure.html,https://example.com/brochure,302,1
/retired,/,301,0

Filters and actions

All seven are prefixed pantry_redirects_.

pantry_redirects_pre_match

Added in 1.1.0. Runs on template_redirect before the exact lookup, once the request path has been normalised. Return a rule row and the visitor is sent there without the exact list being read; return the value you were given and matching carries on as usual.

A rule row needs id, target and type. The id is the row whose hit count is raised, so a rule stored in this plugin's own table is counted like any other, and an id of 0 sends the redirect without counting it.

add_filter( 'pantry_redirects_pre_match', function ( $rule, $request ) {
	if ( null !== $rule || 0 !== strpos( $request, '/legacy/' ) ) {
		return $rule;
	}
	return (object) array(
		'id'     => 0,
		'source' => $request,
		'target' => '/archive' . $request,
		'type'   => 301,
	);
}, 10, 2 );

pantry_redirects_settings_after

Added in 1.1.0. Fires at the end of the Settings tab, after the settings form, with the settings screen object as its argument. An add-on can render its own section there. The form above it posts to options.php with this plugin's own settings group, so a section that has fields of its own brings its own form and its own group.

add_action( 'pantry_redirects_settings_after', function ( $settings ) {
	echo '<section class="pantry-section"><h2>My add-on</h2></section>';
} );

pantry_redirects_enabled

Turn redirect matching off for a request.

add_filter( 'pantry_redirects_enabled', function ( $enabled ) {
	return is_user_logged_in() ? false : $enabled;
} );

pantry_redirects_target

Change the address a matched rule sends the visitor to. Return an empty string to cancel the redirect.

add_filter( 'pantry_redirects_target', function ( $url, $rule, $request ) {
	return add_query_arg( 'from', rawurlencode( $request ), $url );
}, 10, 3 );

pantry_redirects_redirecting

Fires just before the header is sent, after the hit has been counted.

add_action( 'pantry_redirects_redirecting', function ( $rule, $url, $status ) {
	error_log( sprintf( '%d to %s', $status, $url ) );
}, 10, 3 );

pantry_redirects_should_log

Decide whether one path is written to the 404 log.

add_filter( 'pantry_redirects_should_log', function ( $should_log, $path ) {
	return 0 === strpos( $path, '/feed' ) ? false : $should_log;
}, 10, 2 );

pantry_redirects_asset_endings

Replace the list of file endings that are never logged.

add_filter( 'pantry_redirects_asset_endings', function ( $endings ) {
	$endings[] = 'pdf';
	return $endings;
} );

What it stores

Two options, pantry_redirects_settings and pantry_redirects_db_version, and two tables, {prefix}pantry_redirects_rules and {prefix}pantry_redirects_log. No post meta, no custom post types, no cron events, no transients, no external requests.

Uninstalling removes all four, on every site of a network.

The kind column

Since 1.1.0 the rules table has a kind column, varchar(20), defaulting to exact. This plugin only ever reads, lists, edits, exports, matches or deletes rows whose kind is exact, which is every row it writes. The column is there so an add-on can keep rules of another kind in the same table and have the hit count, the last-hit time and the 404 log work for them without a second table. A row of another kind is invisible here, with one exception: the source column is unique across the whole table, so the add form still refuses a source that another kind of rule has already taken.

The schema version is held in pantry_redirects_db_version and the column is added by dbDelta on the first admin request after an update.

Notes for the curious

• Matching costs one indexed SELECT on the rules table per front-end request, and a second one only when the request has a query string and the query string option is on. Nothing is cached, so a redirect works the moment it is saved.
• Plugin::boot() runs on plugins_loaded and hooks init at priority 5, where it builds the objects. The menu title and every field label are translatable, and WordPress 6.7 and newer log a notice when a text domain is used before init. Every hook this plugin needs fires after init, so nothing is lost by waiting.
• wp_http_validate_url() is deliberately not used to check targets. It resolves the host through DNS and refuses private addresses, which would break a redirect to a staging host and would count as an external request. Targets are checked structurally instead: a path must start with a slash, and an address must parse to an http or https scheme with a host.
• wp_redirect() is used rather than wp_safe_redirect() because a redirect to another site is a normal thing to want. The target is validated when it is saved by a user with manage_options.

Why this plugin is over the line limit

The Pantry Standard aims for under 1,500 lines of PHP per plugin and asks for a written reason above 2,000. This one measures 3,221 lines, counted with find plugins/pantry-redirects -name '*.php' -not -path '*/tests/*' | xargs cat | wc -l. The reason, in order of size:

• 742 lines are the vendored includes/core settings class, which is shared and not written here.
• 353 lines are the two WP_List_Table subclasses. The scope asks for a redirect list and a 404 log, and each list needs its own columns, sortable columns, row actions, bulk actions and empty-state text. There is no smaller way to get a native WordPress list.
• 518 lines are the admin write paths in one class: the add and edit handler, the row and bulk handlers, the CSV reader, the CSV writer, the validator, and the notice texts. The notice map alone is 70 lines because every outcome gets a sentence a person can act on rather than a code.
• 571 lines are the database layer. Ordering and paging are written out twice, once ascending and once descending, because the coding standard will not allow a direction to be concatenated into a prepared statement, and 1.1.0 added a kind-limited version of the rule reads and writes.
• The rest is path normalisation shared by the front end and the admin, the screen markup, and one docblock per method.

Nothing here is dead code or a feature outside the scope contract. If the limit has to be met, the honest cut is the 404 log, which would move the plugin back under 1,900 lines and remove half of what it is for.