Environment and Hosting Detection

WP Debug Toolkit (WPDT) automatically resolves the paths for wp-config.php and debug.log through a defined fallback chain, so WPDT can locate the right files on managed hosts like GridPane, Kinsta, or WP Engine that use non-standard directory structures. WPDT shows a status badge in File Paths Configuration, confirming how each path was determined, and you can override either one from the Settings UI or by defining a constant in wp-config.php.

What Is Environment and Hosting Detection

WP Debug Toolkit does not assume your site follows the standard WordPress file layout. Before WPDT can read your debug log or modify wp-config.php, it needs to know where those files actually live. 

Environment and hosting detection is the process WPDT runs at startup to locate those files automatically, without requiring any manual configuration on a standard installation.

On managed hosting platforms, the problem is concrete: GridPane places wp-config.php outside the webroot; some hosts route debug output to a non-standard path instead of wp-content/debug.log; and others impose directory structures that differ from what the WordPress documentation describes. 

A debugging plugin that cannot find your config file or log file cannot do its job. WPDT’s detection system handles these variations, so you do not have to configure paths from scratch on every new environment. 

How It Works

WPDT resolves two file paths at runtime before performing any read or write operation: the location of debug.log and the location of the config file it writes debug constants to. Both update the File Paths Configuration panel in Settings with the result.

Path Resolution: The Fallback Chain

WPDT resolves the debug log path by working through a defined sequence until it finds a valid match:

1. The path you entered under File Paths Configuration in Settings, if a manual override is saved
2. The DBTK_LOG_PATH constant, if defined in wp-config.php
3. A string value assigned to WP_DEBUG_LOG, when WP_DEBUG_LOG is set to a file path rather than true
4. A host-specific location for detected environments — GridPane uses a logs/ directory above the webroot
5. Standard fallback locations, checked in order: wp-content/debug.log, ABSPATH/debug.log, then dirname(ABSPATH)/logs/debug.log

Config file resolution follows the same priority structure: a saved, enabled, and valid Settings override first, then DBTK_CONFIG_PATH, then the standard and parent-directory locations for wp-config.php. 

On GridPane, WPDT writes debug constants directly into wp-config.php, wrapped in if ( ! defined() ) guards and placed ahead of GridPane’s own secure-debug.php include so that file remains authoritative. WPDT never modifies or deletes secure-debug.php.

GridPane is the only host with a dedicated path-resolution branch. WPDT also detects Flywheel environments, but that detection governs the Viewer App’s web root and config writability, not debug log or config path resolution. See Flywheel Compatibility for details. Kinsta, WP Engine, and other managed hosts without a dedicated path branch are served by the standard fallback chain.

Environment Type: Site Health Calibration

WPDT determines your environment type by calling WordPress’s native wp_get_environment_type() function when available (WordPress 5.5 and above). If that function is not available, WPDT checks the WP_ENVIRONMENT_TYPE constant, then the WP_ENV constant. If none of these are defined, WPDT defaults to ‘production’.

This affects the WPDT Site Health panel. When WP_DEBUG is active and the environment resolves to ‘production’, WPDT reports an error with the badge Debug Mode Active in Production. On staging or development environments, the same active debug mode shows as a good configuration, while disabled debug mode on a non-production environment produces a warning encouraging you to enable it.

To control how WPDT categorizes your environment, set WP_ENVIRONMENT_TYPE in wp-config.php:

php
// Accepted values: 'production', 'staging', 'development', 'local'
define( 'WP_ENVIRONMENT_TYPE', 'staging' );

When Auto-Detection Falls Short

WPDT shows a status badge next to each entry in WP Debug Toolkit › Settings, indicating how that path was determined: Auto-detected for a path found through the standard fallback chain, GridPane when the GridPane-specific log location is in use, or Custom when a DBTK_LOG_PATH or DBTK_CONFIG_PATH constant is controlling the path. The File Paths Configuration section subtitle describes the purpose directly: “Configure custom file paths for non-standard WordPress setups like GridPane or custom environments.”

If the resolved path does not match your actual setup, click Override next to the relevant entry and enter the correct path. The Quick Reference panel inside File Paths Configuration lists path conventions and common examples:

• ../wp-config.php — GridPane setup (parent directory, one level up from the webroot)
• /tmp/debug.log — Temporary directory
• ./wp-content/debug.log — Standard location

For a permanent, code-level override that persists across settings changes, define one or both constants in wp-config.php:

php

// Force WPDT to use a specific config file path for debug constant writes

define( 'DBTK_CONFIG_PATH', '/path/to/wp-config.php' );

// Force WPDT to use a specific debug log path

define( 'DBTK_LOG_PATH', '/path/to/debug.log' );

A saved, enabled Settings override is always checked first and takes precedence over the constants. The constants take precedence over WP_DEBUG_LOG and the rest of the automatic resolution chain, which makes them useful for setting a path without touching the database. If you want a constant to always win, leave the corresponding Override field in Settings empty or disabled.

✅ Key Guarantees

• WPDT resolves the debug log path and the config file path through separate fallback chains, checking a saved Settings override first, before performing any read or write operation on either file.
• WPDT never modifies or deletes GridPane’s secure-debug.php file. On GridPane, debug constants are written into wp-config.php itself, ahead of GridPane’s secure-debug.php include.
• GridPane is the only host with dedicated path-resolution logic. Kinsta, WP Engine, and other managed hosts without a dedicated path branch are served by the standard fallback chain.
• Environment type detection uses WordPress’s own wp_get_environment_type() and falls back to WP_ENVIRONMENT_TYPE and WP_ENV, so your existing environment configuration controls WPDT’s Site Health severity thresholds without any additional setup.

Key Concepts

Related Documentation

How to Safely Modify wp-config.php – Explains the atomic write process WPDT uses when saving debug constants, including backup creation and automatic rollback on failure.

Site Health Integration – See how WPDT uses your environment type to set the right severity thresholds across all Site Health checks.

Flywheel Compatibility – Flywheel’s symlinked directory structure means wp-config.php isn’t writable through the usual path. Here’s how to navigate it.