Redirecting Legacy URIs in MODX CMS

May 12, 2015

The Problem

Redirects are a fact of Life. (Yes, in this context, Life == The Internet.) Luckily MODX provides many options for you to handle redirects, including core methods and installable Extras. Here's a review of most, if not all, of these options.

Options for redirecting legacy URIs in MODX


Redirector has long been the go-to Extra for handing redirects in MODX. It's fully-featured, including a Custom Manager Page (CMP) that provides an easy-to-use interface for non-tech folks to manage their redirects.

It can even handle more complex requirements like tracking Manager actions for changed URIs. If you need help implementing some of the more advanced features, or you might benefit from additional features, contact the MODX PS team.

All that aside, Redirector isn't always the best solution, at least for some common use cases. Why?

The fact that it's fully-featured means it executes a lot of code, relatively speaking. The Redirector plugin includes its class, does database lookups, calls methods to process MODX tags, etc.

Granted, it only fires on the 'OnPageNotFound' event, so overall site performance is probably not being sent to the sewer, but if you only need a screwdriver, maybe it's better not to use a power drill…?

htaccess or nginx Rewrites

By far the most performant way to redirect traffic is via server configuration. There's plenty of documentation on the Internet about this topic, written by far more qualified folks than myself, so use that omnipotent developer resource "Google" and you'll almost certainly find what you need. If you're using MODX Cloud, (or any nginx server) you can probably benefit from this documentation here.

The reason why this is the most performant option, is that you don't have to execute PHP at all, to serve up the redirect. PHP is going to be hard-pressed to outperform a properly configured web server for a job like simple redirects.

There are some drawbacks though. If you have a huge list of URIs to redirect, it can get unruly to manage them in a .htaccess or .conf file. Furthermore, you're limited in the "dynamic" stuff that you can do...I'll explain what that might mean in the next section...

Custom MODX Plugin Using Core Methods

Let's say you just rebuilt a client's website in MODX, but the client is concerned about SEO (who isn't?) You need to redirect legacy URIs, but what if you also want to maintain control of the redirect target by "routing" through a MODX Resource?

Using a Switch Statement

Here's an example of how you can do that with a custom plugin, some core MODX methods and a switch statement:

The comments should make it fairly obvious what's going on here. Notice that by using the $modx->makeUrl() method, you have access to some fairly robust, dynamic routing features. Using a switch statement, only the matched case will execute. This method probably starts to fall down if you have a ton of redirects to manage. Also, it doesn't expose any of it to non-coder type folks. For that, it's back to Redirector.

Using an Array

Sometimes a client will supply a list of old URIs that they want to map to new URIs. I've come across this on several occasions. If there's no requirement to use the makeURL method, a simple PHP array can be a wee bit faster than a switch statement:

Again, not as fast as server configuration, but definitely faster than the other Plugin options mentioned here, and also it's more accessible than a nginx .conf file. You can edit this Plugin in the MODX Manager for example, and you can prepend the $baseUrl variable to handle multiple contexts.

Snippets and Other Options

Not every requirement for a redirect involves a long list of URIs to handle. Sometimes you want to redirect one Resource to an external link, or to another Resource. You can do this by simply making your Resource a WebLink document, which is a MODX feature out-of-the-box. You can also call the Redirectoid Snippet in your Template dynamically, or redirect to the first "child" Resource of a given Resource with FirstChildRedirect.

Creative Freedom

This is by no means an exhaustive list, but you can see that MODX gives you plenty of options dealing with the housekeeping duties of redirecting old URLs. If you have any solutions of your own, please share them in the comments :)