Неочікувана зміна опції WordPress часто виглядає як проблема з базою даних: налаштування зберегли, але після нового запиту, cron-завдання або повторного відкриття сторінки воно повернулося до старого значення. Насправді причиною може бути плагін, тема, обробник форми, REST-запит або фоновий процес, який повторно викликає update_option().
Перевірка таблиці wp_options покаже лише поточне значення, але не пояснить, хто його перезаписав. Для цього можна тимчасово підключити MU-плагін із фільтром pre_update_option_імʼя_опції. Він запише момент зміни та ланцюжок викликів PHP, за яким зазвичай вдається знайти джерело проблеми.
Чому опції WordPress змінюються без очевидної причини
Опції зберігають глобальні налаштування WordPress, плагінів і тем. Під час збереження зазвичай використовується функція update_option(), але зміна може відбуватися всередині іншого коду: після збереження форми, синхронізації налаштувань, імпорту, авторизації користувача або виконання cron.
Плагін може не просто один раз записати значення під час активації. Він може перевіряти опцію на кожному запиті й виправляти її, якщо вважає поточне значення неправильним. Інший поширений сценарій — сторінка налаштувань передає неповний масив, а код плагіна зберігає його поверх попереднього, втрачаючи частину параметрів.
Найчастіші джерела таких змін:
• плагін із власною сторінкою налаштувань; • дочірня або кастомна тема; • WP-Cron, Action Scheduler чи інший планувальник; • імпорт або міграція сайту; • REST API, AJAX-запит або CLI-команда; • callback, підключений через update_option або інший фільтр; • код, який напряму змінює таблицю бази даних.
Що перевірити до встановлення трасування
Спочатку переконайтеся, що змінюється саме та опція, яку ви відстежуєте. Назва в таблиці wp_options може відрізнятися від назви поля у формі налаштувань. Для масивів також важливо відрізняти всю опцію від окремого ключа всередині неї: WordPress зберігає масив як одне значення.
Порівняйте час зміни з подіями на сайті. Якщо значення змінюється лише в певний час, підозрюйте cron або зовнішню інтеграцію. Якщо це відбувається одразу після відкриття сторінки налаштувань, імовірний код самої сторінки або автоматична перевірка конфігурації.
Корисно тимчасово зафіксувати:
• точну назву опції; • старе та очікуване значення; • URL або дію, після якої відбувається зміна; • чи повторюється проблема в адміністративній частині, на фронтенді або лише в cron; • які плагіни чи тему нещодавно оновлювали або налаштовували.
Як підключити MU-плагін для трасування
Створіть файл trace-option.php у каталозі wp-content/mu-plugins/. MU-плагіни завантажуються автоматично й не потребують активації через адміністративну панель. Якщо каталогу mu-plugins немає, його можна створити вручну.
У прикладі нижче замініть my_option на реальну назву опції. Пріоритет 999 потрібен для того, щоб побачити значення після більшості інших фільтрів. Трасер не змінює дані — він лише повертає нове значення далі за ланцюжком.
Код навмисно не записує старе та нове значення. В опції можуть бути паролі, токени, ключі API або персональні дані, тому для первинної діагностики достатньо назви опції та backtrace.
Переконайтеся, що журнал помилок PHP або WordPress увімкнений у контрольованому середовищі. Якщо error_log() не записує повідомлення, перевірте налаштування логування хостингу та WP_DEBUG_LOG.
<?php
$trace_option = 'my_option';
add_filter(
'pre_update_option_' . $trace_option,
function ($new_value, $old_value, $option_name) {
if ($new_value === $old_value) {
return $new_value;
}
$request_uri = isset($_SERVER['REQUEST_URI'])
? $_SERVER['REQUEST_URI']
: 'CLI/cron';
error_log(sprintf(
'[option-trace] Changed %s; request=%s; backtrace=%s',
$option_name,
$request_uri,
wp_debug_backtrace_summary()
));
return $new_value;
},
999,
3
);
Як читати запис у журналі
Після встановлення трасера повторіть дію, яка спричиняє проблему: відкрийте потрібну сторінку, збережіть налаштування або дочекайтеся виконання запланованого завдання. Потім знайдіть у журналі рядок із міткою [option-trace].
Функція wp_debug_backtrace_summary() повертає скорочений ланцюжок викликів. У ньому можуть бути назви функцій, методів класів і файлів, які привели до update_option(). Якщо серед них видно префікс конкретного плагіна, назву його класу або callback зі зрозумілим іменем, це головний кандидат на перевірку.
Backtrace не завжди прямо показує рядок коду, який записав значення. Він може показати лише шлях до update_option(), особливо якщо зміна відбулася через абстракцію налаштувань. У такому випадку:
• знайдіть у коді плагіна всі виклики update_option() і delete_option(); • пошукайте назву опції у всьому каталозі плагіна; • перевірте callback-и на admin_init, init, rest_api_init, wp_ajax_* та cron-хуки; • подивіться, чи не викликається збереження в обробнику сторінки налаштувань; • порівняйте пріоритети callback-ів, якщо опцію змінюють кілька компонентів.
Що робити, якщо трасер нічого не показує
Фільтр pre_update_option_імʼя_опції спрацьовує під час оновлення вже наявної опції через стандартний Options API. Він не охоплює всі можливі способи зміни даних, тому відсутність запису не означає, що проблема зникла.
Перевірте такі варіанти:
• значення додається вперше через add_option(), а не оновлюється через update_option(); • змінюється site option у мережевій інсталяції, для якої потрібні фільтри pre_update_site_option_*; • код виконує прямий SQL-запит до wp_options; • ви трасуєте неправильну назву опції; • змінюється не сама опція, а кеш, transient або значення в іншому сховищі; • запис у журналі потрапляє в інший файл, наприклад у лог PHP-FPM, вебсерверу або CLI-процесу.
Для першого створення опції можна додатково перевірити фільтр pre_add_option_імʼя_опції. Для мережевих налаштувань WordPress використовуйте відповідні site option hooks. Якщо є підозра на прямий SQL, пошукайте в коді $wpdb->update(), $wpdb->query() та згадку таблиці options.
Типові помилки під час діагностики
Не варто одразу забороняти зміну, повертаючи старе значення з фільтра. Такий підхід може приховати проблему, зламати збереження легітимних налаштувань або спричинити повторні спроби запису. Спочатку встановіть джерело, а блокування використовуйте лише як короткочасний аварійний захід.
Також не слід виводити в журнал повні значення опції без маскування. Великі серіалізовані масиви швидко збільшують лог, а вміст може містити секрети. Якщо порівняння значень необхідне, записуйте лише тип, розмір масиву, хеш або окремі безпечні ключі.
Інша помилка — залишити MU-плагін на production після завершення перевірки. Backtrace створюється під час кожної зміни, а інтенсивне логування може збільшити навантаження та розмір файлів. Після отримання доказів видаліть файл або вимкніть код і очистьте тимчасові журнали відповідно до політики безпеки.
Як виправити першопричину
Коли винний компонент знайдений, перевірте логіку, яка формує нове значення. Часто проблема не в самому update_option(), а в тому, що код передає неповний масив, застосовує значення за замовчуванням на кожному запиті або вважає порожнє значення ознакою пошкодженої конфігурації.
Для налаштувань-масивів безпечніше спочатку отримати поточну опцію, змінити лише потрібний ключ і зберегти результат. Під час обробки форм перевіряйте дозволені поля, типи даних і права користувача. Не запускайте запис на кожному запиті без необхідності — оновлюйте опцію лише тоді, коли значення справді змінилося.
Якщо причиною є сторонній плагін, перевірте його оновлення, відомі помилки та сумісність. На staging-середовищі можна тимчасово вимкнути підозрілий компонент і повторити сценарій. Якщо проблема зникає, виправлення краще внести в плагін, його конфігурацію або власний інтеграційний код, а не маскувати симптом фільтром.
Поширені запитання
Чи можна трасувати всі зміни опцій одразу?
Технічно можна підключити загальний фільтр pre_update_option, але на активному сайті це створить багато шуму та записів у журналі. Краще почати з конкретної опції, яка змінюється неочікувано.
Чи покаже backtrace точний плагін, який змінив опцію?
У багатьох випадках так: у ланцюжку видно функції, методи або файли плагіна. Проте backtrace може бути скороченим і не завжди містить точний рядок коду, тому результат потрібно підтвердити пошуком назви опції та викликів update_option().
Чому значення змінюється, але фільтр не спрацьовує?
Можливо, використовується add_option(), update_site_option(), прямий SQL-запит або змінюється інше сховище. Також перевірте назву опції, процес cron і файл, у який записуються повідомлення.
Чи безпечно залишати цей MU-плагін на production?
Лише на короткий час і з обмеженим логуванням. Backtrace може містити внутрішні назви класів, шляхи та контекст запиту, а часті записи збільшують навантаження. Після діагностики трасер потрібно видалити.
Висновок
Для пошуку неочікуваних змін опцій не обовʼязково одразу аналізувати всю базу даних. Тимчасовий фільтр pre_update_option_імʼя_опції дає змогу побачити момент запису та контекст, у якому він відбувся.
Використовуйте трасування як діагностичний інструмент: знайдіть компонент, перевірте його логіку, виправте формування значення й видаліть MU-плагін після завершення перевірки. Це надійніше, ніж безумовно блокувати оновлення опції та залишати справжню причину несправності прихованою.