Symlinked Plugins in WordPress 3.9

One of the cool little features included with 3.9 is the ability to symlink pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party directories. While it has been possible to symlink plugins in the past, functions such as plugins_url() return the wrong URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org, 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 coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. of plugins_url(), along with other
functions) to reverse symlinks and find the correct plugin directory.

This enhancementenhancement Enhancements are simple improvements to WordPress, such as the addition of a hook, a new feature, or an improvement to an existing feature. 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!

    #3-9, #dev-notes, #plugins, #symlinks