Дебаг в 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.

wp_initial_constants() определяет дефолтные значения констнат, если они не установлены вручную. Функция срабатывает на раннем этапе загрузки WordPress.

wp_debug_mode() устанавливает настройки PHP на основе установленных констант.

WP_DEBUG_DISPLAY и WP_DEBUG_LOG активируются, только если включена константа WP_DEBUG.

Включение WP_DEBUG не изменяет значение других констант. Т.е. при WP_DEBUG=true WP_DEBUG_DISPLAY и WP_DEBUG_LOG сохранят свои дефолтные значения и на основе этих значений будут выставлены PHP настройки показа и логирования ошибок.

Используйте wp_get_environment_type(), для управления средой разработки.

Отображение ошибок форсировано отключено для AJAX/REST/XMLRPC/JSONP запросов. См. код wp_debug_mode():

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

Как включить показ ошибок в AJAX запросе, сморите в статье про AJAX.

Важно отключать «дебаг» на рабочем сайте.

Как включить «дебаг» (показ ошибок в 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 in WordPress.
 *
 * Installation:
 * replace line 'define( WP_DEBUG, false );' in 'wp-config.php' file with this code.
 *
 * Enabling debug mode:
 * NOTE: Strongly recommended to changing the 'debug' word to something more 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 into 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=anything
 *
 * @author Kama (http://wp-kama.ru)
 * ver 2.5
 */
// IMPORTANT: change from `debug` to your unique key!
kama_define_wp_debug( 'debug' );

function kama_define_wp_debug( $key ){

	$val = isset( $_GET[ $key ] ) ? ( $_GET[ $key ] ?: 'yes' ) : false;

	// set/delete cookie
	if( $val !== false ){

		$cookie = preg_match( '/^(yes|[1234])$/', $val ) ? $val : null;

		$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}.[a-z.]{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

C 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-settings.php) срабатывает функция 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] => Drop-ins are single files, found in the /public_html/assets directory, that replace or enhance WordPress features in ways that are 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 image compression] => 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] => The options shown below relate to your server setup. If changes are required, you may need your 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] => These settings alter where and how parts of WordPress are loaded.
			[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] => Shows whether WordPress is able to write to the directories it needs access to.
			[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-запросов.