README

A lightweight Ray-like debugging tool for Laravel applications with a web-based debug viewer.

Features

• ray() helper function for quick debugging
• Automatic slow query logging (configurable threshold)
• Request profiling middleware (N+1 detection, memory usage)
• Mail driver that records sent emails to the viewer (great for tests)
• Web-based debug viewer at /debug/ray
• Color-coded entries (red, orange, yellow, green, blue)
• Configurable access control via email whitelist

Requirements

• PHP 8.2+
• Laravel 11 or 12

Installation

composer require rayzenai/ray

Configuration

Publish the config file:

php artisan vendor:publish --tag=ray-config

This creates config/ray.php:

return [
    // Define allowed users by email
    // Use ['*'] to allow all authenticated users
    'allowed_emails' => [
        // '*',
        // 'admin@example.com',
    ],

    // User model configuration (for apps with custom user tables)
    'user_model' => \App\Models\User::class,
    'user_email_field' => 'email',

    // Queries slower than this (ms) are auto-logged
    'slow_query_threshold' => 100,

    // Max debug entries to keep
    'max_entries' => 100,

    // Storage location
    'storage_path' => storage_path('logs/ray-debug.json'),
];

Usage

Basic Debugging

// Simple debug
ray($variable);

// With label — when two arguments are passed, the first becomes the label
ray('user data', $user);

// With colors
ray($data)->red();
ray($data)->green();
ray($data)->blue();
ray($data)->yellow();
ray($data)->orange();
ray($data)->purple();

// Chained
ray($data)->label('My Label')->green();

// Pause — highlights the entry as paused (orange) so it stands out in the viewer
ray($data)->pause();

// Inline — log and return the original value so you can wrap an expression
$user = ray($repository->find($id))->label('user')->value();

Static Methods

// Semantic logging
Ray::error($data);    // Red
Ray::warning($data);  // Yellow
Ray::success($data);  // Green
Ray::info($data);     // Blue

// Performance
Ray::measure('label');        // Start timer
// ... code ...
Ray::measure('label');        // Stop & log elapsed time

Ray::memory();                // Log memory usage

// Debugging
Ray::trace();                 // Log stack trace
Ray::caller();                // Log caller info

// Query logging
Ray::showQueries();           // Start logging all queries
Ray::showSlowQueries(50);     // Log queries > 50ms
Ray::stopQueries();           // Stop logging
Ray::querySummary();          // Get query stats

Counter

// Count iterations
foreach ($items as $item) {
    Ray::count('loop');       // Increments each call
}

Ray::resetCount('loop');      // Reset counter

Die & Dump

ray($data)->die();            // Log and exit

// Or use helper
rayDie($data, 'label');

Request Profiler Middleware

Add the middleware to log slow requests and detect N+1 queries:

// app/Http/Kernel.php
protected $middlewareGroups = [
    'web' => [
        // ... other middleware
        \RayzenAI\Ray\Middleware\RayRequestProfiler::class,
    ],
];

The profiler automatically logs:

• Requests taking > 100ms
• Requests using > 25MB memory
• N+1 query detection (same query 3+ times)

Mail Driver

Ray ships a Symfony mailer transport that records every outgoing email to the debug viewer instead of sending it. Perfect for inspecting mails generated by tests or local seeders.

Add it to config/mail.php:

'mailers' => [
    // ...
    'ray' => [
        'transport' => 'ray',
    ],
],

Then point your environment at it (typically in .env.testing or phpunit.xml):

MAIL_MAILER=ray

Recorded mails show up under the Mail tab at /debug/ray with full headers, an HTML preview (rendered in a sandboxed iframe), the text alternative, and an attachment summary. The transport itself works in any environment — only the viewer is gated to local.

Debug Viewer

Once installed, the package automatically registers the dashboard route. Open it in your browser at:

http://your-app.test/debug/ray

The route is registered with the web middleware group under the debug/ray prefix, and is only accessible in the local environment. Access is further restricted by the allowed_emails config (see Security).

Features:

• Tabs: Debug, Mail, Requests, Queries
• Color filters
• Search
• Auto-refresh toggle
• Expand/collapse entries
• Copy to clipboard
• Delete individual entries or clear all

Security

The package only works in local environment. Access is controlled by:

1. Empty config - Shows error message prompting configuration
2. Wildcard ['*'] - Allows all authenticated users
3. Email list - Only specified emails can access

License

MIT