Lesson 1.3. Debugging: WP_DEBUG, Logs and Xdebug

A white screen and a var_dump() on production

The checkout page is blank. Someone adds var_dump( $order ); to the plugin on the live site to see what is going on. Customers now see a dump of order data above the header. The error itself is still unknown, because WP_DEBUG is off and nothing was logged.

WordPress already has a place for errors. It is just switched off by default.

Goal

Turn on logging without showing errors to visitors, read debug.log, and debug locally with Xdebug instead of var_dump().

Key concepts

flowchart LR
  E["PHP warning · notice · fatal"] --> D{"WP_DEBUG"}
  D -- "false" --> N["Nothing recorded"]
  D -- "true" --> L["WP_DEBUG_LOG<br/>wp-content/debug.log"]
  D -- "true" --> S["WP_DEBUG_DISPLAY<br/>on screen (local only)"]
  • WP_DEBUG turns on PHP error reporting inside WordPress. Off by default.
  • WP_DEBUG_LOG: true writes to wp-content/debug.log; a path writes to that file instead (keep it outside the web root on production).
  • WP_DEBUG_DISPLAY shows errors in the page. true by default when WP_DEBUG is on, so set it to false anywhere but your own machine.
  • error_log() writes your own messages to the same log; wp_json_encode() or print_r( $x, true ) turns arrays and objects into text.
  • Xdebug 3 pauses PHP on a breakpoint in your IDE: xdebug.mode=debug, port 9003. Local only, it slows every request.

Commands / artifacts

PHP
// wp-config.php on a staging or production site
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', '/var/log/my-site/debug.log' ); // outside the web root
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', '0' );
PHP
// Your own log line instead of var_dump()
error_log( 'my-plugin: order ' . $order_id . ' ' . wp_json_encode( $payload ) );
BASH
wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw
wp config set WP_DEBUG_DISPLAY false --raw
tail -n 20 wp-content/debug.log
TEXT
; php.ini or conf.d/xdebug.ini (local only)
xdebug.mode = debug
xdebug.start_with_request = trigger
xdebug.client_port = 9003

Common mistakes

SymptomCauseFix
Visitors see warnings at the top of the pageWP_DEBUG_DISPLAY left at its default trueWP_DEBUG_DISPLAY false and display_errors 0 outside local
https://site.com/wp-content/debug.log opens in the browserThe log is in the public folderA path outside the web root, or deny access in the server config
Nothing in debug.logWP_DEBUG is false, or the log file is not writableTurn on both constants; check folder permissions
var_dump() / die() left in a commitDebugging by printingerror_log() for logs, Xdebug breakpoints locally
Every page takes seconds locallyXdebug in start_with_request=yes mode all the timetrigger mode, start it only when you debug

WPCS

var_dump(), print_r() without true and error_log() left in production code are flagged by the WordPress Coding Standards (WordPress.PHP.DevelopmentFunctions). Log through a wrapper you can switch off, not with bare calls.

Practice

Turn on the debug log without on-screen errors, trigger a warning in a plugin and read it in debug.log.

php — Module 1. PHP Runtime in WordPress

Interview Questions

Turn on WP_DEBUG and WP_DEBUG_LOG with WP_DEBUG_DISPLAY off, reproduce the request and read the log. Since WordPress 5.2 a fatal error in a plugin or theme also triggers recovery mode and an email to the admin with the error and the file.

WP_DEBUG_LOG writes errors to a file (wp-content/debug.log or a custom path). WP_DEBUG_DISPLAY prints them into the page. On any site with visitors you log and never display.

Xdebug pauses execution at a breakpoint and shows every variable and the call stack, without editing code or printing data into the page. var_dump() changes the output, shows one value at a time and tends to end up in commits.

Save your progress

Sign in or create a free account to mark lessons as completed and continue the whole course. You will come back to this lesson.