# Redirection: managing WordPress 301s and 404 logs without touching .htaccess

> Redirection is a WordPress plugin that stores 301 redirect rules in the database and records 404 hits, so a site migration does not require editing Apache configuration by hand. It also ships a full build, lint and test toolchain for anyone who wants to work on the plugin itself.

**johngodley/redirection** — Manage all your WordPress 301 redirects and monitor 404 errors

- Repository: https://github.com/johngodley/redirection
- Website: https://redirection.me
- Stars: 637 · Forks: 157
- Language: PHP
- License: GPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/johngodley-redirection

## Redirection keeps its rules in the database, not in Apache config

Redirection is a WordPress plugin for managing 301 redirects, keeping track of 404 errors and tidying up the loose ends a site accumulates. The stated use cases are migrating pages from an old website and changing the directory of a WordPress installation, which is the kind of change that normally means editing Apache .htaccess files by hand. The plugin's own description states the point directly: it manages 301 redirections and keeps track of 404 errors without requiring knowledge of Apache .htaccess files. That is the design decision everything else follows from. Redirect rules and the record of failed URLs live in the database and are applied by PHP during a WordPress request, so a site owner can add, edit and disable rules from an admin interface instead of editing server configuration over SSH. The trade-off is equally direct. A rule that a visitor hits before WordPress loads is not covered by the plugin, and the plugin's own documentation points out that access to the admin interface is granted to users who can manage_options, with the ability to change that through permission filters. The homepage is redirection.me, and the plugin is distributed through the WordPress.org plugin directory.

## The trunk branch is explicitly labelled experimental

The repository carries a warning that deserves attention before anyone clones it. The README states that this is the current trunk version of Redirection, that it may be newer than what is in the WordPress.org plugin repository, and that it should be considered experimental. That framing defines the relationship between the git repository and the plugin directory. The repository is where new work lands first, and the WordPress.org plugin page is where a stable build of it is published. The published releases listed for the project are version 5.10.1 dated 2026-09-19, version 5.10.0 dated 2026-08-29 and version 5.9.0 dated 2026-07-11, and package.json carries version 5.10.1 with main pointing at redirection.php. The last push to the repository was on 2026-10-04, which is after the newest published release, so trunk contains work that has not yet shipped to the plugin directory. Anyone installing from the WordPress.org page gets the 5.10.1 line. Anyone working from the trunk branch is working with code the maintainer himself describes as experimental, and the practical difference between the two is the gap the release process closes.

## Installing means grabbing the plugin; building means Node, pnpm and Composer

There are two distinct paths here and they are often confused. Installing Redirection as a site owner means visiting the WordPress.org plugin page, and the README points at https://wordpress.org/plugins/redirection/ for that. No server access, no build step, no command line. Building the plugin from source is a different activity, because the project is mostly PHP but does contain files that need to be built. The stated requirements for that are Node.js >= 12.14.0, pnpm and Composer for PHP development. With those in place the setup is two commands, one for the JavaScript dependencies and one for the PHP dependencies used in linting and testing:

```bash
pnpm install
```

```bash
composer install
```

The development loop uses the same package manager. The UI is built with React using @wordpress/scripts, and hot-reload development starts with:

```bash
pnpm start
```

A production build of the assets is:

```bash
pnpm build
```

For a site owner none of this matters, which is exactly the point of the split. The plugin's compiled assets ship with the released package, so you install it and configure it in the admin interface, and the build toolchain only matters to someone who intends to change the code.

## Four lint targets and five test suites, including a real WordPress environment

The tooling is unusually complete for a WordPress plugin, and the split tells you how the code is organised. Linting runs through a single entry point that chains four targets:

```bash
pnpm lint
```

Those four are pnpm lint:php for PHP linting with PHPCS and PHPStan, pnpm lint:js for JavaScript, pnpm lint:css for CSS, and pnpm lint:ts for TypeScript type checking. PHP code can be reformatted with composer format. Testing is split even further. The PHP unit tests run with pnpm test:unit, or through composer test-unit directly. The integration tests need a real WordPress, and the workflow starts by bringing up the environment and then running the suite:

```bash
pnpm wp-env:start
```

```bash
pnpm test:integration
```

The environment is torn down with pnpm wp-env:destroy. JavaScript tests run through pnpm test:js, and there is a separate end-to-end suite:

```bash
pnpm test:e2e
```

Running everything at once is pnpm test. The corresponding config files are visible in the repository root: phpunit-unit.xml and phpunit-integration.xml split the two PHP suites, jest.config.js and e2e-jest.js handle the JavaScript side, .wp-env.json describes the local WordPress environment, and phpcs.xml plus phpstan.neon and phpstan-max.neon hold the static analysis configuration. A separate phpunit-integration.xml existing at all tells you the plugin is tested against an actual WordPress instance rather than a mock.

## A release pipeline that builds a zip and pushes to WordPress.org SVN

The release process is scripted, and the scripts show how a WordPress plugin actually reaches users. The plugin directory is assembled by the plugin script, which builds the assets, recreates a release directory and copies the PHP entry files, changelog.txt, readme.txt, the build output, license.txt and the includes, modules, models, matches and images directories into it, excluding the two Rector configuration files from the packaged copy. Wrapping that, there are two entry points. A full release build compiles the assets and creates a zip:

```bash
pnpm release
```

and the plugin:zip target produces just the zip file without publishing it:

```bash
pnpm plugin:zip
```

Publishing to the WordPress.org plugin directory is a separate step that runs the zip build and then calls the SVN deployment script with the package version:

```bash
pnpm release:svn
```

The release script itself delegates to dev/release-github.sh. That the plugin directory is versioned through SVN rather than uploaded as a release is a quirk of the WordPress.org distribution model, and it explains why the trunk branch and the published plugin can differ. The API documentation is generated from an OpenAPI description in dev/openapi.yaml with pnpm doc, producing a release/api-doc.html file, which tells you the plugin exposes an HTTP API that is documented separately from the admin interface.

## Hooks and permission filters are the extension points

Two extension mechanisms are described, and they sit at different layers. The first is a large set of WordPress action and filter hooks, documented on the Redirection Hooks page at redirection.me/developer/wordpress-hooks/, which are described as usable to extend or customise the plugin. The second is the permission model. Access to the admin interface is given to users who can manage_options, and the documentation says this can be modified with permission filters described on the Redirection permissions page. That is a meaningful detail for anyone running a WordPress site with a layered role structure, because the default assumption is that only full administrators see the redirect tables at all. The repository layout backs up the impression of a mature plugin: redirection-admin.php, redirection-front.php, redirection-cli.php, redirection-capabilities.php, redirection-settings.php and redirection-refactor.php sit at the top level, with includes/, models/, modules/, matches/, actions/, src/, dev/, tests/ and e2e/ below. A separate redirection-cli.php entry point indicates command line access to some of the functionality, and the presence of a wp-scripts based React front end in src/ with TypeScript configuration in tsconfig.json and jsconfig.json shows the interface has been migrated to modern tooling. Translations for the plugin are handled on translate.wordpress.org under the wp-plugins/redirection project, which is where a translator would contribute.

## Where Redirection stops and server-level redirects take over

There are cases where this plugin is the wrong instrument, and the honest reason is architectural rather than a missing feature. Because the rules are applied by PHP inside a WordPress request, a redirect can only happen once WordPress is running and able to load the plugin. Requests that never reach WordPress, whether because the web server returns an error first or because a static file is served directly by the server, are outside the plugin's reach. A site that has just migrated domains and needs every incoming link resolved immediately, before a database query and a PHP bootstrap, needs rules at the web server or CDN layer instead. The plugin's own positioning acknowledges this gap by promising to save you from .htaccess knowledge rather than from needing a web server at all. There is a second limitation worth naming, which is operational rather than technical. The trunk branch is described as experimental and can be ahead of what the WordPress.org directory serves, so a site that needs a specific fix has to check whether it exists in the published 5.10.1 release or whether it only exists in the repository. For those who want to compare, server-level approaches such as Apache mod_rewrite rules or an edge redirect service solve the same problem at a different layer, with the tradeoff that they need server access and apply to requests that never boot WordPress.

## Conclusion

Redirection suits site owners who are migrating pages or reorganising directories and want a database-backed rule set with 404 history, and it suits plugin developers who want to read a well-instrumented WordPress codebase with unit, integration and end-to-end tests. It is the wrong choice if you need redirect rules enforced at the web server layer before WordPress boots, or if you will not touch the plugin when the WordPress.org version lags the trunk branch. Verify first that the release you install matches the 5.10.1 line published on 2026-09-19, that your web server can pass requests through to WordPress, and that the permissions filter mechanism documented on the redirection.me developer pages matches how your administrators are set up.

## FAQ

### How do I install the Redirection WordPress plugin?

The plugin is installed from the WordPress.org plugin page at https://wordpress.org/plugins/redirection/. The build toolchain with Node, pnpm and Composer is only needed if you intend to work on the plugin source.

### Who can see the Redirection admin interface?

Access is given to users who can manage_options. The documentation states this can be changed with permission filters, described on the Redirection permissions page at redirection.me/developer/permissions/.

### How do I run the Redirection integration tests?

You start the local WordPress environment with pnpm wp-env:start, then run pnpm test:integration, and stop the environment with pnpm wp-env:destroy.

### What is the difference between the Redirection trunk branch and the WordPress.org plugin?

The README states that the trunk version may be newer than what is in the WordPress.org plugin repository and should be considered experimental. The last push was on 2026-10-04, after the published 5.10.1 release dated 2026-09-19.

## Sources

- [johngodley/redirection on GitHub](https://github.com/johngodley/redirection)
- [License: GPL-3.0](https://github.com/johngodley/redirection/blob/trunk/LICENSE)
- [Project website](https://redirection.me)
- [README](https://github.com/johngodley/redirection/blob/trunk/README.md)
- [Releases](https://github.com/johngodley/redirection/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/johngodley-redirection