Laravel Ray Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-ray
   php artisan ray:install
   

   This publishes the config file (config/ray.php) and registers the service provider.

2. Configure Ray: Edit config/ray.php to set your project name, token, and other settings. Ensure the token matches your Ray app configuration.

3. First Use Case: Replace a dd() or dump() call in your code with:

   ray('Variable to inspect', ['context' => 'Debugging user creation']);
   

   Launch the Ray app, and the output will appear in real-time.

Where to Look First

• Ray Directives: The package provides Blade directives (@ray, @raydump, @xray) for debugging views.
• Artisan Commands: Use php artisan ray:clean to remove Ray calls from your codebase.
• Watchers: Built-in watchers for HTTP requests, queries, exceptions, and more (see config/ray.php under watchers).

Implementation Patterns

Core Workflows

1. Debugging Variables:

   ray($user, ['context' => 'User profile data']);
   ray(['status' => 'success', 'data' => $data]);
   

2. Blade Debugging:

   @ray($user)
   @xray  <!-- Shows all variables in scope -->
   

3. Performance Measurement:

   ray()->measure('Database query', function () {
       User::all();
   });
   

4. Exception Context:

   try {
       // Risky code
   } catch (\Exception $e) {
       ray($e, ['context' => 'Failed payment processing']);
       throw $e;
   }
   

Integration Tips

• Conditional Debugging: Use config('ray.enabled') to toggle Ray output in different environments:

  if (config('ray.enabled')) {
      ray($data, ['context' => 'Debug only in local']);
  }
  

• Custom Watchers: Extend the Spatie\Ray\Watchers\Watcher class to create domain-specific watchers (e.g., for API requests or third-party services).

• Queue Jobs: Use ray() in job handlers to inspect payloads or failures:

  public function handle() {
      ray($this->data, ['context' => 'Processed job']);
  }
  

• API Responses: Log API responses with context:

  $response = Http::get('https://api.example.com/data');
  ray($response->json(), ['context' => 'API response']);
  

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Ray adds minimal overhead, but avoid excessive logging in production. Use environment checks:

     if (app()->environment('local')) {
         ray($data);
     }
     

2. Token Leaks:

   • Never commit config/ray.php with a token. Use environment variables:

     RAY_TOKEN=your_token_here
     

     Then reference it in ray.php:

     'token' => env('RAY_TOKEN'),
     

3. Blade Directives in Production:

   • Disable Ray in production by setting 'enabled' => false in config/ray.php or via .env:

     RAY_ENABLED=false
     

4. Query Watcher Conflicts:

   • If queries aren’t appearing in Ray, ensure the QueryWatcher is enabled in config/ray.php:

     'watchers' => [
         'queries' => true,
     ],
     

5. PHP 8.5+ Deprecations:

   • Recent versions handle PHP 8.5 deprecations (e.g., strtolower on null). Ensure you’re on >=1.41.0.

Debugging Tips

1. Missing Output:

   • Verify the Ray app is running and connected to the same project.
   • Check config/ray.php for misconfigured token or project_name.
   • Ensure Spatie\Ray\RayServiceProvider is registered in config/app.php.

2. Artisan Command Issues:

   • If ray:clean fails, manually remove Ray calls or check for syntax errors in your codebase.

3. Context Overload:

   • Use concise context labels to avoid clutter:

     ray($user, ['context' => 'User ID: ' . $user->id]);
     

4. Blade @xray Not Working:

   • Ensure the directive is placed in a Blade file and the BladeWatcher is enabled:

     'watchers' => [
         'blade' => true,
     ],
     

Extension Points

1. Custom Directives: Create a custom directive by extending Spatie\Ray\Directives\Directive and binding it in the service provider.

2. Middleware Integration: Use Ray in middleware to log incoming requests:

   public function handle($request, Closure $next) {
       ray($request->all(), ['context' => 'Incoming request']);
       return $next($request);
   }
   

3. Event Listeners: Log events with context:

   public function handle(UserRegistered $event) {
       ray($event->user, ['context' => 'New user registered']);
   }
   

4. Testing: Mock Ray calls in tests using Spatie\Ray\Facades\Ray:

   Ray::shouldReceive('ray')->once();