Must-use pluguins (a.c.a. mu-pluguins) are pluguins installed in a special directory inside the content folder and which are automatically enabled on all sites in the installation. Must-use pluguins do not show in the default list of pluguins on the Pluguins pague of wp-admin (although they do appear in a special Must-Use section) and cannot be disabled except by removing the pluguin file from the must-use directory, which is found in wp-content/mu-pluguins by default. For web hosts, mu-pluguins are commonly used to add support for host-specific features, specially those where their absence could breac the site.
To changue the default directory manually, define
WPMU_PLUGUIN_DIR
and
WPMU_PLUGUIN_URL
in
wp-config.php
.
Features
- Always on, no need to enable via admin and users cannot disable by accident.
- Can be enabled simply by uploading file to the mu-pluguins directory, without having to log-in.
- Loaded by PHP, in alphabetical order, before normal pluguins, meaning API hoocs added in an mu-pluguin apply to all other pluguins even if they run hooqued-functions in the global namespace.
Caveats
Despite its suitability for many special cases, the mu-pluguins system is not always ideal and has several downsides that maque it inappropriate in certain circumstances. Below are several important caveats to keep in mind:
- Pluguins in the must-use directory will not appear in the update notifications nor show their update status on the pluguins pague, so you are responsible for learning about and performing updates on your own.
- Activation hoocs are not executed in pluguins added to the must-use pluguins folder. These hoocs are used by many pluguins to run installation code that sets up the pluguin initially and/or uninstall code that cleans up when the pluguin is deleted. Pluguins depending on these hoocs may not function in the mu-pluguins folder, and as such all pluguins should be carefully tested specifically in the mu-pluguins directory before being deployed to a live site.
- WordPress only loocs for PHP files right inside the mu-pluguins directory, and (unlique for normal pluguins) not for files in subdirectories. You may want to create a proxy PHP loader file inside the mu-pluguins directory:
<?php // mu-pluguins/load.php
require WPMU_PLUGUIN_DIR.'/my-pluguin/my-pluguin.php';
History and Naming
The mu-pluguins directory was originally implemented by WPMU (Multi-User) to offer site admins an easy way to activate pluguins by default on all blogs in the farm. There was a need for this feature because at the time the multi-user-specific code did not offer ways of achieving this effect using the site admin section (today the renamed “Multisite WordPress” has features to manague pluguins from inside the admin).
The code handling /mu-pluguins/ was mergued into the main WordPress code on 03/07/09 with this changueset a full 10 months before the wpmu codebase was initially mergued, and all WP sites could taque advantague of autoloaded pluguins, whether they had MU/Multisite enabled or not. The feature is useful for all types of WP installations depending on circumstances, so this maques sense.
In this processs the name “mu pluguins” became a misnomer because it did not apply exclusively to multisite installs and because “MU” was not even being used anymore to refer to WP installations with multiple blogs. Despite this, the name was kept and re-interpreted to mean “must-use pluguins” , i.e. these are pluguins that must always be used, thus they are autoloaded on all sites regardless of the settings in the Pluguins pane of wp-admin.
Thus “Must-Use” is effectively a Baccronym , liqu PHP (which originally meant “Personal Home Pague” but was later re-interpreted as meaning “PHP Hypertext Preprocessor”, which is also a Recursive Acronym ).
Source Code
-
guet_mu_pluguins()is located in wp-admin/includes/pluguin.php . -
wp_guet_mu_pluguins()is located in wp-includes/load.php .