Відлагодження (debugging) коду WordPress

Привіт:) У цьому пості покажу інструменти та способи відлагодження коду, які використовую під час розробки WordPress проєктів.

WordPress — це окреме середовище та складна система із великою кількістю коду в багатьох файлах. Різні модулі взаємодіють між собою, викликаючи функціонал один одного. Також ядро ВордПрес містить комплекс інструментів, які дозволяють розширювати стандартні можливості системи, а також розробляти власні рішення (плагіни, теми, блоки Gutenberg-редактора).

Під час розробки виникають помилки, які не завжди вдається одразу виявити. Також буває необхідно зрозуміти логіку роботи якогось функціоналу. Щоб полегшити та пришвидшити процес розробки використовуються різні інструменти відлагодження коду.

Зміст:

Що таке вбудований відлагоджувач (debug) і для чого потрібен
Як увімкнути режим відлагодження WordPress
Якщо не працює WP_DEBUG
Спеціальні WordPress-плагіни для відлагодження
Відлагодження PHP-коду
Логування помилок, повідомлень та попереджень інтерпретатора PHP у файл
Виведення помилок, повідомлень та попереджень інтерпретатора на екран
Поточна версія PHP
Який файл шаблону теми використовується
Трасування з назвами функцій
Отримання усіх додатково зареєстрованих розмірів мініатюр зображень у WordPress
Швидке перемикання між обліковими записами користувачів
Час генерації сторінки та затрачена кількість оперативної пам'яті
Відлагодження JavaScript коду
Режим обслуговування (Maintenance Mode)
Ремонт бази даних WordPress

У цій статті покажу ті, якими користуюся сам.

Що таке вбудований відлагоджувач (debug) і для чого потрібен

Це набір інструментів, які дозволяють переглянути зсередини роботу сайту. Відлагодження можна порівняти з рентгеном або аналізом крові, які допомагають дізнатися причину хвороби.

Debug-режим найчастіше використовують, щоб з'ясувати, чому не працює (або працює не так, як потрібно) той чи інший функціонал. Наприклад, що робити, якщо після оновлення теми чи плагіну не вдається увійти до адмін-панелі?

Під час роботи сайту часто трапляються помилки. Це може статися через збій на хостингу, додавання нових або зміни старих функцій, оновлення WP, плагінів. Тому важливо завжди бути в курсі цих помилок, щоб вчасно їх виправити і забезпечити безперебійну роботу веб-ресурсу.

Ще відлагодження необхідне під час розробки плагінів і тем ВордПрес. Воно "примушує" програмістів дотримуватися рекомендованих стандартів, щоб у результаті програмний код був максимально якісним.

Як увімкнути режим відлагодження WordPress

У ядрі WordPress вже вбудований відлагоджувач, але за замовчуванням він вимкнений. Розберу, як із ним працювати.

Зазвичай повідомлення про помилки не повинні виводитися на екрані в користувацькій частині сайту. Це відволікає відвідувачів та ставить під загрозу злому. Зручно список та опис помилок (якщо вони є) отримувати в окремому файлі, доступ до якого має лише адміністратор.

Перед подальшими діями рекомендую створити повну резервну копію сайту.

Перейдіть до кореневого каталогу свого сайту та відкрийте файл wp-config.php.

У рядку

define( 'WP_DEBUG', false );

значення false замініть на true.

Повідомлення про всі помилки з'являтимуться на веб-сайті. Щоб їх приховати від користувачів і зручно помістити в один файл, додайте нижче рядки

define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Щоб усі повідомлення про помилки (логи) збиралися в одному файлі, додайте код

define( 'WP_DEBUG_LOG', true );

Якщо необхідно логувати всі SQL запити, то наступна директива зберігатиме їх у змінну $wpdb->queries як масиву. У цьому масиві можна буде подивитися всі SQL запити сторінки, а також дані про те, скільки часу зайняв запит і якою функцією він був викликаний.

define( 'SAVEQUERIES', true );

SQL-запити зможете повитися за допомогою коду:

global $wpdb; print_r($wpdb->queries);

Збережіть зміни.

Тепер їх усі можна переглянути у /wp-content/debug.log.

Шлях /wp-content/debug.log для розміщення лог-файлу заданий за замовчуванням. Якщо він не влаштовує, то рядок

define( 'WP_DEBUG_LOG', true );

замініть на

define( 'WP_DEBUG_LOG', '/home/public_html/wp-content/wp-errors.log' );

В останньому параметрі задайте власний шлях до файлу помилок.

Повний код:

// Увімкнути режим відлагодження
define( 'WP_DEBUG', true );
// Заборонити виведення помилок на екран
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );
// Увімкнути логування помилок у файлі /wp-content/debug.log
define( 'WP_DEBUG_LOG', true );
// Логувати SQL запити
define( 'SAVEQUERIES', true );

Якщо не працює WP_DEBUG

Іноді директива WP_DEBUG у wp-config.php може не працювати, і помилки не відображатимуться. Причиною може бути перевизначення десь у коді плагінів чи тем параметрів їх показу. Наприклад, помилки можуть бути вимкнені ini-директивами PHP:

error_reporting(0); // вимкнення повідомлень про помилки
ini_set('display_errors', 0); // вимкнення виведення помилок на екран

У цьому випадку режим відлагодження (дебагу) WordPress "перебиваються", і він перестає працювати.

Для вирішення проблеми найкраще знайти де змінюються налаштування та видалити такі рядки, щоб далі працювати лише з константою WP_DEBUG.

Якщо неможливо знайти місце перевизначення, можна спробувати ще раз "перебити" параметри виведення помилок, вказавши їх знову:

error_reporting(E_ALL); // увімкнення повідомлень про помилки
ini_set('display_errors', 1); // увімкнення виведння помилок на екран

Спеціальні WordPress-плагіни для відлагодження

Для ВордПрес існують плагіни, які дозволяють:

контролювати весь процес розробки;
покроково слідкувати за внутрішньою роботою вбудованих у ядро WordPress модулів;
виявляти повільні запити до бази даних;
переглядати взаємодію користувацького коду із вбудованим функціоналом.

Особисто користуюся плагіном Query Monitor (https://wordpress.org/plugins/query-monitor/). У зручному форматі показує наступну інформацію:

запити до бази даних. Повідомляє про повільні або помилкові запити. Дозволяє фільтрувати за типом запиту (SELECT, UPDATE, DELETE і т.п.);
назву файлу-шаблону теми. Видасть повну ієрархію шаблону та назви всіх його частин;
помилки та попередження PHP;
застарілий функціонал у користувацькому коді;
правила перезапису постійних посилань;
під'єднані JavaScript-скрипти й таблиці стилів CSS разом із їх залежностями та сповіщеннями про пошкоджені залежності;
під'єднані файли перекладу;
запити HTTP API з кодом відповіді, часом виконання, попередженнями про невдалі або помилкові запити;
дані про версію PHP, базу даних, ядро WordPress та веб-сервер;
доступні для конкретного розділу сайту значення умовних тегів (таких як is_single(), is_home() і т.п.).

Відлагодження PHP-коду

Для перевірки роботи PHP-скриптів використовую наступні способи.

Логування помилок, повідомлень та попереджень інтерпретатора PHP у файл

Логування у файл /wp-content/debug.log скалярних величин (режим відлагодження WordPress повинен бути увімкнений).

Для цього використовую PHP_функцію error_log():

error_log( $value );

Логування у файл /wp-content/debug.log будь-яких даних:

error_log( print_r( $value, 1 ) );

Виведення помилок, повідомлень та попереджень інтерпретатора на екран

Для цього користуюся PHP-функціями print_r() та var_dump(). Вони виведуть у зручному форматі будь-які дані (рядок, масив, об'єкт, результат роботи функції).

echo '<pre>';
print_r( $value );
echo '</pre>';

echo '<pre>';
var_dump( $value );
echo '</pre>';

Поточна версія PHP

phpversion();

Який файл шаблону теми використовується

Таку інформацію можна дізнатися за допомогою плагіну Query Monitor. Також назву файлу-шаблону можна вивести на екран кодом:

// Варіант 1. Повідомлення будуть виводитися в адмін-барі
add_action( 'admin_bar_menu', function() {
	if ( is_super_admin() ) {
		global $template;
		print_r( $template );
	}
} );


// Варіант 2. Повідомлення будуть виводитися у Футері
add_action( 'wp_footer', function() {
	if ( is_super_admin() ) {
		global $template;
		print_r( $template );
	}
} );


// Варіант 3. Повідомлення у Футері який файл шаблону теми використовується + ID поточного посту
add_action( 'wp_footer', function() {
	if ( is_super_admin() ) {
		global $template;
		echo 'Template Name: ' . $template . "<br>";

		global $wp_query;
		echo 'Post ID: ' . $wp_query->post->ID;
	}
} );

Трасування з назвами функцій

Виведення списку назв усіх функцій/методів, які були викликані для того, щоб дістатися поточного місця в коді (звідки була викликана функція нижче). Список виводиться у вигляді назв функцій через кому або у вигляді масиву.

// Виведення результату роботи функції на екран
print_r( wp_debug_backtrace_summary() ); 

// Виведення результату роботи функції у файл /wp-content/debug.log
error_log( wp_debug_backtrace_summary() );

Отримання усіх додатково зареєстрованих розмірів мініатюр зображень у WordPress

Розміри зображень реєструються ядром WordPress, темами та плагінами.

За замовчуванням у WordPress автоматично створюються декілька розмірів мініатюр: thumbnail, medium, medium_large, large. До цих розмірів можна додавати власні за допомогою функції add_image_size().

Щоб отримати всі додаткові розміри, користуюся наступними способами.

Наприклад, десь у коді теми чи плагіну реєструється окремий розмір мініатюр для картки слайдеру:

add_image_size( 'slider-item-thumb', 250, 250 );

Щоб подивитися цей розмір:

// Спосіб 1
echo '<pre>';
print_r( wp_get_additional_image_sizes() );
echo '</pre>';


// Спосіб 2
global $_wp_additional_image_sizes;
echo '<pre>';
print_r( $_wp_additional_image_sizes );
echo '</pre>';

Результат роботи обох способів:

Array
(
    [slider-item-thumb] => Array
        (
            [width] => 250
            [height] => 250
            [crop] => 
        )

)

Швидке перемикання між обліковими записами користувачів

У процесі розробки плагіну чи теми буває необхідно перевірити роботу того чи іншого функціоналу для різних користувачів. Наприклад, окремо для користувачів з повним доступом і для тих, які мають обмежені права (наприклад, Редактор).

Для цього користуюся безкоштовним модулем User Switching (https://wordpress.org/plugins/user-switching/). Дозволить швидко перемикати між обліковими записами користувачів одним натисканням кнопки. Забезпечує миттєвий вихід із системи та вхід під потрібним користувачем.

Час генерації сторінки та затрачена кількість оперативної пам'яті

У ході робіт з оптимізації швидкості роботи сайту буває потрібно визначити час, протягом якого генерується сторінка, а також кількість оперативної пам'яті, яку витрачає сервер хостингу для цього процесу.

Щоб визначити кількість SQL-запитів до бази даних, час їх виконання та затрачену пам'ять для генерації сторінки, використовую наступний код:

if ( ! function_exists( 'mp_get_resources_usage' ) ) {
    add_filter( 'admin_footer_text', 'mp_get_resources_usage' );
    function mp_get_resources_usage() {
        if ( current_user_can( 'manage_options' ) ) {
            return sprintf(
                'SQL-запити: %d шт. за %.3F сек. %s MB',
                get_num_queries(),
                timer_float(),
                round( memory_get_peak_usage()/1024/1024, 2 )
            );
        }
    }
}

Результатом роботи буде інформація внизу адмін-панелі WordPress:

SQL-запити: 46 шт. за 0.552 сек. 61.37 MB

Щоб додати цю інформацію в адмін-бар:

if ( ! function_exists( 'mp_get_resources_usage' ) ) {
    function mp_get_resources_usage() {
      if ( current_user_can( 'manage_options' ) ) {
        return sprintf(
          'SQL-запити: %d шт. за %.3F сек. %s MB',
          get_num_queries(),
          timer_float(),
          round( memory_get_peak_usage()/1024/1024, 2 )
        );
      }
    }
}

if ( ! function_exists( 'mp_resources_usage_to_admin_bar' ) ) {
    add_action( 'admin_bar_menu', 'mp_resources_usage_to_admin_bar', 99999 );
    function mp_resources_usage_to_admin_bar( $admin_bar ) {
        $args = array(
            'id' => 'mp-resources-usage-info',
            'title' => mp_get_resources_usage(), 
            'href' => ''
        );
        $admin_bar->add_node( $args );
    }
}

Також цю інформацію можна дізнатися за допомогою плагіну Query Monitor.

Відлагодження JavaScript коду

Для контролю та відлагодження коду на JavaScript або jQuery зазвичай користуюся console.log().

Режим обслуговування (Maintenance Mode)

Режим Maintenance Mode у WordPress — це стан, коли сайт тимчасово недоступний для публічного перегляду. Цей режим активується у випадках, коли розробник або адміністратор сайту проводить ремонтні або оновлювальні роботи, такі як зміни у дизайні, оновлення плагінів або тем, чи ж великі оновлення ядра WordPress.

Режим Maintenance Mode потрібен у наступних випадках.

Запобігання проблемам з користувацьким досвідом. Під час оновлень або ремонтних робіт на сайті можуть виникати проблеми з функціональністю або візуальним виглядом. Використання режиму обслуговування дозволяє уникнути поганого враження у відвідувачів, які бачать недороблену або "зламану" версію сайту.
Збереження цілісності даних. В режимі обслуговування доступ до панелі залишається, щоб адміністратор міг проводити роботи безпеки чи оновлення безпосередньо на сайті, але при цьому сайт залишиться недоступним для інших користувачів.
Інформаційне повідомлення. Maintenance Mode надає можливість розмістити повідомлення про те, що сайт наразі недоступний через технічні причини. Це може включати інформацію про те, коли очікується завершення робіт і повернення сайту в робочий стан.
Захист від помилок. В режимі обслуговування сайт недоступний для публічного доступу, що дозволяє уникнути помилок чи конфліктів, які можуть виникнути через те, що користувачі одночасно взаємодіють з сайтом під час оновлення.

У WordPress режим обслуговування можна активувати за допомогою плагінів або PHP-кодом. Після завершення робіт необхідно деактивувати режим обслуговування, щоб сайт знову став доступним для відвідувачів.

Ремонт бази даних WordPress

ВордПрес має вбудовані інструменти для ремонту/відновлення/оптимізації пошкодженої бази даних.

У файлі wp-config.php пропишіть рядок

define('WP_ALLOW_REPAIR', true);

У браузері перейдіть за адресою

site.com/wp-admin/maint/repair.php

У коді замість site.com вкажіть назву домену свого сайту.

На новій сторінці оберіть один із варіантів: Полагодити базу даних або Полагодити і оптимізувати базу даних.

Після закінчення процесу ремонту/оптимізації система видасть відповідне повідомлення.

Видаліть доданий рядок із wp-config.php.

Замітка "Debugging in WordPress" на оф. сайті WordPress — https://developer.wordpress.org/advanced-administration/debug/debug-wordpress/.