Debugging & Profiling

Overview

To maintain high performance and code quality within this WordPress environment, we utilize Xdebug for step-debugging and Query Monitor for real-time database and hook analysis. This section outlines how to configure these tools for effective development.

Xdebug Configuration

Xdebug is essential for deep-dive error analysis and understanding the execution flow of complex WordPress hooks and filters.

1. Enable Xdebug in PHP

Ensure your PHP environment has the Xdebug extension installed. Add or modify the following directives in your php.ini or xdebug.ini file:

[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug,develop
xdebug.client_port=9003
xdebug.start_with_request=yes
xdebug.discover_client_host=1

2. VS Code Integration

If you are using Visual Studio Code, use the following launch.json configuration to listen for Xdebug sessions:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceRoot}"
            }
        }
    ]
}

Query Monitor Usage

Query Monitor is the primary tool for identifying performance bottlenecks, slow database queries, and redundant hooks.

Installation & Access

Query Monitor is included as a required development plugin. Once activated:

1. Navigate to the WordPress Admin Bar.
2. Click the statistics overview (e.g., 0.05s 12.5MB) to open the console.

Key Analysis Areas

| Feature | Usage for Users | | :--- | :--- | | Queries by Component | Identify if a specific plugin or the theme is performing excessive database calls. | | Hooks & Actions | View all actions fired during the request to debug hook priority issues. | | Scripts & Styles | Identify enqueued assets and detect dependencies that may be slowing down page loads. | | Environment | Check PHP memory limits, error levels, and server software versions. |

Error Logging

Standard WordPress debugging should be enabled alongside Xdebug for persistent logs. In your wp-config.php, ensure these constants are configured for local development:

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

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

// Do not display errors on the frontend (keeps the UI clean)
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Accessing Logs

You can tail the debug log directly from your terminal to monitor errors in real-time:

tail -f wp-content/debug.log

Profiling with Xdebug

To profile application performance and generate cachegrind files, update your configuration:

1. Set xdebug.mode=profile.
2. Trigger the request.
3. Use a tool like WebGrind or QCacheGrind to analyze the output files generated in your xdebug.output_dir.