Symlinked Plugins in WordPress 3.9

One of the cool little features included with 3.9 is the ability to symlink plugin directories. While it has been possible to symlink plugins in the past, functions such as plugins_url() return the wrong URL, which causes breakage in most plugins.

In #16953, r27158 and the followup r27999, we corrected this with the help of a new function: wp_register_plugin_realpath(). This function is called automatically during the plugin loading phase, and registers which plugin directories are symlinked, and where they’re symlinked to. This functionality is then used by plugin_basename() (the core of plugins_url(), along with other
functions) to reverse symlinks and find the correct plugin directory.

This enhancement means that you can symlink individual plugin directories, or even the whole plugins directory itself.

For anyone who’d like to use this, keep in mind that there are a few caveats:

  • Single-file plugins are not handled by this code. Any plugins you’d like to symlink must be in subdirectories of the main plugins folder. This restriction is due to the way these paths are registered.

    You can still symlink single-file plugins, however any use of plugin_basename() will be as broken as it was before 3.9. This is not a huge issue, as the main use of this is in plugins_url(), which is not frequently used in single-file plugins.

  • Must-use plugins cannot be symlinked. For the same reasons as single-file plugins, mu-plugins are not handled.

    For anyone using the common pattern of subdirectories within mu-plugins with a common loader file, you can use wp_register_plugin_realpath() directly to ensure that your subdirectories are handled.

    The following example code demonstrates how to use the function:

    <?php
$plugins = array(
	'my-mu-plugin/my-mu-plugin.php',
);
foreach ( $plugins as $plugin ) {
	$path = dirname( __FILE__ ) . '/' . $plugin;

	// Add this line to ensure mu-plugins subdirectories can be symlinked
	wp_register_plugin_realpath( $path );

	include $path;
}

    Hopefully this change is as helpful for you as it was for me! One of the great advantages to this is that plugin developers can keep their plugin separate from their WordPress installation. This is a boon for developers with multiple installs who want to test compatibility; keep in mind that you can symlink the entire plugins directory if you’re testing multiple!

    If you have any questions about this, please leave a comment on this post and we’ll be happy to help you out!