Wordpress Ray Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require spatie/wordpress-ray
   

   Add to wp-config.php (before WP_DEBUG):

   require __DIR__ . '/vendor/autoload.php';
   $wpRay = new \Spatie\WordPressRay\WordPressRay();
   

2. Configure Ray

   • Install Ray Desktop App and authenticate.
   • Set your API key in wp-config.php:

     $wpRay->setApiKey('your-ray-api-key');
     

3. First Debug Output Use ray() helper (auto-loaded) or $wpRay->ray():

   ray($this->get_post(), 'Current Post Data');
   // or
   $wpRay->ray($user, 'User Object');
   

First Use Case

Debug a custom WordPress plugin/theme:

add_action('wp_enqueue_scripts', function() {
    $query = new WP_Query(['post_type' => 'product']);
    ray($query->posts, 'Products Query Result');
});

Implementation Patterns

Core Workflows

1. Replacing var_dump/error_log Replace legacy debugging with ray() for structured output:

   // Before
   error_log(print_r($user, true));
   
   // After
   ray($user, 'User Object');
   

2. Conditional Debugging Use WP_DEBUG to toggle Ray output:

   if (WP_DEBUG) {
       ray($this->get_options(), 'Plugin Options');
   }
   

3. Performance Profiling Measure execution time:

   $wpRay->startTimer('plugin_init');
   // ... code ...
   $wpRay->stopTimer('plugin_init');
   

4. Query Debugging Inspect database queries:

   global $wpdb;
   $results = $wpdb->get_results("SELECT * FROM wp_posts");
   ray($results, 'Raw Posts');
   

Integration Tips

• Hooks & Filters Debug hook execution:

  add_action('init', function() {
      ray(current_filter(), 'Current Hook');
  });
  

• REST API Debugging Log API responses:

  add_filter('rest_pre_serve_request', function($response) {
      ray($response, 'API Response');
      return $response;
  });
  

• Theme Development Debug template data:

  add_action('wp_head', function() {
      ray(get_post_meta(get_the_ID()), 'Post Meta');
  });
  

• CLI Debugging Use Ray in WP-CLI scripts:

  // wp-cli-script.php
  require __DIR__ . '/vendor/autoload.php';
  $wpRay = new \Spatie\WordPressRay\WordPressRay();
  $wpRay->setApiKey(getenv('RAY_API_KEY'));
  ray(wp_list_plugins(), 'Installed Plugins');
  

Gotchas and Tips

Common Pitfalls

1. API Key Leaks

   • Never commit wp-config.php with hardcoded API keys. Use environment variables:

     $wpRay->setApiKey(getenv('RAY_API_KEY'));
     

2. Performance Overhead

   • Disable Ray in production:

     if (!defined('WP_ENV') || WP_ENV !== 'production') {
         $wpRay->setApiKey(getenv('RAY_API_KEY'));
     }
     

3. Large Data Dumps

   • Avoid sending massive arrays/objects (e.g., WP_Query results with posts_per_page=-1). Use array_slice():

     ray(array_slice($posts, 0, 10), 'First 10 Posts');
     

4. Ray App Not Connecting

   • Ensure the Ray app is running and authenticated.
   • Check firewall/proxy settings if using remote WordPress.

Debugging Tips

• Inspect Ray Messages Use ray() with context:

  ray($this->get_errors(), 'Plugin Errors', ['context' => 'admin']);
  

• Group Related Outputs Use tags for organization:

  ray($user, 'User Data', ['tags' => ['auth', 'user']]);
  

• Pause Execution Use ray()->pause() to halt script execution for inspection.

• Markdown Support Format output with Markdown:

  ray("# User Data\n\n- Name: {$user->name}\n- Role: {$user->roles[0]}");
  

Extension Points

1. Custom Handlers Extend Spatie\WordPressRay\WordPressRay to add custom logic:

   $wpRay->extend(function($data, $label, $tags = []) {
       if (is_wp_error($data)) {
           return ray($data->get_error_message(), $label, $tags);
       }
       return $data;
   });
   

2. Override Default Ray Client Swap the underlying Ray client for custom transport:

   $wpRay->setRayClient(new \Spatie\Ray\RayClient('custom-endpoint'));
   

3. Hook into Ray Events Listen for message sent events:

   $wpRay->onMessageSent(function($message) {
       do_action('wp_ray_message_sent', $message);
   });
   

4. Theme-Specific Output Create a custom Ray theme for WordPress:

   $wpRay->setTheme('wordpress');
   // Requires Ray Pro or custom theme setup