Debug and Hooks Cheat Sheet

Summary: Understanding debugging and where to use it in WordPress, Cheat Sheet on WordPress Hooks.

Debugging WordPress Using Xdebug

Debugging is an essential part of the development process and Xdebug is a powerful tool for PHP developers especially when working with WordPress. Xdebug provides detailed error messages, stack traces, and the ability to set breakpoints, inspect variables, and step through code execution.

Common Use Cases in WordPress

Debugging Theme and Plugin Development

We can place breakpoints in our theme’s functions.php, template files, or custom plugins to troubleshoot issues.
Analyze how WordPress loads and executes our code during different stages of the WordPress lifecycle.

Investigating WordPress Hooks (Actions & Filters)

WordPress relies heavily on hooks. We can place breakpoints in the callback functions attached to actions and filters to see how and when they are executed.
Useful for understanding how third-party plugins or themes interact with our code.

Debugging the WordPress Loop

The WordPress loop is central to theme development. By setting breakpoints inside the loop we can inspect how posts are fetched and rendered.

Analyzing SQL Queries

Xdebug can help us understand how WordPress builds and executes SQL queries. This is particularly useful for optimizing performance or debugging custom queries.

Error Handling and Logging

Xdebug enhances PHP’s default error handling by providing detailed stack traces, which are invaluable when tracking down the source of a problem.
We can combine Xdebug with WordPress’s built-in logging functions (error_log(), WP_DEBUG_LOG) for comprehensive debugging.

Profiling

Xdebug can generate detailed profiles of our PHP code’s execution, showing which functions take the most time and where bottlenecks occur.

Cheat sheet on Hooks

Hooks are a fundamental part of WordPress, allowing developers to modify or extend the core functionality of WordPress without directly modifying core files. There are two main types of hooks: Actions and Filters.

Actions

Actions are used to execute functions at specific points in the WordPress lifecycle, such as when a post is published, a user logs in, or the footer is rendered.
We can add custom functionality by “hooking” into these points using add_action().

  add_action('wp_footer', 'custom_footer_message');

  function custom_footer_message() {
      echo '<p>Custom Footer Message</p>';
  }

Filters

Filters are used to modify data at specific points in the WordPress lifecycle before it is used or displayed.
We can alter the data by “hooking” into these points using add_filter(). Example:

  add_filter('the_title', 'modify_post_title');

  function modify_post_title($title) {
      return 'Modified: ' . $title;
  }

Priority

Both add_action() and add_filter() accept a priority parameter. The default priority is 10, but we can change it to control the order in which functions are executed.
Lower priority numbers run earlier higher numbers run later.

  add_action('wp_footer', 'first_footer_function', 5);  // Runs first
  add_action('wp_footer', 'second_footer_function', 15); // Runs later

Number of Accepted Arguments

By default hooks only pass one argument to the callback function. But many hooks pass more than one argument, which we can capture by specifying the number of accepted arguments.

  add_filter('the_content', 'modify_content', 10, 2);

  function modify_content($content, $post_id) {
      // Modify the content based on $post_id
      return $content;
  }

Creating Custom Hooks

Custom Actions

We can create custom actions in our plugins or themes to allow other developers to hook into our code.

  function my_custom_function() {
      // Do something
      do_action('my_custom_action');
  }

  // Other developers can hook into this action:
  add_action('my_custom_action', 'another_custom_function');

Custom Filters

Custom filters work similarly allowing other developers to modify data processed by our plugin or theme.

  function process_data($data) {
      $filtered_data = apply_filters('my_custom_filter', $data);
      return $filtered_data;
  }

  // Other developers can modify $data:
  add_filter('my_custom_filter', 'modify_data_function');

Advanced Hook Techniques

Anonymous Functions (Closures)

We can use anonymous functions to create hooks on the fly which can be useful for short one-off modifications.

  add_action('wp_footer', function() {
      echo '<p>Anonymous Function Hook</p>';
  });

Removing Hooks

We can remove an action or filter if we need to prevent it from running. This is often used to override default behavior.

  remove_action('wp_footer', 'default_footer_function');

When dealing with anonymous functions removing them can be tricky since we cannot directly reference the function. Instead we should use a named function if we anticipate needing to remove it later.

Dynamic Hooks

WordPress allows for dynamic hook names enabling more flexible and modular coding practices. We can append or prepend variables to hook names.

  $post_type = 'custom_post_type';
  add_action("save_post_{$post_type}", 'custom_save_post_function');

Callback Execution Control with Conditionals

Sometimes we may want to control when a callback should run based on certain conditions.

  add_action('the_content', function($content) {
      if (is_single() && in_the_loop()) {
          $content .= '<p>Appended to single post content</p>';
      }
      return $content;
  });

Profiling Hook Performance

We can use tools like Query Monitor or custom profiling code to measure the time taken by each hook and optimize accordingly.

  add_action('the_content', function($content) {
      $start_time = microtime(true);
      // Do some work
      $end_time = microtime(true);
      error_log('Hook took ' . ($end_time - $start_time) . ' seconds');
      return $content;
  });