Ray Laravel Package

Technical Evaluation

Architecture Fit

• Debugging-First Philosophy: spatie/ray aligns perfectly with Laravel’s debugging ecosystem (e.g., Laravel Debugbar, Tinker). It replaces dd(), dump(), and log() with a real-time, interactive desktop UI, reducing context-switching between terminal/IDE and browser.
• Modularity: The package is framework-agnostic but integrates seamlessly with Laravel’s service container, event system, and middleware. It can be adopted incrementally (e.g., only in development) without architectural refactoring.
• Observability Layer: Acts as a centralized logging/debugging layer, complementing Laravel’s built-in tools (e.g., Log::channel(), Sentry). Supports structured data (queries, exceptions, variables) with rich formatting (Markdown, HTML, tables).
• Performance Profiling: Includes execution timing (e.g., ray()->stop('query')), enabling micro-optimizations without external tools like Blackfire.

Integration Feasibility

• Laravel-Specific Features:
  • Pre-configured for Laravel’s config/ray.php (supports queues, middleware, service providers).
  • Laravel Debugbar integration: Ray messages appear in Debugbar’s panel.
  • Livewire/Inertia support: Captures component state and props.
  • Queue workers: Debugs jobs/consumers via ray()->job().
• Non-Laravel PHP: Works in vanilla PHP (CLI, Symfony, Lumen) but lacks Laravel’s conveniences (e.g., Facade, service binding).
• Database/Query Debugging:
  • Logs raw SQL, bindings, and execution time (via DB::listen or QueryObserver).
  • Query replay: Click to execute logged queries in a DB client.
• Exception Handling:
  • Replaces try-catch debugging with stack traces in Ray’s UI, including variable states at each step.

Technical Risk

Key Questions for TPM

1. Debugging Workflow:
   • Will teams use Ray exclusively (replacing dd()/log()) or complementarily (e.g., for complex queries)?
   • Should Ray be mandatory in CI (e.g., for failed tests) or opt-in?
2. Data Sensitivity:
   • Are there PII/PCI compliance concerns? If so, enforce strict blacklists in ray.php.
   • Should production-like data be allowed in staging (e.g., for QA debugging)?
3. Tooling Integration:
   • Should Ray integrate with existing monitoring (e.g., Datadog, New Relic) via webhooks?
   • Will custom payloads (e.g., API request/response pairs) be needed? Extend via afterSendCallbacks.
4. Performance Budget:
   • For high-traffic endpoints, will Ray’s payload size impact response times? Test with ray()->ignore() for critical paths.
5. Onboarding:
   • Should a Ray "cheat sheet" be added to the dev portal?
   • Will pair programming sessions require Ray setup? Document Docker/remote debugging.

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • First-Class Citizen: Works with Laravel’s Facades, Service Container, and Events (e.g., Ray::log('Event fired')).
  • Middleware: Add RayMiddleware to log requests/responses globally.
  • Testing: Integrates with Pest/Laravel Tests (e.g., ray()->seeInLastRequest()).
• Non-Laravel:
  • Symfony: Use Ray::capture() in controllers/services.
  • CLI: Debug Artisan commands with ray()->table($users).
  • Livewire/Inertia: Captures component props/states automatically.
• Database:
  • Eloquent: Logs queries via DB::listen or QueryObserver.
  • Raw SQL: Use ray()->query($sql, $bindings) for ad-hoc debugging.
• Queues/Jobs:
  • Log jobs via ray()->job($job, 'Processing order').
  • Debug failed jobs with ray()->exception($e) in HandleFailures.

Migration Path

Compatibility

• Laravel Versions: Officially supports 10.x–13.x. Laravel 9.x via 1.x branch.
• PHP Versions: 8.1–8.5 (PHP 7.4+ with legacy branch). Test for PHP 8.6 compatibility.
• Dependencies:
  • Symfony Components: Uses VarDumper, HttpFoundation (no conflicts).
  • Livewire/Inertia: Auto-detects components; no manual setup.
  • Queues: Works with database, Redis, SQS (via Ray::job()).
• IDE/Editor: No plugins needed; Ray’s desktop app handles rendering.

Sequencing

1. Installation:

   composer require spatie/ray --dev
   php artisan vendor:publish --provider="Spatie\Ray\RayServiceProvider"
   

2. Configuration:
   • Enable in config/ray.php:

     'enabled' => env('RAY_ENABLED', false),
     'ignore_exceptions' => [\SensitiveDataException::class],
     

3. Basic Usage:

   use Spatie\Ray\Ray;
   
   Ray::info('User logged in', ['user_id' => 123]);
   Ray::dump($user); // Replaces dd()
   Ray::query($query->toSql(), $query->getBindings());
   

4. Advanced:
   • Middleware: Log requests/responses.
   • Events: Ray::log('Order created', ['order' => $order]).
   • Custom Payloads: Extend RayServiceProvider for domain-specific data.

Operational Impact

Maintenance

• Package Updates:
  • Automated: Use composer require spatie/ray --dev with update scripts.
  • Testing: Add to CI:

    # .github/workflows/test.yml
    - name: Test Ray
      run: php artisan ray:test
    

• Configuration Drift:
  • Centralized: Manage config/ray.php via Laravel Envoy or Terraform.
  • Blacklists: Maintain a team-wide list of sensitive fields (e.g., password, api_key).
• Deprecations:
  • Monitor PHP 8.5+ deprecations (e.g., self:: → static::). Use rector for auto-fixes:

    composer require rector/rector --dev
    vendor/bin/rector process src --dry-run
    

Support

• Troubleshooting:
  • Common Issues:
    • Ray not receiving logs: Check RAY_ENABLED env var, firewall (port 8080), or queue:work processes.
    • Large payloads: Use ray()->ignore() or increase ray.max_payload_size.
  • Debugging Ray Itself:

    RAY