У 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() під час діагностики. Це запобігає тихим помилкам, коли код читає або змінює дані не того блогу.