MU-plugins в WordPress: организация системного слоя сайта
MU-plugin - это плагин из каталога wp-content/mu-plugins, который WordPress подключает автоматически, до обычных плагинов, без включения в админке.
Прямой ответ: MU-слой - это инфраструктурный код проекта, который обеспечивает выполнение обязательных задач до загрузки обычных плагинов и темы. Сам по себе MU-слой не гарантирует работоспособность сайта. Отключение слоя рассматривается как изменение конфигурации или аварийная операция, а не как штатное действие администратора. Организуют слой как версионируемый код: loader в корне mu-plugins плюс модули с разделением загрузки и инициализации, явными проверками зависимостей и миграциями схемы в контролируемом процессе деплоя.
1. Зачем нужны MU-плагины
Свойства по документации:
- включаются сами, отдельная вкладка Must-Use на экране Plugins;
- отключить из админки нельзя, для отключения нужно удалить файл из каталога;
- PHP-файлы непосредственно в каталоге MU-плагинов загружаются в алфавитном порядке, до обычных активных плагинов. Файлы во вложенных каталогах автоматически не подключаются;
- каталог по умолчанию -
wp-content/mu-plugins. Путь и URL можно переопределить константамиWPMU_PLUGIN_DIRиWPMU_PLUGIN_URLсоответственно, заданными вwp-config.php.
Штатных уведомлений об обновлениях для MU-плагинов нет, обновления выполняются средствами сборки, а не админки.
2. Что должно находиться в MU-слое
Основной принцип: в MU-слой помещают инфраструктурный код проекта, который должен загружаться независимо от активной темы и состояния обычных плагинов. При этом его отключение должно рассматриваться как изменение конфигурации или аварийная операция, а не как штатное действие администратора.
Независимость от темы - необходимое свойство, а невозможность отключения сама по себе еще не основание класть код в MU. Обязательная интеграция с внешним сервисом может не зависеть от темы, но иметь собственные настройки и жизненный цикл. Тогда ей место в обычном плагине, пусть даже обязательном для сборки.
Кандидаты в MU-слой:
- базовая инфраструктура проекта: пространства имен, автозагрузка классов, общие хелперы;
- чтение окружения и выбор поведения модулей на его основе, например различия staging и prod;
- обязательные платформенные интеграции без собственного UI: мониторинг, логирование, коннекторы, без которых сайт нельзя эксплуатировать;
- ограничения MU-слоя, действующие при любой теме и не являющиеся контентными настройками.
3. Что не следует туда помещать
В MU-слой не помещают код по функциональным причинам, а не по факту наличия настроек. Конфигурация обязательного модуля MU-слоя вполне может храниться в опциях, это само по себе не выводит код из MU-слоя.
Не помещают:
- конфигурационные константы уровня WordPress, включая
WP_ENVIRONMENT_TYPE: их место вwp-config.phpили в окружении сервера, MU-плагин подключается слишком поздно, чтобы быть их источником; - код, которому нужны хуки активации, деактивации или деинсталляции для установки схемы или очистки;
- функциональность, для которой отключение из админки - нормальный сценарий управления сайтом: SEO, формы, кеш с настройками;
- бизнес-логику отдельных разделов и представление: шорткоды темы, шаблоны, стили;
- плагины, жизненный цикл и обновление которых рассчитаны на штатный механизм WordPress.
4. Организация структуры
WordPress подключает только PHP-файлы непосредственно в mu-plugins. Для файлов во вложенных каталогах используют загрузчик (loader) - PHP-файл в корне MU-каталога, который подключает bootstrap проекта. Это поведение ядра, а конкретная реализация loader не стандартизирована.
mu-plugins/
├── project-loader.php
└── project/
├── bootstrap.php
├── core/
│ └── environment.php
└── modules/
├── security.php
├── admin.php
└── integrations.php
Loader проверяет флаг аварийного отключения и наличие bootstrap:
<?php
// mu-plugins/project-loader.php
defined( 'ABSPATH' ) || exit;
if ( defined( 'PROJECT_MU_DISABLE' ) && PROJECT_MU_DISABLE ) {
return;
}
$bootstrap = WPMU_PLUGIN_DIR . '/project/bootstrap.php';
if ( ! is_readable( $bootstrap ) ) {
error_log( 'project MU: bootstrap.php not found.' );
return;
}
require_once $bootstrap;
Отсутствие bootstrap.php означает, что инфраструктурный код MU-слоя не загружен. Поведение в этом случае определяет сборка заранее: остальной код проверяет готовность слоя и деградирует предсказуемо, дежурный видит запись в логе. Если сборка без слоя работать не может, в документации фиксируют остановку инициализации и отдельный механизм отказа в обслуживании вместо тихого продолжения.
Bootstrap разделяет обязательные и необязательные модули:
<?php
// mu-plugins/project/bootstrap.php
defined( 'ABSPATH' ) || exit;
const PROJECT_MU_VERSION = '1.4.0';
const PROJECT_MU_SCHEMA_VERSION = '1.2.0';
$required = [
'core/environment.php',
'modules/security.php',
];
$optional = [
'modules/admin.php',
'modules/integrations.php',
];
foreach ( $required as $module ) {
$file = __DIR__ . '/' . $module;
if ( ! is_readable( $file ) ) {
error_log( 'project MU: required module missing: ' . $module );
return;
}
require_once $file;
}
foreach ( $optional as $module ) {
$file = __DIR__ . '/' . $module;
if ( ! is_readable( $file ) ) {
error_log( 'project MU: optional module skipped: ' . $module );
continue;
}
require_once $file;
}
Версия кода и версия схемы разделены намеренно: код может меняться без изменения структуры базы. Каталог не сканируется через glob, порядок загрузки определяется явными списками.
5. Особенности жизненного цикла
MU-плагины загружаются до обычных активных плагинов. После загрузки всех MU-плагинов и сетевых плагинов срабатывает muplugins_loaded, а после подключения обычных плагинов - plugins_loaded. Поэтому при разработке нужно учитывать не только порядок подключения файлов, но и доступность API на каждом этапе.
Если модулю необходимы функции или классы обычного плагина, инициализацию следует отложить до момента, когда зависимость гарантированно доступна. Для проверки наличия плагина и регистрации интеграционных хуков обычно подходит plugins_loaded, но готовность конкретного API определяется жизненным циклом самого плагина.
Файл модуля MU-слоя в момент подключения только проверяет окружение и регистрирует хуки, работу он выполняет в колбэках. Pluggable-функции и классы обычных плагинов нельзя считать доступными в момент загрузки MU-файла.
Пример зависимости от WooCommerce:
<?php
// mu-plugins/project/modules/integrations.php
add_action( 'plugins_loaded', function () {
if ( ! class_exists( 'WooCommerce' ) ) {
error_log( 'project MU: WooCommerce not found, integration skipped.' );
return;
}
// регистрация хуков интеграции
} );
Миграции в MU-слое не имеют хуков активации. Принципы вместо готового мигратора: версия схемы хранится отдельно от версии кода, миграции идут последовательно, каждая безопасна при повторном запуске, версия обновляется только после полного успеха. Запуск - в контролируемом процессе деплоя, например через WP-CLI, а не по первому заходу в админку.
Полноценный листинг мигратора здесь намеренно отсутствует. Блокировка через transient не исключает гонку, а add_option в актуальной реализации не дает гарантии эксклюзивного владения, для захвата нужен отдельный механизм уровня базы, например advisory lock или собственная таблица с атомарной вставкой. Ошибки $wpdb->query возвращают false и не всегда превращаются в исключения, запись версии через update_option затрагивает объектный кеш отдельно от транзакции базы, а DDL-операции MySQL вызывают implicit commit. Поэтому откат транзакцией для миграций схемы не гарантирован. Надежность обеспечивают идемпотентные шаги, фиксация прогресса и заранее предусмотренная стратегия восстановления после частичного выполнения.
Для Multisite область миграции определяют отдельно: общая сетевая схема или схема каждого сайта, во втором случае миграция выполняется в контексте каждого сайта контролируемым процессом. В рамках статьи сетевая миграция - отдельное архитектурное ограничение.
6. Надежность и диагностика
Два уровня нельзя смешивать. Загрузка: файл существует, доступен, подключается без фатальной ошибки. Проверка is_readable() относится только к этому уровню. Инициализация: зависимости присутствуют, окружение подходит, модуль может регистрировать хуки. Проверка файла не равнозначна проверке работоспособности.
Отдельные файлы не означают изоляцию выполнения: все модули работают в одном PHP-процессе. Можно обеспечить независимость инициализации необязательных модулей, но нельзя гарантировать, что ошибка одного уже подключенного модуля не повлияет на остальные.
При ошибке обязательного модуля bootstrap прекращает инициализацию остальных модулей MU-слоя и записывает причину в лог. Если без этого слоя проект не может безопасно обслуживать запросы, сборка должна предусматривать отдельный механизм отказа в обслуживании, а не просто прекращать загрузку модулей. return внутри bootstrap.php останавливает только этот файл, WordPress продолжит загружать обычные плагины и тему, поэтому аварийное поведение описывают явно.
Совместимость с минимальной версией PHP проверяют на этапе сборки и деплоя. В рантайме дополнительно проверяют наличие необходимых функций и классов до регистрации зависимых хуков. Проверка внутри файла не спасает от parse error, если сам файл уже содержит несовместимый синтаксис.
Для диагностики используют проверки зависимостей до регистрации хуков, feature flags через константы в wp-config.php для рискованных интеграций, журнал ошибок с понятными сообщениями о модуле и причине. Страница в админке со списком модулей и их состоянием - возможный инструмент для сборки с несколькими обязательными интеграциями, а не универсальное требование.
Аварийное отключение MU-слоя выполняют через PROJECT_MU_DISABLE в wp-config.php или переименование project-loader.php. Если без слоя сайт не должен обслуживать запросы, механизм отказа в обслуживании должен быть реализован отдельно. Процедуру отключения и восстановления фиксируют заранее.
7. Обновление и сопровождение
Git здесь - способ контроля исходников, а не самостоятельный механизм деплоя. Схема: исходники MU-слоя лежат в репозитории сборки вместе с lock-файлом зависимостей, изменения проходят staging и проверку, на prod попадают процессом деплоя, а не правкой файлов. Версия слоя хранится в константе и видна в диагностике, изменения фиксируются в changelog сборки. Для каждого модуля зафиксирован владелец: кто поддерживает, как обновлять, от чего зависит.
Если MU-плагины добавляет хостер, владелец сайта должен знать, какие файлы добавлены и как они влияют на поведение.
8. MU-plugins, обычные плагины, drop-ins и functions.php
| Задача | Куда помещать | Почему |
|---|---|---|
| Обязательная инфраструктура без UI | MU-слой | Загружается независимо от темы и активных плагинов |
| Отключаемая функциональность с настройками и жизненным циклом | Обычный плагин | Есть активация, настройки, штатные обновления |
| Кеш и точки расширения ядра | Drop-in (object-cache.php, advanced-cache.php) | Отдельный механизм ядра со своим местом и именем файла |
| Представление и привязка к теме | functions.php темы | Действует только при активной теме |
| Параметры окружения и низкоуровневая конфигурация | wp-config.php или окружение сервера | Доступно раньше MU-слоя |
Выбирайте механизм исходя из ответственности кода и требований к его жизненному циклу. Конфигурационные параметры определяйте в wp-config.php, обязательную инфраструктуру размещайте в MU-слое, отключаемую функциональность реализуйте обычными плагинами, а логику представления связывайте с темой. Drop-ins используйте только для предусмотренных WordPress точек расширения. Не всякий код, который технически можно положить в MU-каталог, должен там находиться.
