{"id":632,"date":"2025-09-05T11:29:42","date_gmt":"2025-09-05T11:29:42","guid":{"rendered":"https:\/\/1v0.net\/blog\/?p=632"},"modified":"2025-09-05T11:29:45","modified_gmt":"2025-09-05T11:29:45","slug":"debugging-laravel-applications-with-ray-and-telescope","status":"publish","type":"post","link":"https:\/\/1v0.net\/blog\/debugging-laravel-applications-with-ray-and-telescope\/","title":{"rendered":"Debugging Laravel Applications with Ray and Telescope"},"content":{"rendered":"\n

Debugging is a critical part of building reliable Laravel applications. While dd()<\/code> and dump()<\/code> are quick solutions, they don\u2019t scale well for complex apps. Laravel offers powerful debugging tools like Telescope<\/strong> for application-wide monitoring, and third-party tools like Ray<\/strong> to simplify debugging during development. In this article, we\u2019ll explore both tools, show how to set them up, and walk through real-world debugging workflows.<\/p>\n\n\n\n

<\/div>\n\n\n\n

Installing Ray for Debugging<\/strong><\/h2>\n\n\n
composer require spatie\/laravel-ray --dev<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
Ray<\/a> is a desktop app by Spatie that displays debugging output in a clear, interactive interface. Once installed, you can use the ray()<\/code> helper function anywhere in your Laravel app. Ray captures variables, queries, jobs, and more \u2014 without polluting your HTML responses or logs.<\/p>\n\n\n\n
Basic Usage<\/strong><\/h3>\n\n\n
ray('Hello from Laravel'<\/span>);\nray($user);\nray($request->all());<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This sends text, objects, or arrays to the Ray desktop client. It works like dd()<\/code> but doesn\u2019t halt execution. You can also chain styles and colors to organize debugging output.<\/p>\n\n\n\n
Debugging Queries with Ray<\/strong><\/h3>\n\n\n
\/\/ In AppServiceProvider or a debug-only service provider<\/span>\n\\Illuminate\\Support\\Facades\\DB::listen(function<\/span> ($query)<\/span> <\/span>{\n    ray($query->sql, $query->bindings, $query->time);\n});<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Ray displays executed queries, bindings, and execution time. This makes query optimization easier during development.<\/p>\n\n\n\n
Debugging Jobs and Events<\/strong><\/h3>\n\n\n
ray()->showJobs();\nray()->showEvents();<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Ray can automatically show when jobs are dispatched or events are fired, helping you track async flows in your app.<\/p>\n\n\n\n
<\/div>\n\n\n\n
Installing and Using Laravel Telescope<\/strong><\/h2>\n\n\n
composer require laravel\/telescope --dev\nphp artisan telescope:install\nphp artisan migrate<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
Telescope<\/a> is Laravel\u2019s official debugging assistant. It provides a dashboard at \/telescope<\/code> where you can view requests, jobs, events, queries, logs, cache hits, and more. It\u2019s particularly powerful for tracking production issues when paired with access restrictions.<\/p>\n\n\n\n
Tracking Requests and Responses<\/strong><\/h3>\n\n\n
\/\/ Example: telescope shows request lifecycle<\/span>\nGET \/posts\/1<\/span>\n- Controller: PostController@show\n- Queries: 2<\/span> (45<\/span>ms)\n- Response: 200<\/span> OK<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
The Requests tab in Telescope shows complete details about each incoming request, including middleware, response time, and database queries executed during that request.<\/p>\n\n\n\n
Monitoring Queries<\/strong><\/h3>\n\n\n\n
Telescope logs all queries executed in your app, including N+1 query problems. It highlights slow queries, so you can quickly identify bottlenecks.<\/p>\n\n\n\n
Jobs, Events, and Cache<\/strong><\/h3>\n\n\n\n
From the dashboard, you can see when jobs are dispatched, events are triggered, and cache hits or misses occur. This visibility helps debug background tasks and performance issues.<\/p>\n\n\n\n
<\/div>\n\n\n\n
Securing Telescope in Production<\/strong><\/h2>\n\n\n\n
Telescope can expose sensitive information. Protect it with authorization gates:<\/p>\n\n\n
\/\/ app\/Providers\/TelescopeServiceProvider.php<\/span>\nuse<\/span> Laravel<\/span>\\Telescope<\/span>\\Telescope<\/span>;\n\nTelescope::auth(function<\/span> ($request)<\/span> <\/span>{\n    return<\/span> in_array($request->user()?->email, [\n        'admin@example.com'<\/span>,\n    ]);\n});<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This ensures that only authorized developers can access Telescope in production environments. Always secure it before deployment.<\/p>\n\n\n\n
<\/div>\n\n\n\n
Ray vs Telescope: When to Use Each<\/strong><\/h2>\n\n\n\n
Feature<\/th>Ray<\/th>Telescope<\/th><\/tr><\/thead>
Scope<\/td>Developer-focused debugging<\/td>App-wide request monitoring<\/td><\/tr>
Best for<\/td>Quick dumps, inspecting variables, dev feedback<\/td>Tracking queries, jobs, events, logs<\/td><\/tr>
UI<\/td>Desktop client<\/td>Web dashboard at \/telescope<\/td><\/tr>
Environment<\/td>Local development only<\/td>Local + Production (with access control)<\/td><\/tr>
Integration<\/td>Simple ray() calls in code<\/td>Automatic hooks into Laravel internals<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Use Ray for quick, developer-centric debugging. Use Telescope for request and system-wide insights. Many teams run both in parallel: Ray locally, Telescope in staging\/production.<\/p>\n\n\n\n
<\/div>\n\n\n\n
Wrapping Up<\/strong><\/h2>\n\n\n\n
Debugging effectively saves hours of guesswork. Ray is perfect for rapid feedback during development, while Telescope gives you full visibility into requests, queries, and background jobs. Together, they provide a powerful toolkit for debugging Laravel apps across environments.<\/p>\n\n\n\n
<\/div>\n\n\n\n
What\u2019s Next<\/strong><\/h2>\n\n\n\n
For further monitoring and debugging, check out these guides:<\/p>\n\n\n\n