Debugging

Tools and techniques for debugging WordPress projects in the WDG AI Development Environment.

WordPress Debug Mode

Enable Debug Mode

Edit project .env or add to wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
define('SCRIPT_DEBUG', true);
define('SAVEQUERIES', true);

View Debug Log

# Tail debug log
wdg logs my-site --tail 100

# Inside container
docker exec wdg-wp-my-site tail -f /var/www/html/wp-content/debug.log

PHP Debugging

Xdebug Setup

Add to services/wordpress/Dockerfile:

RUN pecl install xdebug \
    && docker-php-ext-enable xdebug

COPY xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini

xdebug.ini:

[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug,develop
xdebug.start_with_request=yes
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.log=/tmp/xdebug.log

VSCode Configuration

.vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}/projects/my-site/repositories/my-site"
            }
        }
    ]
}

JavaScript Debugging

Browser DevTools

// Add breakpoints
debugger;

// Console logging
console.log('Variable:', variable);
console.table(array);
console.group('Group Name');
console.groupEnd();

// Performance
console.time('operation');
// ... code ...
console.timeEnd('operation');

React DevTools

Install React DevTools browser extension for debugging Gutenberg blocks.

Database Debugging

Query Monitor Plugin

# Install Query Monitor
wdg wp my-site plugin install query-monitor --activate

# View at: https://my-site.localhost:8443/wp-admin/
# Check: Tools > Query Monitor

Manual Query Debugging

global $wpdb;
$wpdb->show_errors();

$results = $wpdb->get_results("SELECT * FROM wp_posts WHERE post_type = 'post'");

// View last query
echo $wpdb->last_query;

// View errors
print_r($wpdb->last_error);

Database Logs

# Enable MySQL logging
docker exec wdg-mysql mysql -uroot -p -e "SET GLOBAL general_log = 'ON';"

# View log
docker exec wdg-mysql tail -f /var/log/mysql/general.log

Container Debugging

View Container Logs

# All logs
wdg logs my-site

# Follow logs
wdg logs my-site --follow

# Last N lines
wdg logs my-site --tail 50

# Filter by string
docker logs wdg-wp-my-site 2>&1 | grep "error"

Shell Access

# WordPress container
wdg shell my-site

# MySQL container
docker exec -it wdg-mysql bash

# Qdrant container
docker exec -it wdg-qdrant sh

Inspect Container

# View container details
docker inspect wdg-wp-my-site

# Environment variables
docker exec wdg-wp-my-site env

# Running processes
docker exec wdg-wp-my-site ps aux

Network Debugging

Test Connectivity

# From WordPress container to MySQL
docker exec wdg-wp-my-site ping mysql

# Test port
docker exec wdg-wp-my-site nc -zv mysql 3306

# DNS resolution
docker exec wdg-wp-my-site nslookup mysql

Check Nginx Configuration

# Test config
docker exec wdg-nginx nginx -t

# Reload config
docker exec wdg-nginx nginx -s reload

# View config
docker exec wdg-nginx cat /etc/nginx/sites-enabled/my-site.conf

Performance Debugging

PHP Performance

# Enable opcache status
docker exec wdg-wp-my-site php -r 'print_r(opcache_get_status());'

# Check memory
docker exec wdg-wp-my-site php -i | grep memory_limit

# Execution time
docker exec wdg-wp-my-site php -i | grep max_execution_time

WordPress Performance

// Add to functions.php temporarily
add_action('shutdown', function() {
    global $wpdb;

    echo '<!-- ';
    echo 'Queries: ' . $wpdb->num_queries . "\n";
    echo 'Query time: ' . timer_stop() . 's' . "\n";
    echo 'Memory: ' . size_format(memory_get_peak_usage()) . "\n";
    echo '-->';
});

Check Query Performance

# Run explain on slow queries
wdg wp my-site db query "EXPLAIN SELECT * FROM wp_posts WHERE post_status='publish'"

Common Issues

White Screen of Death

# Check error logs
wdg logs my-site --tail 100

# Enable WordPress debug
docker exec wdg-wp-my-site wp config set WP_DEBUG true --raw

# Check PHP syntax
docker exec wdg-wp-my-site php -l /var/www/html/wp-content/themes/custom-theme/functions.php

Database Connection Error

# Verify MySQL is running
docker ps | grep wdg-mysql

# Test connection
docker exec wdg-wp-my-site mysql -h mysql -u wordpress -pwordpress -e "SELECT 1"

# Check credentials
docker exec wdg-wp-my-site wp config get DB_HOST

404 Errors

# Flush rewrite rules
wdg wp my-site rewrite flush

# Check .htaccess
docker exec wdg-wp-my-site cat /var/www/html/.htaccess

# Verify permalinks
wdg wp my-site option get permalink_structure

Memory Limit Issues

# Increase PHP memory limit
docker exec wdg-wp-my-site wp config set WP_MEMORY_LIMIT 256M

# Check current limit
docker exec wdg-wp-my-site php -r "echo ini_get('memory_limit');"

Logging Best Practices

Custom Logging

// Create custom logger
function custom_debug_log($message, $data = null) {
    if (WP_DEBUG === true) {
        $log = date('[Y-m-d H:i:s] ') . $message;

        if ($data !== null) {
            $log .= ': ' . print_r($data, true);
        }

        error_log($log);
    }
}

// Usage
custom_debug_log('User login', ['user_id' => $user_id, 'timestamp' => time()]);

Conditional Logging

// Only log for specific user
if (is_user_logged_in() && get_current_user_id() === 1) {
    error_log('Admin debugging: ' . print_r($data, true));
}

// Only log in development
if (wp_get_environment_type() === 'development') {
    error_log('Dev only: ' . $message);
}

Debugging Tools

WP-CLI Debug Commands

# Check site status
wdg wp my-site cli info

# Verify checksums
wdg wp my-site core verify-checksums

# Check plugin/theme updates
wdg wp my-site plugin list --update=available
wdg wp my-site theme list --update=available

# Regenerate salts
wdg wp my-site config shuffle-salts

Browser Extensions

• Query Monitor - Database and PHP debugging
• React DevTools - React component debugging
• Vue DevTools - Vue component debugging
• Redux DevTools - State management debugging

---

See Also:

• Development Workflow
• Docker Setup
• CLI Commands