☰
WORDPRESS / PRACTICE

Безопасное переключение контекста в WordPress Multisite

Безопасное переключение контекста в WordPress Multisite

В 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() во время диагностики. Это предотвращает тихие ошибки, когда код читает или изменяет данные не того блога.

← Все материалы WordPress