=== DebugZen ===
Contributors: parag44
Tags: debug, error log, debug log, php errors, wp-config
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.3.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Turn WP_DEBUG on and off without FTP, then search, filter and clear debug.log in your dashboard, with grouped errors and the code behind them.

== 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_DEBUG`
* `WP_DEBUG_LOG`
* `WP_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.log` for 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**: `/` or `Cmd/Ctrl + K` to search, `j` and `k` to move between entries, `r` to refresh, `t` to turn Live on or off, and `Esc` to 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 ==

1. Upload the `debugzen` folder to `/wp-content/plugins/`, or install the plugin ZIP from Plugins > Add New > Upload Plugin.
2. If installing from source without the bundled `vendor` directory, run `composer install --no-dev --optimize-autoloader` inside the plugin directory.
3. Activate DebugZen through the Plugins screen in WordPress.
4. Open DebugZen in the WordPress admin sidebar (below Tools).
5. Ensure `wp-config.php` is writable before saving changes. Restore restrictive permissions after configuration if required by your hosting environment.

== Frequently Asked Questions ==

= 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 ==

1. The DebugZen screen: wp-config.php debug switches, log summary, severity and source filters, and grouped log entries.
2. An open fatal error with the source code around the failing line, plus stack trace and raw tabs.
3. Settings for log rotation and the viewer.

== 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: `j` and `k` keyboard 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_capability` filter 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 (`/` or `Cmd/Ctrl + K` to search, `r` to refresh, `t` to toggle Live Tail, `Esc` to 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 in `DebugZen_Source_Reader`, user-scoped source-context HMAC tokens, `edit_plugins`/`edit_themes` capability gating on editor line jumps, explicit log-file exclusion, `$_POST['file']` input sanitization, and `X-Content-Type-Options: nosniff` on 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 with `15s`/`30s` polling intervals, `30` entries/page, `8` context lines, and `rotate` archive 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`, and `WP_DEBUG_DISPLAY`.
* Added a memory-conscious debug-log viewer and secure clear-log action.
* Added WP Config Transformer integration.

== Upgrade Notice ==

= 1.3.0 =
DebugZen moves to its own admin menu item, with debug switches on the main screen, source filters, and a redesigned log viewer.

= 1.2.0 =
Major workbench UI polish, full-width WP Admin layout, security hardening, and full WordPress.org Plugin Check compatibility.

= 1.1.0 =

Major feature release introducing an interactive diagnostic log viewer, smart duplicate log grouping, source code context preview with editor jump, real-time live tail, and log rotation.

= 1.0.0 =

Initial release.
