Дебаг у WordPress

У розробці потрібно мати можливість дивитися, де помилка, коли щось раптом зламалося. У WordPress для цього є спеціальний режим “дебаг” (режим налагодження). У цій нотатці розберемо його на частини і подивимося, що це за константа така WP_DEBUG.

Навіщо потрібний «дебаг режим»?

Допустимо, ви змінили код файлу functions.php теми і сайт перестав працювати. Замість нього білий екран – нічого не зрозуміло. «дебаг» допоможе розібратися, він покаже помилку і скаже в якому вона рядку якогось файлу.

«Дебаг» виводить не лише помилки, через які сайт перестає працювати, а й нотатки. Нотатки можуть створюватися самим PHP (наприклад, коли неправильно використовується змінна) або кодом PHP скрипта (наприклад, WP створює такі нотатки, якщо сайт використовує застарілу функцію WordPress або застарілий параметр функції).

Читайте також

Зміст:

Є два варіанти режиму «дебаг»:

  1. WP_DEBUG_DISPLAY— Константа показу помилок на екрані.
  2. WP_DEBUG_LOG– Константа запис помилок у лог файл.

Сам «дебаг» режим включається константою WP_DEBUG.

Всі три константи можуть набувати значення true або false.

За умовчанням константи дебага мають такі значення:

  • WP_DEBUG = false ( true при 'development' === wp_get_environment_type())
  • WP_DEBUG_DISPLAY = true
  • WP_DEBUG_LOG = false

Усі константи можуть бути визначені у файлі wp-config.php або визначаються функцією завантаження WordPress .

WP_DEBUG_DISPLAYі WP_DEBUG_LOGактивуються, лише якщо увімкнено константу WP_DEBUG.

Увімкнення WP_DEBUGне змінює значення інших констант. Тобто. при WP_DEBUG=true WP_DEBUG_DISPLAY та WP_DEBUG_LOG збережуть свої дефолтні значення і на основі цих значень будуть виставлені PHP налаштування показу та логування помилок.

Функція wp_debug_mode() встановлює налаштування PHP на основі встановлених констант.

Показ помилок завжди відключений для AJAX запитів, там побачити помилки можна тільки через файл лог. Це встановлюється в wp_debug_mode() :

if ( defined( 'XMLRPC_REQUEST' ) || defined( 'REST_REQUEST' ) || ( defined( 'WP_INSTALLING' ) && WP_INSTALLING ) || wp_doing_ajax() ) {
	@ini_set('display_errors', 0);
}

Як увімкнути показ помилок в AJAX запиті, зморіть у статті про AJAX .

Використовуйте wp_get_environment_type() , щоб керувати середовищем розробки.

Важливо відключати “дебаг” на робочому сайті.


Як увімкнути «дебаг» (показ помилок у WordPress)


Базове включення

Відкрийте файл wp-config.php у корені сайту та змініть false на true у рядку:

define( 'WP_DEBUG', true ); // false - вимкнути показ помилок

При такому включенні помилки та нотатки виводитимуться на екран, але нічого логуватися не буде.


Увімкнення та налаштування дебагу

Код нижче, включить запис помилок, попереджень та нотаток у файл wp-content/debug.log та вимкне показ нотаток та попереджень на екрані, щоб вони не заважали під час перегляду сайту.

define( 'WP_DEBUG', true ); // Включення дебаг режиму
define( 'WP_DEBUG_LOG', true ); // true - логування помилок у файлі /wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // false – відключає показ помилок на екрані
define( 'SCRIPT_DEBUG', true ); // використовуємо повні версії JS і CSS файлів движка

Вставляти цей код потрібно у файл wp-config.php куди завгодно, але до рядка:

require_once(ABSPATH. 'wp-settings.php');

Завдяки коду вище було включено логування помилок у файл. Цим можна скористатися для запису вмісту змінних у файл:

error_log($ value); // Скалярні величини
error_log (print_r ($ value, 1)); // Будь-які дані


Динамічне ввімкнення показу помилок

Цей код допомагає швидко включати константу WP_DEBUG , яка має бути вимкнена на робочому сайті. Також код дозволяє включити запис помилок у файл debug.log до папки /wp-content та вимкнути показ помилок на екрані.

Для чого це треба? Припустимо, ми зробили сайт і на бойовому сайті нам іноді потрібно бачити помилки (зазвичай, звичайно, все це тестується на локалці, але всяке буває потрібно). Щоб бачити причину помилки, нам потрібно включити дебаг, але на бойовому сайті, де ходять користувачі, робити цього не рекомендується. За допомогою коду нижче можна ввімкнути дебаг режим WordPress через URL, знаючи певний ключ.

Увімкнення помилок зберігається в куку.

Встановлення

Замініть рядок define( WP_DEBUG, false );у файлі wp-config.php на такий код:

GitHub

<?php

/**
 * Dynamically enable/disable the display of PHP errors в WordPress.
 *
 * Installation:
 * replace line 'define( WP_DEBUG, false );' in 'wp-config.php' file with this code.
 *
 * Enabling debug mode:
 * NOTE: Значно recommended до зміни 'розповсюдження' слово до деяких більше unique!
 * add the 'debug' query parameter to the URL. Examples:
 * https://site.com/?debug - default enabling of WP_DEBUG constant
 * https://site.com/?debug=1 - logging of errors in file 'DOCUMENT_ROOT/../php-errors-{HOST}.log'.
 * https://site.com/?debug=2 - linking uncompressed scripts and saving all SQL queries to $wpdb->queries
 * https://site.com/?debug=3 - saving all SQL queries in $wpdb->queries
 * https://site.com/?debug=4 - disable displaying errors (enabled by default)
 * https://site.com/?debug=14 - combining
 *
 * Disabling debug mode:
 * https://site.com/?debug=d or ?debug=del
 *
 * @author Kama (http://wp-kama.ru)
 * ver 2.4
 */
// IMPORTANT: зміна від `debug` до вашого unique key!
kama_define_wp_debug('debug');

function kama_define_wp_debug( $key ){

	$val = isset( $_GET[$key] )
		? ( ( empty( $_GET[ $key ] ) && $_GET[ $key ] !== '0' ) ? 'yes' : $_GET[ $key ] )
		: ( isset( $_COOKIE[ $key ] ) ? $_COOKIE[ $key ] : null );

	if( $val || '0' === $val ){
		if( preg_match( '/d|del|0/u', $val ) ) $cookie = ''; // delete cookie
		elseif( preg_match( '/yes|[1234]/', $val ) ) $cookie = $val;

		// Потрібно налаштувати або виконати cookie
		if( isset( $cookie ) ){
			$host = str_replace( 'www.', '', $_SERVER['HTTP_HOST'] );

			// cirilic domains: .сайт, .онлайн, .діти, .ком, .орг, .рус, .укр, .москва, .випробування, .бг
			false !== strpos( $host, 'xn--' )
				? preg_match( '~xn--[^.]+.xn--[^.]+$~', $host, $mm )
				: preg_match( '~[a-z0-9][a-z0-9-]{1,63}.[az.]{2,6}$~', $host, $mm);

			$host = $mm[0];

			$_COOKIE[ $key ] = $cookie;
			setcookie( $key, $cookie, time() + ( $cookie ? 3600*24*365 : -3600 ), '/', ".$host" );
		}
	}

	// enable the debug based on the cookie
	if( ! empty( $_COOKIE[ $key ] ) )){

		define( 'WP_DEBUG', true );

		$set = array_flip( preg_split( '/(d)/', $_COOKIE[$key], -1, PREG_SPLIT_DELIM_CAPTURE | PREG_SPLIT_NO_EMPTY ) );

		isset( $set[1] ) && define( 'WP_DEBUG_LOG', dirname($_SERVER['DOCUMENT_ROOT']) ."/php-errors-{$_SERVER['HTTP_HOST']}.log" );
		isset( $set[2] ) && define( 'SCRIPT_DEBUG', true );
		isset( $set[3] ) && define( 'SAVEQUERIES', true );
		isset( $set[4] ) && define( 'WP_DEBUG_DISPLAY', false );
	}
	else {
		define( 'WP_DEBUG', false );
	}
}

Тепер, щоб увімкнути режим WP_DEBUG , потрібно додати в будь-який URL сайту параметр запиту debug : http://example.com/?debug або http://example.com/?debug=1 (примусове виведення на екран, якщо такий виключення вимкнено ) або http://example.com/?debug=2 (логування у файл).

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

При включенні логування, не забувайте видаляти файл лог, а то його може подивитися хто завгодно. Або шлях до файлу лога можна змінити див. WP_DEBUG_LOG .


WP_DEBUG

WP_DEBUG – це PHP константа (глобальна постійна – визначається лише один раз). Значення цієї постійної включає або відключає показ помилок у PHP, а також вона використовується в різних місцях коду WordPress для показу чи придушення помилок, де це необхідно.

WP_DEBUG потрібно визначати (встановлювати) у файлі wp-config.php із кореня сайту.

define( 'WP_DEBUG', false ); // дебаг вимкнено. За замовчуванням.
// або
define( 'WP_DEBUG', true ); // дебаг включений

Для зручності можна писати числа 1 або 0:

define( 'WP_DEBUG', 0); // дебаг вимкнено. За замовчуванням.
// або
define( 'WP_DEBUG', 1); // дебаг включений

Примітка: не можна вказувати false у лапках – ‘false’ . У цьому випадку дебаг буде включений, тому що значення дорівнює рядку false, а не логічному – ні.

PHP помилки, попередження та нотатки (errors, warnings та notices)

У PHP є різні рівні помилок. Якщо не вдаватися до подробиць, то рівні значущості такі:

  1. errors– Серйозна помилка, яка призводить до зупинки скрипта. PHP перериває роботу.
  2. warnings– не помилка, а попередження про щось. PHP не перериває роботу.
  3. notices– не помилка, а замітка про щось. PHP не перериває роботу. Нотатки можуть показати можливі баги у коді. Їхнє виправлення, як правило, робить код більш стабільним.

Режим дебаг включає всі рівні помилок. Це не схоже на звичайну поведінку PHP, там зазвичай включені лише помилки рівня errors, а warnings та notices не відображаються. Докладніше читайте в описі error_reporting() .

Застарілі функції, хуки та застарілі параметри функцій

WP_DEBUG також включає внутрішні нотатки самого WordPress. У WordPress є спеціальні функції типу _deprecated_function() , які показують помилку рівня notices, коли використовується застаріла функція або хук або параметр хука, функції і т.д. Ці нотатки попереджають, що функція WP вважається застарілою і її потрібно замінити, тому що вона будь-коли може бути видалена. У таких нотатках найчастіше пропонується альтернативна функція для заміни.


WP_DEBUG_DISPLAY

Типово: true .

Ще один компонент WP_DEBUG , який контролює виведення (показ) помилок на екран.

Залежить від WP_DEBUG ! Працює тільки якщо дебаг включений WP_DEBUG = true. В іншому випадку просто використовується глобальне значення PHP опції display_errors .

Якщо вказати у wp-config.php :

  • define( 'WP_DEBUG_DISPLAY', true )— (за замовчуванням) WP виводить (показуватиме) помилки на екран.
  • define( 'WP_DEBUG_DISPLAY', false )– помилки не виводитимуться на екран. Це потрібно, коли помилки записуються у файл (див. WP_DEBUG_LOG ) і їх можна дивитися пізніше.
  • define( 'WP_DEBUG_DISPLAY', null )– WP взагалі не вказуватиме значення для PHP опції display_errors , тобто. буде використано глобальне налаштування PHP (сервера).

Показ помилок завжди відключається для запитів REST, AJAX або XML-RPC. Для них спрацьовує такий код ini_set( ‘display_errors’, 0 ) , але значення константи WP_DEBUG_DISPLAY не змінюється!


WP_DEBUG_LOG

Типово: false

Ще один компонент дебагу. Включає запис помилок у файл /wp-content/debug.log. Залежить від WP_DEBUG – працює тільки якщо WP_DEBUG дорівнює true.

Запис помилок у файл може стати в нагоді, коли потрібно перевірити наявність помилок у коді, який нічого не виводить на екран. Наприклад, при запиті AJAX або при тестуванні CRON або REST.

define( 'WP_DEBUG_LOG', true ); // true - запис помилок у файл /wp-content/debug.log

Зміна адреси файлу лога помилок

Через WP

З WordPress 5.1, в WP_DEBUG_LOG можна вказати шлях до файлу лога:

define( 'WP_DEBUG_LOG', '/srv/path/to/custom/log/location/errors.log' );
Через PHP

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

ini_set( 'error_log', WP_CONTENT_DIR . '/hidden-debug.log' );

Але цей рядок не можна додавати в wp-config.php – це зарано…

Майте на увазі:

  • Кінцева папка в зазначеному шляху повинна існувати та бути доступною для запису.
  • Файла всередині може бути, він буде створено, як тільки станеться перша помилка.


SAVEQUERIES

За замовчуванням: не визначено .

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

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

define( 'SAVEQUERIES', true ); // true - зберігає SQL запити та дані про них у `$wpdb->queries`

Важливо! що включення запису запитів, вимагає додаткової пам’яті та PHP операцій. Тому, з метою продуктивності, на робочому сайті ця константа має бути відключена.


SCRIPT_DEBUG

Типово: false .

Пов’язана із дебагом константа. Контролює, які JS і CSS файли використовувати: стислі або повні. При включенні WordPress використовуватиме стислі версії (dev версії) JS та CSS файлів. За промовчанням використовуються min версії файлів. Це потрібно для тестування під час зміни вбудованих js або css файлів.

define( 'SCRIPT_DEBUG', true ); // true - використання повних версій `.css` та `.js` файлів


Як працює WP_DEBUG?

Після встановлення констант дебагу в wp-config.php ми заходимо на сайт. І при генерації сторінки, на початку завантаження WordPress (див. wp_debug_mode() . Вона, використовуючи функції PHP, встановлює, як і які рівні помилок показувати, чи потрібно створювати лог файл і т.д.


Чи не працює WP_DEBUG?

Іноді може виникнути така ситуація, коли ви включаєте WP_DEBUG у конфізі, а помилки все одно не видно. Така поведінка може виникнути, коли десь після встановлення параметрів показу помилок самим WordPress ці установки змінюються. Наприклад, у MU плагіні, звичайному плагіні або в темі, помилки вимикаються переустановкою ini директив PHP, приблизно таким кодом:

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

У цьому випадку установки дебага WP перебиваються і він перестає працювати.

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

В якості іншого рішення можна спробувати ще раз перебити параметри виведення помилок, вказавши їх знову:

error_reporting(E_ALL); // Включаємо повідомлення про помилки
ini_set('display_errors', 1); // Включаємо показ помилок на екран


Функції WP для дебагу

  • wp_debug_backtrace_summary() — Отримує трасування з назвами функцій — список назв усіх функцій/методів, які були викликані для того, щоб дістатися поточного місця в коді (звідки була викликана ця функція).
  • wp_get_environment_type() — Отримує поточний тип оточення: local , development , staging , production (за замовчуванням).


Дані системи

Для дебагу WP є клас WP_Debug_Data . Наприклад, використовуючи наступний метод, ми можемо отримати купу даних про систему:

require_once ABSPATH. '/wp-admin/includes/class-wp-debug-data.php';
require_once ABSPATH. '/wp-admin/includes/update.php';
require_once ABSPATH. '/wp-admin/includes/misc.php';

$data = WP_Debug_Data::debug_data();

print_r ($ data);

Отримаємо великий масив даних:

Array
(
	[wp-core] => Array
		(
			[label] => WordPress
			[fields] => Array
				(
					[version] => array( data )

					[site_language] => array( data )

					[user_language] => array( data )

					[timezone] => array( data )

					[home_url] => array( data )

					[site_url] => array( data )

					[permalink] => array( data )

					[https_status] => array( data )

					[multisite] => array(data)

					[user_registration] => array( data )

					[blog_public] => array( data )

					[default_comment_status] => array( data )

					[environment_type] => array( data )

					[user_count] => array( data )

					[dotorg_communication] => array( data )

				)

		)

	[wp-paths-sizes] => Array
		(
			[label] => Directories and Sizes
			[fields] => Array
				(
					[wordpress_path] => array( data )

					[wordpress_size] => array( data )

					[uploads_path] => array( data )

					[uploads_size] => array( data )

					[themes_path] => array(data)

					[themes_size] => array( data )

					[plugins_path] => array( data )

					[plugins_size] => array( data )

					[database_size] => array( data )

					[total_size] => array( data )

				)

		)

	[wp-dropins] => Array
		(
			[label] => Drop-ins
			[show_count] => 1
			[description] => Помилка є одними файлами, що знаходяться в /public_html/assets directory, що заміна або розширення WordPress features in ways that not possible for traditional plugins.
			[fields] => Array
				(
					[maintenance.php] => array(data)

					[object-cache.php] => array( data )

				)

		)

	[wp-active-theme] => Array
		(
			[label] => Active Theme
			[fields] => Array
				(
					[name] => array( data )

					[version] => array( data )

					[author] => array( data )

					[author_website] => array( data )

					[parent_theme] => array( data )

					[theme_features] => array(data)

					[theme_path] => array(data)

					[auto_update] => array( data )

				)

		)

	[wp-parent-theme] => Array
		(
			[label] => Parent Theme
			[fields] => Array( data )
		)

	[wp-themes-inactive] => Array
		(
			[label] => Inactive Themes
			[show_count] => 1
			[fields] => Array
				(
					[Dummy] => array( data )

				)

		)

	[wp-mu-plugins] => Array
		(
			[label] => Must Use Plugins
			[show_count] => 1
			[fields] => Array
				(
					[disable-plugins-in-front.php] => array( data )

					[main.php] => array( data )

					[not_support_browsers_redirect.php] => array( data )

					[POMOdoro Translation Cache] => array( data )

					[protect-malicious-queries.php] => array( data )

					[Rus to Lat] => array( data )

				)

		)

	[wp-plugins-active] => Array
		(
			[label] => Active Plugins
			[show_count] => 1
			[fields] => Array
				(
					[AJAX Simply] => array( data )

					[Democracy Poll] => array( data )

					[Disable Emojis (GDPR friendly)] => array( data )

					[Display Active Plugins First] => array( data )

					[Kama Breadcrumbs] => array( data )

					[Kama Postviews] => array( data )

					[Kama SpamBlock] => array(data)

					[Kama Thumbnail Pro] => array( data )

					[Redis Object Cache] => array(data)

				)

		)

	[wp-plugins-inactive] => Array
		(
			[label] => Inactive Plugins
			[show_count] => 1
			[fields] => Array
				(
					[404 Error Monitor] => array( data )

					[Category Order and Taxonomy Terms Order] => array( data )

					[Contact Form 7] => array( data )

					[Kama Thumbnail] => array( data )

					[Query Monitor] => array( data )

					[Query Monitor Extend] => array( data )

					[Right Now Reloaded] => array( data )

					[Three Column Screen Layout] => array( data )

					[TinyPNG - JPEG, PNG & WebP зображення зображення] => array( data )

					[User Role Editor] => array( data )

					[Widget Logic] => array( data )

					[WooCommerce] => array( data )

					[WordPress Sphinx Search Plugin] => array( data )

					[WP Crontrol] => array(data)

					[WP Super Cache] => array(data)

					[Yoast SEO] => array( data )

				)

		)

	[wp-media] => Array
		(
			[label] => Media Handling
			[fields] => Array
				(
					[image_editor] => array( data )

					[imagick_module_version] => array( data )

					[imagemagick_version] => array( data )

					[imagick_version] => array( data )

					[file_uploads] => array( data )

					[post_max_size] => array( data )

					[upload_max_filesize] => array( data )

					[max_effective_size] => array(data)

					[max_file_uploads] => array( data )

					[imagick_limits] => Array (data)

					[imagemagick_file_formats] => Array( JPEG, JPG, MOV, MP4, MPEG, MPG, PNG, PNG24, WBMP, WEBP, WMV ...)

					[gd_version] => array( data )

					[gd_formats] => array( data )

					[ghostscript_version] => array( data )

				)

		)

	[wp-server] => Array
		(
			[label] => Server
			[description] => Опції показують нижче, ніж ваш сервер setup. Якщо зміни потрібні, ви можете знайти свій web host's assistance.
			[fields] => Array
				(
					[server_architecture] => array( data )

					[httpd_software] => array( data )

					[php_version] => array( data )

					[php_sapi] => array( data )

					[max_input_variables] => array(data)

					[time_limit] => array( data )

					[memory_limit] => array(data)

					[max_input_time] => array( data )

					[upload_max_filesize] => array( data )

					[php_post_max_size] => array( data )

					[curl_version] => array( data )

					[suhosin] => array( data )

					[imagick_availability] => array( data )

					[pretty_permalinks] => array(data)

				)

		)

	[wp-database] => Array
		(
			[label] => Database
			[fields] => Array
				(
					[extension] => array( data )

					[server_version] => array( data )

					[client_version] => array( data )

					[database_user] => array( data )

					[database_host] => array( data )

					[database_name] => array( data )

					[database_prefix] => array( data )

					[database_charset] => array( data )

					[database_collate] => array(data)

				)

		)

	[wp-constants] => Array
		(
			[label] => WordPress Constants
			[description] => Ці налаштування ще раз, де і як частини WordPress є завантажені.
			[fields] => Array
				(
					[ABSPATH] => array( data )

					[WP_HOME] => array( data )

					[WP_SITEURL] => array( data )

					[WP_CONTENT_DIR] => array( data )

					[WP_PLUGIN_DIR] => array( data )

					[WP_MEMORY_LIMIT] => array( data )

					[WP_MAX_MEMORY_LIMIT] => array( data )

					[WP_DEBUG] => array( data )

					[WP_DEBUG_DISPLAY] => array( data )

					[WP_DEBUG_LOG] => array( data )

					[SCRIPT_DEBUG] => array( data )

					[WP_CACHE] => array( data )

					[CONCATENATE_SCRIPTS] => array( data )

					[COMPRESS_SCRIPTS] => array( data )

					[COMPRESS_CSS] => array( data )

					[WP_LOCAL_DEV] => array( data )

					[DB_CHARSET] => array( data )

					[DB_COLLATE] => Array
						(
						)

				)

		)

	[wp-filesystem] => Array
		(
			[label] => Filesystem Permissions
			[description] => Покази, які WordPress є можливим для отримання до повідомлень, які потребують доступу до.
			[fields] => Array
				(
					[wordpress] => array( data )

					[wp-content] => array( data )

					[uploads] => array( data )

					[plugins] => array( data )

					[themes] => array( data )

					[mu-plugins] => array( data )

				)

		)

)


Плагіни для дебагу та профілювання в WordPress

У каталозі WP є кілька хороших плагінів, які розширюють можливості “дебагу” і дають додаткову інформацію для виявлення слабких місць коду. Популярні з них:

  • Query Monitor – виводить у підвалі купу корисної інформації про поточний запит. Скільки часу витрачено, скільки SQL запитів, які запити, скільки часу зайняв кожен запит, скільки затрачено пам’яті, які хуки використовувалися і т.д.

  • Debug Bar – комплекс плагінів з дебагінгу та профілювання. Це основний плагін, після встановлення до нього можна підключати ще інші плагіни, які розширюють можливості профілювання. Але я його якось не оцінив…

  • Log Deprecated Notices – записує в балку всі нотатки про наявність застарілих функцій WordPress або їх параметрів і т.д. Не залежить від WP_DEBUG – працює з вимкненим WP_DEBUG.

  • WordPress mu-plugin for debugging – альтернативний дебаггер на базі бібліотеки Kint .

  • Clockwork для WordPress – виводить будь-яку налагоджувальну інформацію в консоль браузера Google Chrome або Firefox, працює на основі браузерного розширення Clockwork, щоб мати можливість передавати дані із сервера на клієнт. Є можливість налагодження AJAX-запитів.

Залишити відповідь

Ваша e-mail адреса не оприлюднюватиметься. Обов’язкові поля позначені *