В WordPress Multisite функция switch_to_blog() изменяет текущий сайт для дальнейшего выполнения PHP-кода. После этого стандартные функции WordPress работают уже в контексте другого блога: обращаются к его таблицам, options, записям и части пользовательских данных.
Самая распространённая ошибка — вызвать switch_to_blog(), но не выполнить restore_current_blog(). Такой баг может проявиться не в том же месте, где возник: следующий запрос, cron-задача или REST-ответ внезапно получит данные другого сайта. В этой статье рассмотрим безопасный шаблон, типичные ошибки, диагностику и способы сократить количество переключений.
Что именно изменяет switch_to_blog()
В Multisite каждый сайт имеет собственный контекст. В зависимости от функции WordPress использует соответствующие таблицы с префиксами конкретного блога, например wp_2_options или wp_3_posts. После вызова switch_to_blog($blog_id) глобальный объект $wpdb и внутреннее состояние WordPress переключаются на указанный сайт.
Поэтому после переключения такие вызовы, как get_option(), get_posts(), WP_Query или запросы через $wpdb, могут работать уже не с основным сайтом, а с выбранным блогом. Это не локальное изменение только для одной строки кода: контекст сохраняется до следующего переключения или восстановления.
Важно различать сайт и сеть. get_option() читает настройки текущего блога, тогда как get_site_option() предназначена для сетевых настроек. Имя переменной вроде my_network_option само по себе не делает опцию сетевой.
- switch_to_blog() изменяет текущий контекст выполнения.
- get_option() работает с опциями текущего блога.
- get_site_option() читает настройки уровня сети.
- restore_current_blog() возвращает предыдущий контекст.
Безопасный шаблон: переключение в try/finally
Каждое переключение нужно рассматривать как временную операцию с чёткой парой: switch_to_blog() в начале и restore_current_blog() в конце. Самый надёжный вариант в современном PHP — блок try/finally.
Блок finally выполняется даже в том случае, если внутри возникло исключение или выполнение покидает блок через return, break или continue. Благодаря этому код не оставит процесс в неправильном контексте.
- Вызывайте restore_current_blog() в finally, а не только после успешного выполнения операции.
- Не рассчитывайте на то, что следующая итерация цикла самостоятельно исправит состояние.
- В рамках одного переключения выполняйте только те операции, которым действительно нужен другой сайт.
foreach ( $blog_ids as $blog_id ) {
switch_to_blog( $blog_id );
try {
$value = get_option( 'my_option' );
// Работа с данными текущего сайта.
} finally {
restore_current_blog();
}
}
Почему пропущенное восстановление создаёт сложные баги
Если не вызвать restore_current_blog(), код после switch_to_blog() продолжит выполняться в контексте последнего выбранного блога. Особенно опасно это в больших функциях, где между переключением и следующим запросом находится много вспомогательной логики.
Проблема часто выглядит случайной: один сайт получает настройки другого, администратор видит неправильный список записей, а cron или WP-CLI-команда записывает данные не туда, куда ожидалось. Причина может находиться далеко от места, где формируется неправильный результат.
В цикле без восстановления контекста следующая итерация также становится менее предсказуемой. Если код переключается на дочерние сайты, а затем должен вернуться на сайт, с которого начал работу, пропущенное восстановление нарушает эту логику.
- В cron-задаче неправильный контекст может повлиять на следующие операции в рамках того же запуска.
- В WP-CLI это может изменить результаты последующих команд или обработку пакетов данных.
- В REST endpoint ошибка может попасть в ответ или привести к записи в чужой блог.
- В длительных процессах неправильный контекст сохраняется дольше, чем ожидает разработчик.
Как правильно работать с данными разных сайтов
Перед циклом определите, какие операции действительно требуют контекста отдельного блога. Не нужно переключаться для получения данных сетевого уровня, если их можно получить через get_site_option(), get_sites() или другие соответствующие API.
После переключения не смешивайте в одном блоке запросы к текущему сайту и сетевые операции без чёткой логики. Это упрощает проверку кода и снижает риск случайно использовать get_option() вместо get_site_option().
Если нужно изменить данные нескольких сайтов, соберите и проверьте идентификаторы заранее и переключайтесь только на нужный блог. Для каждого blog ID желательно убедиться, что он относится к ожидаемой сети, особенно если значение поступает из запроса или внешних данных.
- Для опций конкретного сайта используйте get_option() после switch_to_blog().
- Для сетевых опций используйте get_site_option() без лишнего переключения.
- Не доверяйте blog ID, полученному без проверки из HTTP-запроса.
- Не используйте переключение как замену проверкам прав доступа.
$network_value = get_site_option( 'my_network_option' );
foreach ( $blog_ids as $blog_id ) {
switch_to_blog( (int) $blog_id );
try {
$site_value = get_option( 'my_site_option' );
// Обработка настройки конкретного сайта.
} finally {
restore_current_blog();
}
}
Особенности для циклов, WP-CLI, cron и REST
В циклах важно восстанавливать контекст на каждой итерации, а не один раз после завершения всего цикла. Если во время обработки одного блога состояние останется изменённым, следующий элемент может обрабатываться с неправильными таблицами или настройками.
Для WP-CLI и cron-задач стоит дополнительно проверять исходный blog ID перед запуском критической логики. Такие процессы часто выполняют много операций последовательно, поэтому один пропущенный restore_current_blog() может повлиять на весь запуск.
В REST endpoint переключение не меняет авторизованного пользователя на другого. Однако данные, роли и возможности могут быть связаны с конкретным сайтом, поэтому проверку прав нужно выполнять с учётом нужного блога. Сам факт успешного switch_to_blog() не является разрешением на чтение или изменение его данных.
- Изолируйте логику одного блога в небольшой функции или отдельном методе сервиса.
- Избегайте скрытых переключений в функциях, которые вызываются из разных мест.
- Для операций записи проверяйте права, существование блога и корректность входных данных.
- После завершения обработки проверяйте, что код вернулся к ожидаемому блогу.
Диагностика: как найти неправильный контекст
Первый шаг при расследовании — записывать в лог результат get_current_blog_id() перед критическим чтением или записью. Это помогает сравнить ожидаемый blog ID с фактическим и найти место, где изменился контекст.
Логи должны содержать название операции, идентификатор блога и, при необходимости, идентификатор пользователя или запуска. Не записывайте в журнал конфиденциальные значения опций или полные данные запросов без необходимости.
Также проверьте код на наличие ранних return, исключений, break и continue между switch_to_blog() и restore_current_blog(). Если переключение скрыто в callback или хуке, проверьте все пути выполнения, а не только основной сценарий.
- Добавьте логирование до и после критической операции.
- Сравните get_current_blog_id() с blog ID, переданным в функцию.
- Проверьте, не вызывается ли switch_to_blog() вложенно.
- Тестируйте сценарии с исключением и преждевременным завершением.
- После пакета операций убедитесь, что текущий блог снова имеет ожидаемое значение.
$expected_blog_id = (int) $blog_id;
switch_to_blog( $expected_blog_id );
try {
error_log(
sprintf(
'Processing blog: expected=%d actual=%d',
$expected_blog_id,
get_current_blog_id()
)
);
// Критическая операция.
} finally {
restore_current_blog();
}
Типичные ошибки и нагрузка от переключений
Одна из типичных ошибок — вызывать switch_to_blog() перед каждой небольшой операцией, хотя несколько запросов можно выполнить в одном контексте. Каждое переключение изменяет глобальное состояние и может взаимодействовать с кэшированием объектов, поэтому лишние вызовы в больших циклах усложняют код и добавляют накладные расходы.
Другая ошибка — использовать switch_to_blog() для доступа к сетевым данным. В таком случае переключение не только не нужно, но и создаёт риск случайно выполнить соседнюю операцию на чужом сайте.
Не стоит также вручную изменять $wpdb->prefix вместо API WordPress. Ручная подмена префикса не воспроизводит полностью поведение переключения контекста и может привести к ошибкам в кэше или служебных запросах.
- Группируйте связанные операции в одном try/finally.
- Не переключайтесь, если достаточно get_site_option() или сетевого API.
- Не полагайтесь на ручное изменение префикса таблиц.
- Не считайте restore_current_blog() необязательным после переключения даже на тот же сайт.
- Во время code review ищите все вызовы switch_to_blog() и проверяйте их пару с restore_current_blog().
Частые вопросы
Нужно ли вызывать restore_current_blog() после каждого switch_to_blog()?
Да, если код временно переключает контекст, а затем должен продолжить работу с предыдущим сайтом. Безопаснее всего размещать restore_current_blog() в finally. Это особенно важно в циклах, cron-задачах, WP-CLI и REST endpoint.
Что произойдёт, если во время работы возникнет исключение?
Без finally выполнение может завершиться до вызова restore_current_blog(), и текущий контекст останется изменённым на оставшуюся часть процесса. Конструкция try/finally гарантирует восстановление даже после исключения.
Чем отличаются get_option() и get_site_option() в Multisite?
get_option() работает с настройками текущего блога, а get_site_option() — с настройками уровня сети. Для сетевых данных обычно не требуется переключаться между блогами.
Меняет ли switch_to_blog() текущего авторизованного пользователя?
Нет, переключение блога не делает пользователя другим. Однако доступ к ролям и возможностям в Multisite может зависеть от конкретного сайта, поэтому права нужно проверять в правильном контексте.
Как быстро проверить, в каком блоге выполняется код?
Используйте get_current_blog_id() и запишите результат в debug-лог перед критической операцией. Сравните его с ожидаемым идентификатором сайта.
Вывод
switch_to_blog() — полезный инструмент для работы с данными разных сайтов в WordPress Multisite, но он изменяет глобальный контекст выполнения. Поэтому каждый вызов должен быть контролируемым и завершаться restore_current_blog().
Практическое правило простое: переключайтесь только при необходимости, группируйте операции в try/finally, разделяйте данные сайта и сети и проверяйте get_current_blog_id() во время диагностики. Это предотвращает тихие ошибки, когда код читает или изменяет данные не того блога.