Laravel Ray

spatie/laravel-ray is the Laravel integration for Ray, a desktop debugging application built by Spatie. It lets developers send variables, queries, HTML, Markdown, and other debug output from a running Laravel app straight to the Ray desktop window instead of dumping to the browser or log files.

The package wraps Ray’s underlying debugging protocol with Laravel-specific conveniences: automatic query watchers, job/event/mail watchers, a ray() helper mirroring dd()/dump(), and integration with Laravel’s exception handler so unhandled errors show up in Ray automatically. Ray itself is a separate, commercially-licensed desktop app (free trial capped at 20 messages per session); this package is the open-source client that talks to it.

What You Get

• A global ray() helper for sending variables, arrays, HTML, and Markdown to the Ray desktop app
• Built-in watchers for Eloquent queries, jobs, events, mail, and cache operations
• Automatic forwarding of unhandled Laravel exceptions to Ray
• Performance measurement helpers (ray()->measure()) and execution pausing for step-through debugging
• Artisan commands to enable/disable Ray output per environment

Common Use Cases

• Replacing dd()/dump() debugging with a persistent, searchable desktop debug window
• Watching Eloquent queries and job dispatches live while developing a feature locally
• Tracing exceptions and their context during local development without tailing log files
• Measuring the execution time of specific code paths during performance investigation

Under The Hood

Architecture - RayServiceProvider boots a set of Watchers/ (Query, Job, Event, Mail, Cache) that hook into Laravel’s own event/manager dispatch points and forward captured data through a central Ray class, which serializes it into Payloads/ objects and ships them over Ray’s client protocol via RayProxy. The exception-handler integration wraps Laravel’s default handler so uncaught exceptions are forwarded the same way as manual ray() calls. Tech Stack - Pure PHP targeting Laravel’s service container/event system, with DumpRecorder hooking Symfony VarDumper’s cloning mechanism to capture rich variable representations (objects, collections) rather than plain var_export output. Code Quality - 36 test files cover the watchers, payload serialization, and helper functions; CI runs both a test suite and PHPStan static analysis, and the project has shipped 100 tagged releases since 2020, indicating steady incremental maintenance rather than large rewrites. API Design - The core interaction is a single global ray() helper mirroring dd()/dump(), so existing debugging habits transfer immediately; watchers and exception forwarding require no code changes once installed, trading a small amount of magic for a very low activation barrier.