Global Ray Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer global require spatie/global-ray
   

   Ensure ~/.composer/vendor/bin is in your PATH or use the full path to global-ray in commands.

2. First Use: Add this to any PHP file (e.g., app/Commands/TestCommand.php):

   ray('Hello from a non-Laravel file!');
   

   Launch Ray via ray CLI command, then run your PHP script. Output appears in the Ray UI.

3. Laravel Integration: For Laravel projects, install the Laravel Ray package alongside:

   composer require spatie/laravel-ray
   

   Publish config (optional):

   php artisan vendor:publish --provider="Spatie\LaravelRay\RayServiceProvider"
   

Implementation Patterns

Core Workflows

1. Debugging Non-Laravel PHP: Use ray() in CLI scripts, cron jobs, or standalone PHP files. Example:

   // In a cron job (e.g., app/Jobs/ProcessData.php)
   ray(['user_ids' => [1, 2, 3], 'status' => 'pending']);
   

2. Laravel-Specific Patterns:

   • Middleware/Service Providers:

     public function boot()
     {
         ray('Service provider booting...');
     }
     

   • Eloquent Observers:

     ray('User created:', $user->toArray());
     

   • Artisan Commands:

     ray('Command executed with args:', $args);
     

3. Performance Profiling: Use ray()->startTimer() in long-running scripts:

   $timer = ray()->startTimer('data_processing');
   // ... process data ...
   ray()->stopTimer($timer);
   

4. Conditional Debugging: Wrap ray() in environment checks:

   if (app()->environment('local')) {
       ray('Debug info:', $variable);
   }
   

Integration Tips

• Ray in Tests: Disable Ray in tests via config or wrap calls:

  if (!app()->runningUnitTests()) {
      ray('Test debug info');
  }
  

• Ray with Queues: Use in queue jobs to inspect payloads:

  ray('Job payload:', $this->payload);
  

• Ray in Tinker: Launch Ray first, then use Tinker:

  ray
  php artisan tinker
  

Gotchas and Tips

Pitfalls

1. Global vs. Project-Specific:

   • spatie/global-ray is global (installed via Composer global). Ensure it’s in your PATH or use the full path:

     ~/.composer/vendor/bin/global-ray
     

   • For project-specific debugging, prefer spatie/laravel-ray.

2. Ray Not Launching:

   • Ensure the ray binary is executable and no port conflicts (default: 8080).
   • Check for errors with:

     ray --debug
     

3. Performance Overhead:

   • Avoid ray() in tight loops or production. Use:

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

4. Output Truncation:

   • Large arrays/objects may truncate. Use ray()->setMaxOutputSize(0) to disable limits.

Debugging Tips

• Ray Not Receiving Data:

  • Verify the Ray server is running (ray in terminal).
  • Check PHP error logs for connection issues.
  • Test with a simple ray('test') in a standalone script.

• Laravel-Specific Issues:

  • If Ray doesn’t auto-detect Laravel, manually bind the service:

    $this->app->singleton('ray', function () {
        return new \Spatie\Ray\Ray();
    });
    

Extension Points

1. Custom Ray Channels: Use ray()->channel('custom') to categorize logs:

   ray('API request')->channel('api');
   

2. Ray Middleware: Create a middleware to auto-log requests:

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

3. Ray in Exceptions: Log exceptions globally in App\Exceptions\Handler:

   public function report(Throwable $exception)
   {
       ray('Unhandled exception:', $exception);
   }
   

4. Ray with MCP (Multi-Channel Protocol): For AI/third-party integrations, use the MCP server:

   ray('AI response')->mcp();
   

Config Quirks

• Global Config: Edit ~/.config/ray/config.json for global settings (e.g., themes, output size).
• Laravel Config: Publish the config for project-specific overrides:

  php artisan vendor:publish --tag=laravel-ray-config
  

  Key options:

  'enabled' => env('RAY_ENABLED', false),
  'max_output_size' => 1024, // in KB
  'channels' => ['default', 'api', 'cli'],