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_DEBUGturns on PHP error reporting inside WordPress. Off by default.WP_DEBUG_LOG:truewrites towp-content/debug.log; a path writes to that file instead (keep it outside the web root on production).WP_DEBUG_DISPLAYshows errors in the page.trueby default whenWP_DEBUGis on, so set it tofalseanywhere but your own machine.error_log()writes your own messages to the same log;wp_json_encode()orprint_r( $x, true )turns arrays and objects into text.- Xdebug 3 pauses PHP on a breakpoint in your IDE:
xdebug.mode=debug, port9003. Local only, it slows every request.
Commands / artifacts
// 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' );
// Your own log line instead of var_dump()
error_log( 'my-plugin: order ' . $order_id . ' ' . wp_json_encode( $payload ) );
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
; php.ini or conf.d/xdebug.ini (local only)
xdebug.mode = debug
xdebug.start_with_request = trigger
xdebug.client_port = 9003
Common mistakes
| Symptom | Cause | Fix |
|---|---|---|
| Visitors see warnings at the top of the page | WP_DEBUG_DISPLAY left at its default true | WP_DEBUG_DISPLAY false and display_errors 0 outside local |
https://site.com/wp-content/debug.log opens in the browser | The log is in the public folder | A path outside the web root, or deny access in the server config |
Nothing in debug.log | WP_DEBUG is false, or the log file is not writable | Turn on both constants; check folder permissions |
var_dump() / die() left in a commit | Debugging by printing | error_log() for logs, Xdebug breakpoints locally |
| Every page takes seconds locally | Xdebug in start_with_request=yes mode all the time | trigger 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.
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.