Laravel Ray Laravel Package

Product Decisions This Supports

• Debugging Efficiency: Accelerates developer onboarding and troubleshooting by replacing dd(), dump(), and Log::debug() with a unified, interactive desktop tool (Ray). Reduces context-switching between terminal, browser, and IDE.
• Observability Roadmap: Enables structured logging, query inspection, and performance profiling without modifying core Laravel logging systems. Aligns with initiatives to improve developer experience (DX) and reduce debugging friction.
• Build vs. Buy: Buy—avoids reinventing a debugging UI/UX. The package integrates seamlessly with Laravel’s ecosystem (e.g., queries, Blade, emails) and leverages Spatie’s battle-tested Ray app (no maintenance overhead).
• Use Cases:
  • Debugging Complex Workflows: Visualize request flows, middleware execution, and service interactions in real-time (e.g., payment processing, multi-step forms).
  • Query Optimization: Inspect raw SQL, bindings, and execution times for slow queries without enabling Laravel’s query logging globally.
  • Blade/Template Debugging: Use @ray directives to inspect variables in views dynamically (e.g., debugging dynamic content generation).
  • Performance Profiling: Measure execution time of critical paths (e.g., API endpoints, background jobs) with @measure directives.
  • Error Context: Attach rich context (e.g., user sessions, request payloads) to exceptions for faster root-cause analysis.
  • AI/ML Debugging: Log predictions, model inputs/outputs, and data transformations for ML pipelines built in Laravel.

When to Consider This Package

• Adopt When:

  • Your team spends >20% of dev time debugging Laravel-specific issues (queries, Blade, services).
  • You need cross-language debugging (PHP + JavaScript/TypeScript) in a unified tool (Ray supports all three).
  • Your app uses complex workflows (e.g., state machines, event-driven architectures) where step-by-step inspection is critical.
  • You’re migrating to Laravel 11/12/13 and want modern debugging tools without legacy constraints.
  • Your team values developer productivity over minimalist logging (e.g., replacing dd() with interactive Ray panels).
  • You need performance insights without integrating APM tools (e.g., New Relic, Blackfire).

• Look Elsewhere If:

  • Your debugging needs are simple (e.g., only dd() usage in a small team).
  • You’re constrained by budget (Ray requires a paid license for full features; free tier has limits).
  • Your stack is non-Laravel (e.g., Symfony, WordPress) or uses non-PHP backends.
  • You prefer terminal-only debugging (e.g., Tideways, Laravel Telescope) or server-side logs (ELK, Datadog).
  • Your app has strict security policies prohibiting local desktop tools (Ray runs locally, but data is not sent to cloud by default).

How to Pitch It (Stakeholders)

For Executives:

*"Laravel-Ray lets our developers debug 10x faster by replacing clunky dd() calls with a real-time, interactive desktop dashboard—like Chrome DevTools for PHP. It’s a force multiplier for:

• Reducing debugging time (e.g., cutting query optimization from hours to minutes).
• Improving onboarding (new devs get context instantly with @ray directives in Blade/queries).
• Lowering support costs (rich error context speeds up triaging production issues). The free tier covers most use cases, and the paid license ($99/year) unlocks unlimited debugging—far cheaper than hiring a senior dev to ‘figure it out.’"*

ROI: "For every 1 hour saved per developer per week, this pays for itself in 3 months."

For Engineering Teams:

*"Laravel-Ray integrates Ray—a Swiss Army knife for debugging—into Laravel with zero config. Key wins:

• Unified Debugging: Replace dump(), Log::debug(), and dd() with @ray() (supports arrays, queries, Blade variables, and even Markdown).
• Query Superpowers: See exact SQL + bindings for any query, with execution time metrics—no more guessing why a join is slow.
• Blade Debugging: Use @ray($variable) in views to inspect dynamic content (e.g., ‘Why is this loop breaking?’).
• Performance Profiling: Add @measure around critical code to find bottlenecks (e.g., ‘Why is this API endpoint taking 2s?’).
• Exception Context: Attach request data, user sessions, or custom metadata to errors for faster fixes.
• Cross-Language: Debug PHP and JavaScript/TypeScript in the same tool (Ray supports all three).

How to Start:

1. Install: composer require spatie/laravel-ray.
2. Run php artisan ray:install and launch the Ray desktop app.
3. Replace dd($user) with @ray($user) in your code.

Trade-offs:

• Requires local Ray app (not cloud-based; data stays on dev machines).
• Free tier limits 20 messages/session (sufficient for most debugging)."*