Using symlinks for WordPress MU plugins

If you haven’t run into them before, WordPress Must-Use (MU) plugins can be a great way to say “no, seriously, my WordPress site needs this plugin in order to function”. Other times, MU plugins may be used to activate required functionality that site maintainers don’t want the site editorial team to have to worry about (for example, caching plugins like Batcache).

There are a lot of things that can be done with MU plugins, but there’s one major limitation right out of the gate: WordPress MU plugins cannot run in sub-directories.

There are a lot of patterns that people will use to get around this limitation: some developers choose to bundle their plugins into single files, while others use intermediary files that consist of a series of require statements for the plugins in directories:

 * Load my mu-plugins.

require_once __DIR__ . '/batcache/batcache.php';
require_once __DIR__ . '/some-other-mu-plugin/some-other-mu-plugin.php';

While these autoloader-type files aren’t bad, one of my favorite ways to handle this situation is with system-level symbolic links (“symlinks”).

What is a symlink?

A symbolic link (“symlink”) is a shortcut within the filesystem that points to a resource elsewhere on the system. This could be to a directory or a file, but this shortcut lives inside a directory.

Symlinks make it trivial to include a single file in multiple directories (while only having to maintain a single copy), and can also be used to get around the single-file MU plugin restriction.

On Unix-based operating systems (macOS, Linux), a symlink can be created using the ln (“link”) command:

ln -s <target> <name>

For example, let’s say we want to run batcache.php as an MU plugin out of wp-content/mu-plugins/batcache/:

ln -s /path/to/wp-content/mu-plugins/batcache/batcache.php /path/to/wp-content/mu-plugins/batcache.php

As far as the filesystem is concerned, batcache/batcache.php lives at wp-content/mu-plugins, and the plugin will load as if it lives there.

How can symlinks help me with my MU plugins?

Where symlinks become really powerful are when you’re using dependency management tools like Composer: suddenly, it doesn’t matter where the actual source files live; as far as WordPress is concerned, the plugin lives in wp-content/mu-plugins.

Likewise, if you have several WordPress sites running the same plugins on the same server (and you’re not concerned with the two sites running different versions of those plugins), you could have a single copy of the codebase running on your server across multiple sites.

Symlinks are an extremely powerful tool to have in your arsenal, so if you haven’t used them much before, definitely spend some time playing with them. The ability to be in more than one place is one superpower I frequently find myself wishing I had.

Leave a Reply