Ray Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/ray
   

   For Laravel, also install the service provider:

   composer require spatie/laravel-ray
   

2. Configuration:

   • Publish the config file:

     php artisan vendor:publish --provider="Spatie\Ray\RayServiceProvider" --tag="ray-config"
     

   • Update .env with your Ray server URL (e.g., RAY_SERVER_URL=http://localhost:8000).

3. First Use Case: Replace dd() or dump() with Ray’s ray() helper:

   ray($user); // Inspects the $user object in the Ray app
   

   Or use the facade:

   use Spatie\Ray\Ray;
   
   Ray::info('Debug message', ['key' => 'value']);
   

Implementation Patterns

Core Workflows

1. Debugging Variables:

   ray($query->get(), 'Query results'); // Label + variable
   ray(['user' => $user, 'posts' => $posts]); // Grouped data
   

2. Conditional Debugging:

   if (config('app.debug')) {
       ray($request->all(), 'Request payload');
   }
   

3. Performance Measurement:

   $start = microtime(true);
   // ... code ...
   ray(microtime(true) - $start, 'Execution time');
   

4. Query Inspection:

   DB::enableQueryLog();
   $results = DB::table('users')->get();
   ray(DB::getQueryLog(), 'SQL queries');
   

5. Exception Handling:

   try {
       // Risky code
   } catch (\Exception $e) {
       ray($e, 'Exception details');
       throw $e;
   }
   

Integration Tips

• Middleware: Log requests/responses:

  public function handle($request, Closure $next) {
      ray($request->all(), 'Incoming request');
      $response = $next($request);
      ray($response->getContent(), 'Response');
      return $response;
  }
  

• Commands: Debug CLI processes:

  use Spatie\Ray\Ray;
  
  Ray::command('user:import', function () {
      ray('Starting import...');
      // ...
  });
  

• Events: Inspect event payloads:

  public function handle(Created $event) {
      ray($event->user, 'New user created');
  }
  

• Testing: Debug tests without cluttering output:

  ray($this->user, 'Test user data');
  

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Avoid ray() in tight loops or production. Use if (app()->environment('local')).
   • Disable Ray in production by setting RAY_ENABLED=false in .env.

2. Large Payloads:

   • Ray has a 20-message limit per session in the free trial. For large data, use ray()->table() or ray()->json() to serialize efficiently.

3. Circular References:

   • Complex objects (e.g., Eloquent models with relationships) may cause infinite loops. Use ray($user->toArray()) or ray($user)->without(['relationships']).

4. Livewire/Blade:

   • Livewire components may render instead of being sent to Ray. Use ray($component)->asClass() to force class inspection.

5. Configuration Conflicts:

   • Ensure RAY_SERVER_URL matches your local Ray server (default: http://localhost:8000).
   • If using Docker, expose the port and update the URL (e.g., http://host.docker.internal:8000).

Debugging Tips

1. Filtering Output: Use labels and tags to organize messages:

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

   Filter in Ray’s UI by label/tag.

2. Copying Data: Right-click a variable in Ray to copy as JSON/array. For arrays, use ray($array)->copy() in code.

3. Expanding Payloads: Click the expand button in Ray to view nested structures (e.g., Eloquent collections).

4. Clipboard Integration: Use ray($data)->clipboard() to auto-copy data to your system clipboard.

5. Custom Themes: Configure themes in config/ray.php:

   'theme' => 'dark', // 'light', 'dark', or 'auto'
   

Extension Points

1. Custom Handlers: Extend Ray’s payload processing by overriding the Spatie\Ray\Ray class or using afterSendCallbacks:

   Ray::afterSend(function ($payload) {
       $payload['custom'] = 'metadata';
       return $payload;
   });
   

2. Rector Rules: Remove ray() calls from production code using Ray’s Rector rule:

   vendor/bin/rector process src --dry-run --config rector.php
   

3. PHPStan Rules: Detect ray() calls in static analysis:

   // rector.php
   return static::configuredWithRules([
       \Spatie\Ray\Rector\RemoveRayCallRector::class,
   ]);
   

4. Remote Debugging: For Docker/Laravel Forge, use the Ray Gateway to proxy requests to your local Ray server.

5. Log Context: Attach log context to Ray messages:

   ray('Error', ['context' => ['user_id' => $user->id]]);
   

Pro Tips

• Keyboard Shortcuts:

  • Ctrl+Shift+R: Refresh Ray.
  • Ctrl+F: Search messages.
  • Ctrl+Click: Expand nested data.

• Markdown Support: Use ray()->markdown('# Title') for formatted output.

• Performance Tracing: Use ray()->trace() to log execution time with context:

  ray()->trace('User fetch', fn() => $user->load('posts'));
  

• Environment-Specific Config: Override config/ray.php per environment:

  'enabled' => env('RAY_ENABLED', false),