Every time WP Debug Toolkit writes a debug constant to wp-config.php, it first creates a backup of the file, then uses an atomic write process under a file lock. If both the atomic write and its direct-write fallback fail, WPDT abandons the operation and your site continues running on the original file content. You do not need FTP access for this, as the process runs through the admin dashboard or WP-CLI.
wp-config.php ModificationEvery change WPDT makes to wp-config.php, whether enabling or disabling a debug constant or updating a path value, goes through a write process designed to prevent partial or corrupt file states.
WPDT targets only the specific constant being changed, locating it by pattern matching and updating it in place. This prevents duplicate defines and unintended alterations to surrounding content.
Most WordPress tools that modify wp-config.php write the new content directly into the existing file. If that write is interrupted by a timeout, a permission error, or a full disk, the file can end up in a state that breaks the site. WPDT prevents this by keeping the original file intact until the new content is confirmed valid and the replacement is complete.
WPDT routes every wp-config.php change through three sequential steps: backup, atomic write, and verification with rollback on failure. Each step must succeed before the next begins.
WPDT’s primary write path writes the new content to a temporary file named wp-config.php.tmp in the same directory, then replaces the original file with that temporary file in a single rename() call. The write happens under a file lock acquired via PHP’s flock(), so concurrent processes cannot interfere mid-write. Using rename() for the replacement means the file transitions directly from the old content to the new content with no partially-written intermediate state.
If the atomic write fails for any reason, WPDT removes the temporary file and attempts a direct write to wp-config.php as a fallback. The backup created in Phase 2 exists as a recovery point in either scenario.
Before WPDT writes any change, it creates a backup of the current wp-config.php. The backup is stored in wp-content/debug-toolkit/ under the filename config-backup-{md5_of_config_path}.php.
The .php extension is intentionally added to prevent web servers from serving the backup file contents as plain text if the directory is ever directly accessible. WPDT creates this backup once on first modification and does not overwrite it on subsequent writes, so it preserves the state of wp-config.php as it existed before WPDT ever touched it.
If the atomic write fails, WPDT removes the temporary file and attempts a direct write to wp-config.php as a fallback. If the direct write also fails, WPDT abandons the operation entirely. No user action is required to trigger this behavior, and WPDT does not display a specific admin notice when a write fails.
The failure surfaces as a settings save error in the admin UI. In either failure scenario, the backup at wp-content/debug-toolkit/config-backup-{hash}.php exists as a recovery point if you need to restore the previous file state manually.
On GridPane, WPDT detects the hosting environment automatically by checking for the GRIDPANE constant and writes to wp-config.php using the wrapped define format, which is compatible with GridPane’s configuration structure. WPDT never modifies GridPane’s secure-debug.php.
✅ Key Guarantees
rename() operation under a file lock, so the file transitions cleanly from old content to new content with no partially-written intermediate state.| Term / Constant / File | What It Means |
|---|---|
| Atomic write | WPDT’s primary write path writes new content to wp-config.php.tmp, then replaces the original in a single rename() call. This ensures the file transitions cleanly from old content to new content with no partially-written intermediate state. If the rename fails, WPDT falls back to a direct write. |
| Backup | A copy of wp-config.php created by WPDT on first modification and stored as wp-content/debug-toolkit/config-backup-{md5_of_path}.php. The .php extension prevents web servers from serving its contents as plain text. WPDT creates this file once and does not overwrite it on subsequent writes. |
| Rollback | The backup file at wp-content/debug-toolkit/config-backup-{hash}.php serves as a recovery point if a write fails and leaves wp-config.php in an unexpected state. The atomic write path keeps the original untouched until rename() completes. The direct write fallback does not carry that guarantee. |
secure-debug.php | A configuration file used by some hosting environments in place of wp-config.php. On non-GridPane hosts where this file exists, WPDT writes debug constants to it rather than to wp-config.php. On GridPane, WPDT writes to wp-config.php directly and does not modify secure-debug.php. |
| Wrapped define | A define() call wrapped inside an if ( ! defined( 'CONSTANT' ) ) guard block. On GridPane, WPDT uses this format when inserting constants into wp-config.php, placing them before the line that includes secure-debug.php so they take effect at the right point in PHP’s execution. WPDT also uses this format on any host where the existing config file already uses wrapped defines throughout. |
The safe write process described in this article runs automatically every time a debug constant is toggled from the Debug Constants section in the Debug Toolkit admin or via wp dbtk debug on or wp dbtk debug off in WP-CLI. (wp dbtk debug status reads the current state of wp-config.php and does not trigger a write.) You are not required to take any action to create backups or trigger this process.
Note: The Viewer App uses a separate write process when toggling debug constants. That process does not include the backup, atomic write, or fallback steps described in this article. To ascertain the guarantees described here, toggle debug constants from the admin dashboard or via WP-CLI.
wp-config.php Change Did Not Apply After Toggling a ConstantLikely cause: the write process encountered a permission error or the disk was full, triggering a fallback and then failure.
Fix: confirm that the PHP process has write permission to wp-config.php (typically 0644, with the web server user as owner), and that disk space is available. After resolving the underlying issue, toggle the constant again.
wp-config.php Shows Unexpected Content After a Failed WriteLikely cause: a third-party plugin or server process wrote to wp-config.php after WPDT’s backup was taken but before the atomic replacement completed, producing a conflict between the two writes.
Fix: review the current content of wp-config.php against the backup in wp-content/debug-toolkit/. Navigate to wp-content/debug-toolkit/ and locate the backup file. Look for a file with a config-backup- prefix and a .php extension. Open it in a text editor; its contents are the last known-good state of your wp-config.php before WPDT’s modification attempt. Copy the full contents of the backup file, then open wp-config.php and replace its current contents with the copied content. Save wp-config.php and your site should immediately return to its previous working state.
wp-config.php Modification — Frequently Asked Questionswp-config.php?No. WPDT writes to wp-config.php directly through the PHP process, the same process that runs WordPress. No FTP, SSH or file manager access is needed. The Debug Constants section in the Debug Toolkit admin and the wp dbtk debug CLI commands both modify the file without any server credentials beyond what WordPress already uses.
wp-config.php?No. WPDT creates the backup once, on the first modification it makes, and never replaces it. The backup represents the state of wp-config.php before WPDT’s first write. This preserves a clean original to restore from if needed.
WPDT’s write process requires the PHP process to have write access to wp-config.php. If the file is not directly writable, WPDT attempts a temporary permission elevation before writing, then restores the original permissions afterward. On some managed hosts where ownership prevents any elevation, WPDT surfaces a warning and skips the config file write while still saving any database-level settings. On GridPane, WPDT automatically detects the environment and writes to wp-config.php using a wrapped define format compatible with GridPane’s configuration structure. For other restrictive hosts, see the Environment and Hosting Detection article.
How to Automatically Enable WordPress Debug Mode – The debug constants WPDT manages through the safe write process. See which constants are currently active on your site and toggle them from the admin or WP-CLI.
Environment and Hosting Detection – How WPDT identifies GridPane, WP Engine, and other managed hosts to apply the correct configuration file paths automatically. Relevant if the safe write process is behaving differently than expected on your host.
Permission Elevation – How WPDT handles write permission requirements on hosting environments that restrict access to wp-config.php and other configuration files.
