Description
DebugZen gives administrators one focused screen for WordPress debugging: turn the debug constants on and off, then read, filter and clear debug.log without FTP or SSH.
Debug constants without editing files
Switches at the top of the DebugZen screen read and update these constants in wp-config.php:
WP_DEBUGWP_DEBUG_LOGWP_DEBUG_DISPLAY
Changes are written with the WP Config Transformer library, which parses wp-config.php instead of using regex or string replacement. If WP_DEBUG_LOG points to a custom file, that path is kept. If wp-config.php is read-only, DebugZen shows the exact lines to add yourself. Turning on WP_DEBUG_DISPLAY shows a reminder that errors are now printed to visitors.
A log viewer built for reading
- Compact rows: each entry shows its severity, message, source, occurrence count and how long ago it happened. Click a row to open it in place.
- Source, stack trace and raw entry: an open entry shows the lines of code around the error with the failing line highlighted, the full stack trace, and the raw log text. “Open in editor” jumps to that line in the plugin or theme editor for users who are allowed to edit files.
- Grouped duplicates: identical errors collapse into one row with a count and first and last seen times.
- Filter by severity and by source: fatal errors, warnings, notices, deprecations and info, plus the plugin, theme or core file each entry came from, with search across messages and file paths.
- Live: watches
debug.logfor new lines by reading only the bytes added since the last check. New entries never move the row you are reading; they wait behind a “new entries” bar. - Log size management: shows the log size against your limit and clears or archives the file when it is reached.
- Keyboard shortcuts:
/orCmd/Ctrl + Kto search,jandkto move between entries,rto refresh,tto turn Live on or off, andEscto close or clear.
Security
DebugZen is limited to administrators (super admins on multisite), and every request is checked with a nonce. Source previews need a server-signed token tied to the current user, are confined to the WordPress installation with realpath() checks, never include wp-config.php, dotfiles or the active log, and files are only read, never executed.
Third-party libraries
DebugZen includes WP Config Transformer by the WP-CLI Development Group. It is distributed under the MIT License. Its license is included at vendor/wp-cli/wp-config-transformer/LICENSE.
This plugin does not contact external services, collect telemetry, or load remote executable code.
Installation
- Upload the
debugzenfolder to/wp-content/plugins/, or install the plugin ZIP from Plugins > Add New > Upload Plugin. - If installing from source without the bundled
vendordirectory, runcomposer install --no-dev --optimize-autoloaderinside the plugin directory. - Activate DebugZen through the Plugins screen in WordPress.
- Open DebugZen in the WordPress admin sidebar (below Tools).
- Ensure
wp-config.phpis writable before saving changes. Restore restrictive permissions after configuration if required by your hosting environment.
FAQ
Does the plugin directly edit debug constants with string replacement?
No. It uses the WP Config Transformer library from WP-CLI, which reads wp-config.php with PHP’s tokenizer and updates only the three debug constants. If a constant is missing, it is added; everything else in the file is left as it was.
Why are the debug switches greyed out?
wp-config.php is read-only for the web server, which many hosts do on purpose. DebugZen then shows “read-only” next to the switches and lists the exact lines to add to wp-config.php yourself. The log viewer keeps working either way.
I see “Unable to locate placement anchor.” What does it mean?
DebugZen tried to add a debug constant that is not in wp-config.php yet, but could not find where to put it. New constants go just above the line /* That's all, stop editing! */, and your wp-config.php does not have that line. This happens when the line was deleted or reworded, when WordPress was installed in another language, or when a host generated its own wp-config.php. Nothing is written to the file when this error appears.
To fix it, open wp-config.php and add this line on its own, just above require_once ABSPATH . 'wp-settings.php';:
/* That's all, stop editing! */
Then use the switch again. Or add the constants yourself in the same place:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
Is it safe to use on a live site?
Yes, with two precautions. Keep WP_DEBUG_DISPLAY off, so errors are written to the log instead of being shown to visitors; DebugZen warns you while it is on. And because wp-content/debug.log can be downloaded by anyone who guesses the address on many servers, consider setting WP_DEBUG_LOG to a path outside your web root, for example define( 'WP_DEBUG_LOG', '/home/example/logs/debug.log' );. DebugZen reads custom paths and keeps them when you toggle logging.
Who can use DebugZen?
Administrators with the manage_options capability. On multisite, only super admins can use it, because wp-config.php and the log are shared by the whole network. Developers can change the required capability with the debugzen_capability filter.
Will it slow down my site?
No. DebugZen’s scripts and styles load only on its own screen. Other admin pages get just the sidebar item and toolbar link. The viewer reads at most the last 1 MB of the log, and Live reads only the bytes added since its last check.
Where is the debug log?
By default, WordPress writes the log to wp-content/debug.log. If WP_DEBUG_LOG contains a custom path, DebugZen uses that path.
How does the source code preview stay secure?
Each preview needs a server-signed token tied to your user account. Paths are resolved with realpath() and must stay inside the WordPress installation, and wp-config.php, dotfiles and the active log file are never shown. Files are only read, never executed.
Does DebugZen send data anywhere?
No. DebugZen has no telemetry, analytics, external API connection, or remote code loading.
Screenshots
Changelog
1.3.0
- DebugZen now has its own admin menu item below Tools. The old Tools > DebugZen address redirects to it.
- New: switches for WP_DEBUG, WP_DEBUG_LOG and WP_DEBUG_DISPLAY at the top of the screen, saved immediately. The settings dialog now only holds log rotation and viewer options.
- New: filter entries by the plugin, theme or core file they came from.
- New: compact entry rows that open in place, with Source, Stack trace and Raw tabs and relative times.
- New: Live holds incoming entries behind a “new entries” bar while you are reading, instead of moving the list.
- New: loading placeholders and clearer states for an empty log, logging turned off, and read-only wp-config.php.
- New:
jandkkeyboard shortcuts to move between entries. - New icon, full-width layout, and admin colors throughout so the screen follows your admin color scheme.
- Fixed: saving viewer settings could no longer change wp-config.php constants as a side effect.
- Fixed: the “clear at limit” rotation option now describes what it does (it empties the log).
- Fixed: severity labels are now translatable.
- Fixed: for grouped duplicates, the Raw tab, stack trace and Copy entry now show the most recent occurrence instead of the first.
- Security: on multisite, DebugZen is now limited to super admins, because wp-config.php and debug.log are shared by the whole network. The new
debugzen_capabilityfilter changes the required capability.
1.2.0
- Redesigned admin interface as a clean, full-width single-pane developer workbench with improved contrast, native
<dialog>modals, keyboard shortcuts (/orCmd/Ctrl + Kto search,rto refresh,tto toggle Live Tail,Escto clear search or close dialogs), inline retry banners, and Screen Help tab integration. - Updated the DebugZen header mark (
>_) and top WordPress Admin Bar icon to inherit native toolbar colors across all admin color schemes cleanly. - Fixed full-width workbench alignment in wide WordPress admin viewports and cleared
#screen-meta-links(Help) cleanly. - Security hardening: added strict
trailingslashit()+realpath()path boundary enforcement against sibling-directory prefix bypasses inDebugZen_Source_Reader, user-scoped source-context HMAC tokens,edit_plugins/edit_themescapability gating on editor line jumps, explicit log-file exclusion,$_POST['file']input sanitization, andX-Content-Type-Options: nosniffon log downloads. - Performance & bug fixes: resolved Source Code context double-escaping and payload field mismatch, added per-request
DebugZen_Config::get_state()memoization with write invalidation, aligned Settings validation with15s/30spolling intervals,30entries/page,8context lines, androtatearchive mode, removed legacy unused tail/i18n dead code, and ensured zero WordPress.org Plugin Check warnings or errors.
1.1.1
- Bumped ‘Tested up to’ tag to 7.1.
1.1.0
- Major feature release introducing an interactive diagnostic log viewer, smart log grouping, and source code context preview.
- Added Admin Toolbar quick link: Instant access to the DebugZen dashboard from anywhere in WordPress for users with manage_options capability.
- Enhanced Visual Hierarchy: Redesigned log cards with intuitive color-coded severity indicators (Fatal Errors, Warnings, Notices, Deprecated) for quick scanning.
- Added Smart Log Grouping: automatically consolidates repeated identical log entries into a single card with occurrence counts and first/last seen timestamps.
- Added Log Grouping setting under Settings > Advanced (enabled by default) with real-time Live Tail duplicate merging.
- Added Source Code Context preview around reported error lines with lazy loading, line number gutter, and error line highlight.
- Added secure “View in Editor” action opening the WordPress Plugin/Theme file editor directly positioned at the error line.
- Added configurable context window setting (3, 5, 8, 10 lines) in Settings > Advanced.
- Added dedicated log parser recognizing Fatal Errors, Warnings, Notices, Deprecations, and stack traces.
- Added server-side debounced search, severity filtering, and memory-conscious pagination.
- Added high-performance Live Tail with byte-offset tracking to prevent server memory spikes.
- Added Log Size management with visual limit progress indicators and automatic truncation or timestamped rotation.
- Added multi-tab Settings modal for General, Log Rotation, and Advanced options.
- Added clean uninstallation routine (uninstall.php) removing plugin options.
- Added server-signed HMAC authentication and strict path traversal protection for source code preview.
- Added secure Download Log and Copy Path actions.
1.0.0
- Initial release.
- Added secure controls for
WP_DEBUG,WP_DEBUG_LOG, andWP_DEBUG_DISPLAY. - Added a memory-conscious debug-log viewer and secure clear-log action.
- Added WP Config Transformer integration.



