Ray Laravel Package

Technical Evaluation

Architecture Fit

• Debugging Paradigm: Spatie/Ray aligns perfectly with modern debugging workflows by replacing traditional dd(), var_dump(), and logging with a real-time, interactive desktop UI. This is particularly valuable for Laravel applications where complex state (e.g., Eloquent models, API responses, or middleware chains) requires deep inspection.
• Laravel Integration: The package is Laravel-optimized (supports Laravel 12/13) and integrates seamlessly with Laravel’s service container, logging, and testing ecosystems. It extends Laravel’s dump() and log() helpers while adding features like query tracing, performance metrics, and AI-assisted debugging.
• Cross-Language Synergy: Ray’s unified debugging syntax (shared with JavaScript/TypeScript) reduces context-switching for full-stack teams, though this is secondary for PHP-only Laravel apps.

Integration Feasibility

• Low Friction: Installation is a single composer require + config publish (php artisan vendor:publish --provider="Spatie\Ray\RayServiceProvider"). No database migrations or schema changes are required.
• Backward Compatibility: Supports PHP 8.1–8.5 and Laravel 10–13, with deprecation fixes for PHP 8.5 (e.g., Typed property warnings). The RemoveRayCallRector (PHPStan/Rector) allows safe removal of debug code post-deployment.
• Performance Impact: Minimal in production (disabled by default via .env). Debug overhead is negligible in development due to lazy evaluation and WebSocket-based streaming.

Technical Risk

• Dependency Bloat: Ray introduces a desktop app dependency (myray.app), which may require:
  • Network access (WebSocket to localhost:8000 by default).
  • Local installation (free trial limits 20 messages/session).
  • License cost for production use (MIT for the package, but Ray app requires a paid license for teams).
• Debugging Overhead: Excessive ray() calls in production could clutter logs or bloat payloads if not guarded (e.g., if (app()->environment('local'))).
• Stateful Debugging: Complex objects (e.g., closures, generators) may break inspection or require manual expansion (e.g., ->expand()).
• Testing Quirks: Ray’s Pest integration and Livewire component handling (fixed in v1.37.4) may need validation in custom test suites.

Key Questions

1. Licensing: Will the team adopt a paid Ray license for production debugging, or rely on the free tier for development only?
2. Security: How will Ray’s WebSocket endpoint (/ray) be secured in shared environments (e.g., CI/CD, staging)? Is it restricted to localhost?
3. Cost vs. Value: For teams already using Laravel Telescope or Blackfire, does Ray’s unified debugging justify the switch?
4. Adoption Barrier: Will developers replace dd()/log() with ray() consistently, or will it remain a "power-user" tool?
5. Performance: How will Ray’s payload size scale with high-frequency debugging in long-running processes (e.g., queues, cron jobs)?

Integration Approach

Stack Fit

• Laravel Ecosystem: Native support for:
  • Eloquent: Query tracing, model inspection.
  • Livewire: Component state debugging (fixed in v1.37.4).
  • Testing: Pest/PHPUnit integration with screen names and test context.
  • Logging: Extends Monolog with ray() as a handler.
• PHP Extensions: Works with Symfony components (e.g., VarDumper, HTTP Client) and custom objects via __debugInfo().
• Non-Laravel PHP: Supports vanilla PHP (e.g., CLI scripts, Symfony apps) but lacks Laravel-specific features like route/model binding.

Migration Path

1. Pilot Phase:
   • Install in a non-production environment (composer require spatie/ray).
   • Replace critical dd() calls with ray() in high-value flows (e.g., payment processing, API endpoints).
   • Use ray()->ignoreFn() to exclude sensitive data (e.g., passwords, tokens).
2. Gradual Adoption:
   • Service Layer: Debug DTOs, repositories, and service responses.
   • Middleware: Inspect request/response cycles.
   • Jobs/Queues: Attach ray() to job payloads (e.g., ray($job->payload)).
3. Tooling Integration:
   • Configure PHPStorm/Xdebug to trigger Ray on breakpoints.
   • Use ray()->pause() for step-through debugging in the Ray UI.
4. Cleanup:
   • Leverage RemoveRayCallRector to strip debug code before production.
   • Set RAY_ENABLED=false in .env for non-debug environments.

Compatibility

Sequencing

1. Phase 1 (Week 1):
   • Install Ray and configure .env/config/ray.php.
   • Replace 3–5 critical dd() calls with ray().
   • Validate query tracing and model inspection.
2. Phase 2 (Week 2):
   • Integrate with testing (Pest/PHPUnit).
   • Debug Livewire components and middleware.
3. Phase 3 (Week 3):
   • Adopt in service layer and jobs.
   • Implement ray() in CI/CD for failure debugging.
4. Phase 4 (Ongoing):
   • Train team on Ray-specific features (e.g., invade(), expand()).
   • Monitor payload size and performance impact.

Operational Impact

Maintenance

• Configuration: Minimal (ray.php and .env settings). Key options:
  • ignore_fn: Exclude sensitive data (e.g., ray()->ignoreFn(fn($var) => $var instanceof User)).
  • max_payload_size: Limit payload size (default: 1MB).
  • enabled: Toggle via .env (RAY_ENABLED=true).
• Updates: Follow Spatie’s active release cycle (monthly updates). Breaking changes are rare (e.g., PHP 8.5 fixes).
• Logging: Ray extends Monolog, so logs are centralized but may require filtering to avoid noise.

Support

• Troubleshooting:
  • Network Issues: Ensure WebSocket access (localhost:8000) is open.
  • Payload Errors: Use ray()->expand() for complex objects or increase max_payload_size.
  • Performance: Disable in production or use if (app()->isLocal()).
• Community: Active GitHub issues (1.4k+ stars) and Spatie’s support channels.
• Enterprise: Paid Ray license includes priority support and team collaboration features.

Scaling

• Development: Zero impact; real-time debugging accelerates iteration.
• Staging/Production:
  • Disabled by default (via .env).
  • Conditional Usage: Guard with if (app()->environment('local')).
  • Payload Limits: Configure max_payload_size to avoid memory issues.
• Microservices: Ray’s per-request context works well in distributed systems, but cross-service debugging requires manual correlation (e.g., request IDs).

Failure Modes