WordPress Debugging & Dependency Management

Comprehensive debugging techniques, dependency checking, local development patterns, and conflict resolution for WordPress themes and plugins.

When to Use

Use when:

• Debugging PHP errors, warnings, notices
• Checking if required plugins are active
• Setting up local development environments
• Resolving plugin/theme conflicts
• Troubleshooting performance issues
• Setting up wp-config.php debug options
• Using Query Monitor, Debug Bar, or other tools

---

Debug Mode Configuration

wp-config.php Debug Settings

<?php
/**
 * WordPress debugging configuration.
 * Place these BEFORE "That's all, stop editing!" line.
 */

// ======================
// DEVELOPMENT ENVIRONMENT
// ======================

// Enable debug mode
define( 'WP_DEBUG', true );

// Log errors to wp-content/debug.log
define( 'WP_DEBUG_LOG', true );

// Display errors on screen (disable in production!)
define( 'WP_DEBUG_DISPLAY', true );

// Use dev versions of core JS and CSS (non-minified)
define( 'SCRIPT_DEBUG', true );

// Save database queries for analysis
define( 'SAVEQUERIES', true );

// Disable concatenation of admin scripts
define( 'CONCATENATE_SCRIPTS', false );

// ======================
// PRODUCTION ENVIRONMENT
// ======================

/*
define( 'WP_DEBUG', false );
define( 'WP_DEBUG_LOG', false );
define( 'WP_DEBUG_DISPLAY', false );
define( 'SCRIPT_DEBUG', false );
*/

// ======================
// CUSTOM LOG FILE LOCATION
// ======================

// Log to custom location (must be writable)
define( 'WP_DEBUG_LOG', '/path/to/custom/debug.log' );

// Or in uploads directory
define( 'WP_DEBUG_LOG', WP_CONTENT_DIR . '/uploads/debug.log' );

Environment-Based Configuration

<?php
/**
 * Environment-aware wp-config.php
 * Detects local development vs production
 */

// Detect local development environment
$is_local = (
    isset( $_SERVER['HTTP_HOST'] ) && (
        strpos( $_SERVER['HTTP_HOST'], '.local' ) !== false ||
        strpos( $_SERVER['HTTP_HOST'], '.test' ) !== false ||
        strpos( $_SERVER['HTTP_HOST'], 'localhost' ) !== false ||
        $_SERVER['HTTP_HOST'] === '127.0.0.1'
    )
);

// Or use environment variable
$is_local = getenv( 'WP_ENVIRONMENT_TYPE' ) === 'local';

if ( $is_local ) {
    // Local/Development settings
    define( 'WP_DEBUG', true );
    define( 'WP_DEBUG_LOG', true );
    define( 'WP_DEBUG_DISPLAY', true );
    define( 'SCRIPT_DEBUG', true );
    define( 'SAVEQUERIES', true );
    define( 'WP_ENVIRONMENT_TYPE', 'local' );
} else {
    // Production settings
    define( 'WP_DEBUG', false );
    define( 'WP_DEBUG_LOG', true ); // Still log errors
    define( 'WP_DEBUG_DISPLAY', false );
    define( 'SCRIPT_DEBUG', false );
    define( 'WP_ENVIRONMENT_TYPE', 'production' );
}

WordPress Environment Types (5.5+)

<?php
// Set environment type (local, development, staging, production)
define( 'WP_ENVIRONMENT_TYPE', 'local' );

// Usage in code
if ( wp_get_environment_type() === 'local' ) {
    // Local development only code
}

if ( wp_get_environment_type() === 'production' ) {
    // Production only code
}

// Check if development environment
function is_development_environment() {
    return in_array( wp_get_environment_type(), array( 'local', 'development' ), true );
}

---

Error Logging

Custom Error Logging

<?php
/**
 * Custom error logging utility.
 *
 * @package Plugin_Name
 */

/**
 * Log message to debug.log with context.
 *
 * @param mixed  $message Message to log.
 * @param string $level   Log level (debug, info, warning, error).
 * @param array  $context Additional context data.
 */
function plugin_name_log( $message, $level = 'debug', $context = array() ) {
    // Only log if WP_DEBUG is enabled
    if ( ! defined( 'WP_DEBUG' ) || ! WP_DEBUG ) {
        return;
    }

    $timestamp = current_time( 'Y-m-d H:i:s' );
    $level     = strtoupper( $level );

    // Format message
    if ( is_array( $message ) || is_object( $message ) ) {
        $message = print_r( $message, true );
    }

    // Build log entry
    $log_entry = sprintf(
        "[%s] [%s] [Plugin Name] %s",
        $timestamp,
        $level,
        $message
    );

    // Add context if provided
    if ( ! empty( $context ) ) {
        $log_entry .= ' | Context: ' . wp_json_encode( $context );
    }

    // Add backtrace for errors
    if ( $level === 'ERROR' ) {
        $backtrace  = debug_backtrace( DEBUG_BACKTRACE_IGNORE_ARGS, 5 );
        $log_entry .= "\nBacktrace:\n";
        foreach ( $backtrace as $i => $trace ) {
            $log_entry .= sprintf(
                "  #%d %s:%d %s()\n",
                $i,
                $trace['file'] ?? 'unknown',
                $trace['line'] ?? 0,
                $trace['function'] ?? 'unknown'
            );
        }
    }

    error_log( $log_entry );
}

// Usage examples
plugin_name_log( 'Plugin initialized' );
plugin_name_log( 'User action', 'info

...