Our Ray Laravel Package

Getting Started

Minimal Setup

1. Installation: Add the package via Composer:

   composer require spatie/our-ray
   

2. Publish Config (Optional): Publish the config file for customization:

   php artisan vendor:publish --provider="Spatie\OurRay\OurRayServiceProvider"
   

3. First Use: Use the our() helper to send Ray payloads:

   our()->ray('Initial debug payload');
   

   • Ensure your .env has OURRAY_APP_KEY set (or use the default RAY_APP_KEY fallback).

Where to Look First

• Config File: config/our-ray.php (if published) for API key and endpoint settings.
• Helper Function: our() in your Blade templates, controllers, or services.
• Ray Documentation: myray.app for payload structure and features.

Implementation Patterns

Core Workflows

1. Debugging in Controllers/Commands

   public function processOrder(Request $request)
   {
       try {
           $order = Order::create($request->all());
           our()->ray('Order created', ['order_id' => $order->id]);
       } catch (\Exception $e) {
           our()->ray('Order creation failed', ['error' => $e->getMessage()]);
           throw $e;
       }
   }
   

   • Tip: Use our()->ray() for critical paths (e.g., payments, API calls).

2. Middleware for Global Debugging

   public function handle($request, Closure $next)
   {
       our()->ray('Request started', [
           'path' => $request->path(),
           'method' => $request->method(),
       ]);
       return $next($request);
   }
   

   • Use Case: Track request metadata (e.g., API gateways, queues).

3. Blade Templates

   @if(config('app.debug'))
       @php
           our()->ray('User viewed profile', ['user_id' => auth()->id()]);
       @endphp
   @endif
   

   • Tip: Wrap in config('app.debug') to avoid clutter in production.

4. Queue Jobs

   public function handle()
   {
       our()->ray('Job dispatched', ['job' => $this->job]);
       // Job logic...
   }
   

   • Use Case: Debug async processes (e.g., notifications, reports).

Integration Tips

• Laravel Logging: Combine with Log::debug() for structured logs:

  our()->ray('User login', ['ip' => $request->ip()]);
  Log::debug('Login attempt', ['user_agent' => $request->userAgent()]);
  

• Error Handling: Use App\Exceptions\Handler to log exceptions:

  public function report(Throwable $exception)
  {
      our()->ray('Unhandled exception', [
          'exception' => $exception->getMessage(),
          'trace' => $exception->getTraceAsString(),
      ]);
  }
  

• API Responses: Log incoming/outgoing data:

  our()->ray('API Response', [
      'status' => $response->status(),
      'data' => $response->getData(),
  ]);
  

Gotchas and Tips

Pitfalls

1. API Key Leaks

   • Risk: Hardcoding OURRAY_APP_KEY in config or environment files.
   • Fix: Use Laravel’s .env and restrict file permissions:

     chmod 600 .env
     

   • Tip: Rotate keys periodically via ourray.app dashboard.

2. Payload Size Limits

   • Issue: Large payloads (>1MB) may fail silently or truncate.
   • Fix: Use our()->ray()->chunk() for big data:

     our()->ray()->chunk($largeArray, 100); // Split into chunks of 100 items
     

   • Tip: Exclude sensitive data (e.g., passwords, tokens) via except():

     our()->ray($data)->except(['password', 'api_token']);
     

3. Rate Limiting

   • Problem: Excessive calls may hit rate limits (default: 60 requests/minute).
   • Solution: Throttle usage in middleware:

     public function handle($request, Closure $next)
     {
         if (our()->ray()->isRateLimited()) {
             our()->ray('Rate limit exceeded');
         }
         return $next($request);
     }
     

4. Environment-Specific Keys

   • Gotcha: Using the same key across dev/staging/prod.
   • Fix: Use environment-specific keys:

     OURRAY_APP_KEY=dev_key_123       # .env
     OURRAY_APP_KEY=prod_key_456      # .env.production
     

Debugging Tips

• Payload Validation: Use our()->ray()->validate() to check structure:

  our()->ray(['key' => 'value'])->validate();
  

• Network Issues: Verify connectivity to ourray.app:

  curl -v https://ourray.app/api/payloads
  

• Logs: Check Laravel logs for transport errors:

  tail -f storage/logs/laravel.log | grep "OurRay"
  

Extension Points

1. Custom Payload Formatter

   • Override the default formatter in a service provider:

     public function boot()
     {
         our()->extend(function ($payload) {
             return [
                 'custom_key' => 'value',
                 'original' => $payload,
             ];
         });
     }
     

2. Webhook Integration

   • Forward Ray payloads to a webhook:

     our()->onPayload(function ($payload) {
         Http::post('https://your-webhook.com', $payload);
     });
     

3. Conditional Logging

   • Disable Ray in CI or specific environments:

     if (!app()->environment('local')) {
         our()->disable();
     }
     

4. Batch Processing

   • Use our()->ray()->batch() for grouped payloads:

     our()->ray()->batch([
         'user_action_1',
         'user_action_2',
     ]);