Alynt Redirects Manager

Developer-focused WordPress redirect management for agency-managed sites.

This plugin is intentionally private, narrow, and operational. It is designed to replace scattered child-theme redirect logic and third-party redirect plugins with one predictable redirect engine.

Requirements

• WordPress 6.0 or newer
• PHP 7.4 or newer
• Composer dependencies installed for local development and tests
• Node dependencies installed when rebuilding assets

Installation

1. Place the plugin directory in wp-content/plugins/alynt-redirects-manager.
2. Run composer install and npm install in development copies.
3. Run npm run build before packaging or deploying changed assets.
4. Activate Alynt Redirects Manager in WordPress.

Current Build

Version 0.1.0 is the foundation slice:

• plugin bootstrap and PSR-4-style loader
• activation/deactivation/uninstall handlers
• custom database schema for redirects, domain mapping, and internal events
• redirect, domain map, and event repositories
• admin CRUD for exact, section/path wildcard, and WordPress object redirects
• single-domain mapping admin support with exclusions and test output
• CSV and JSON export for redirect rows
• CSV and pasted-text import preview and apply for valid redirect rows
• default WordPress-sensitive exclusions for new domain maps
• path/domain/URL normalization
• redirect and domain-map validation
• redirect warnings for stripped query strings, likely chains, stored-rule overlaps, and object references that need review
• admin field-level validation messages, live normalized previews, object search helpers, duplicate-row drafts, and warning confirmation before active saves
• deterministic matcher for exact, object, section, and domain-map redirects
• runtime executor hook
• Tools > Redirects admin screens
• WP-CLI redirect/domain-map test commands plus redirect list, export, import, enable, disable, delete, and domain-map show commands
• build/lint/test configuration

Basic Usage

Manage redirects from Tools > Redirects.

• Add exact path redirects for one source path.
• Add section redirects with a trailing wildcard, such as /old-section/*.
• Add object redirects by searching for a post, page, or public taxonomy term.
• Use the test action to verify the matched destination before enabling risky rules.
• Use duplicate row actions to create inactive drafts from existing rules.
• Use the import screen to preview CSV exports or pasted redirect lines before applying valid rows.
• Use Diagnostics to enable scoped, redacted operational events when troubleshooting import, export, database write, AJAX search, destructive action, schema upgrade, or blocked external redirect issues.

WP-CLI

Test runtime matching from the command line:

wp alynt-redirect test /old-page/
wp alynt-redirect test /old-page/ --format=summary
wp alynt-redirect test https://old.example.test/path/ --host=old.example.test --format=table
wp alynt-redirect domain-map test https://old.example.test/path/

Manage redirect rows from the command line:

wp alynt-redirect list --status=active --format=table
wp alynt-redirect export redirects.csv --format=csv
wp alynt-redirect export redirects.json --format=json
wp alynt-redirect import redirects.csv --format=summary
wp alynt-redirect import redirects.csv --apply --format=table
wp alynt-redirect enable 123
wp alynt-redirect disable 123
wp alynt-redirect delete 123 --yes
wp alynt-redirect domain-map show --format=summary

CLI import previews validate the export-format CSV before writing anything. Passing --apply imports only valid rows through the same revalidation path used by the admin importer.

The legacy agency-redirect alias is also registered for compatibility. Test commands exit non-zero when no redirect matches or when input is invalid. Import commands exit non-zero when preview-level errors, invalid rows, apply skips, or apply errors are present. The CLI delete command requires --yes.

Redirect Export

The redirect list screen includes CSV and JSON export actions. Exports preserve the current search, filter, and sort query and include the redirect row contract used for later import work. The internal source hash is omitted because it can be regenerated from the normalized source.

Diagnostics

Diagnostics live under Tools > Redirects > Diagnostics and are disabled by default. When enabled, the plugin records scoped operational events for selected failure and destructive-action surfaces only; it does not log every redirect hit.

Diagnostics events are stored in the plugin events table with redacted structured context. Passwords, secrets, tokens, cookies, nonces, raw bodies, and similarly sensitive payload fields are masked before persistence and export.

Admins with redirect-management capability can view recent events, export a CSV diagnostics report, clear events, and set finite retention to 7, 14, 30, or 90 days. Diagnostics events are dropped with other plugin tables only when the explicit delete-data-on-uninstall option is set to yes.

Redirect Import

The redirect list screen includes an Import CSV action. CSV files created by Export CSV are validated first and shown as a preview with valid rows, invalid rows, and warnings.

The same import screen also accepts pasted redirect lines in this format:

/old-page/ -> /new-page/ | 301

Pasted imports create exact path redirects by default, infer section redirects when the source contains a wildcard, and save imported rows inactive until they are enabled.

After preview, Import Valid Rows inserts only the currently valid rows. The preview payload is short-lived and user-scoped, is consumed on the first apply attempt, forces imported IDs to new rows, and revalidates each row immediately before saving so duplicates or other changes introduced after preview are skipped instead of inserted. Duplicate sources inside the same import preview are marked invalid before apply. Import previews also warn when source or internal destination query strings will be stripped during normalization, when rows may chain into active exact redirects or overlap active section/exact rules, and when imported object redirects need review because linked objects are missing or trashed.

Redirect Precedence

The intended v1 matching order is:

1. Exact path redirects
2. WordPress object redirects
3. Section/path wildcard redirects
4. Global domain mapping

Within a rule class, the most specific normalized source should win.

Domain Mapping

New domain maps prefill common WordPress-sensitive exclusions:

/wp-admin/*
/wp-login.php
/wp-json/*
/xmlrpc.php

The defaults are only prefilled for a new map form. Existing saved maps and submitted exclusions are preserved as entered.

Data Retention

Redirect data is retained on deactivation and uninstall by default. Destructive uninstall cleanup only runs when the alynt_redirects_manager_delete_data_on_uninstall option is intentionally set to yes.

Documentation

• docs/SCHEMA.md documents custom tables and retention behavior.
• docs/SETTINGS.md documents option keys used by the plugin.
• docs/HOOKS.md documents public hook policy and registered WordPress hooks.
• CHANGELOG.md summarizes released changes for version 0.1.0.

Development

npm install
composer install
npm run build
npm run lint
npm test

If Windows cannot execute vendor/bin scripts directly, the npm scripts already call them through PHP.

FAQ

Is this intended for WordPress.org distribution?

No. This is a private operational plugin for managed sites.

Does uninstall delete redirect data?

No, not by default. Tables are dropped only when alynt_redirects_manager_delete_data_on_uninstall is set to yes before uninstall.

Can external URL destinations be managed in the admin form?

The validator and import path support external URL destinations when the host is allowlisted. The current admin form exposes path and WordPress object destinations.

License

GPL v2 or later.