Ray desktop debugging for Laravel (sponsor)

January 11, 2021 / Eric L. Barnes

Ray is a beautiful, lightweight desktop app for MacOS, Windows and Linux that helps you debug your Laravel application faster. Instead of sending your dump statements to the browser, you can send them to the Ray, where we can display them beautifully.

In this short demo, you can see it in action.

You can download a free demo now! At the time of writing, you can pick up a full license with a 30% discount.

Using Ray

To start using Ray in Laravel, all you need to do is install this small package.

composer require spatie/laravel-ray

After that, you can send anything you’d like to Ray. Here’s an example.

Here’s an example:

ray('my first debug statement'); 

This is what that looks like in Ray:

You can see that underneath the string we’ve sent to Ray, you see a link to where that ray statement was executing. Clicking that link will take you to that location in your IDE (we support PhpStorm, VScode, Sublime, and many others…).

That ray function accepts everything: strings, arrays, objects, … You can also pass as many arguments as you want.

ray('a string', ['a' => 1, 'b' => 2 , 'c' => 3], app());

Pieces of large arrays and large object arrays can be collapsed, much like you’re used to. In this screenshot, I’ve collapsed that large instance of Illuminate\Foundation\Application.

When you’re debugging medium-size problems, you probably have used multiple dump statements in the past. Some of those statements could be more important than others. In the past, I’ve distinguished between more and less important statements by writing dump statements in capitals, or by adding some extra characters, so that it catches my eye in between a log of output. Something like this:

dump('I AM HERE');
dump('-------- I AM HERE --------');

Instead of capitalizing or other tricks to make debugging information stand out, you can colorize statements you send to Ray.

ray('this is green')->green();
ray('this is orange')->orange();
ray('this is red')->red();
ray('this is blue')->blue();
ray('this is purple')->purple();
ray('this is gray')->gray();

See those little colored dots at the top of the UI? You can use those to filter out items with that color. Here’s how it looks like with the blue filter activated:

Do you think Ray is too bright for your eyes? You’ll be happy to now that there’s also a dark theme. This is what it looks like.

Quickly measuring performance

You might want to know how long a certain piece of code takes to run and how much memory it takes. You can easily measure performance by calling ray()->measure(). The first time that it is called, Ray will start to measure performance. The second time measure() is called, it will display the amount of time between the second and first call.

Here’s an example:

ray()->measure();

sleep(1);

ray()->measure();

sleep(2);

ray()->measure();

Here is what that looks like in Ray:

Pausing the execution of your code

This feature is a little bit mind-blowing: Ray can pause your code. This can be useful when you want to see your code’s side effects (what got written to the DB, which API calls were executed?) before continuing.

In this example, we will loop over each user, alter that user somehow, and pause the code.

User::each(function(User $user) {
    $user->performSomeSortOfUpdateOrSideEffect();

    ray("Executed loop for user {$user->id}")->pause();
})

After you’ve checked in the DB if everything is ok, you can press “continue” in Ray to execute the code for the next user. If you want to stop execution, press “Stop” to have an exception thrown in your app.

Seeing where a function is called

Sometimes you want to know where your code is being called. You can quickly determine that by using the caller function.

ray()->caller();

If you want to see the entire backtrace, use the trace method:

ray()->trace();

Displaying a model

If you dump an Eloquent model, you see many internals of that model that you mostly don’t need.

In most cases, you want to see the attributes and/or loaded relations. Calling model() does just that.

ray()->model($user);

Displaying all queries

You can send all queries that your code performs to Ray by calling ray()->showQueries();

ray()->showQueries();

User::whereFirst('email', 'john@example.com'); 

In Ray, we display the executed query with all parameters inlined. You also see the time that was needed to execute the query. Ray even shows you where the query was executed. You can click that link to jump to the origin of the query.

If you don’t want to send any queries anymore after a certain point in your code, you can call ray()->stopShowingQueries().

Alternatively, you can pass a closure to showQueries to only show the executed queries in the given callable.

ray()->showQueries(function() {
    // some code that executes queries
});

Displaying log items (and mailables!)

By default, anything that is sent to the log is displayed in Ray as well.

// these are automatically sent to Ray
Log::info('using the facade to log something');
info('using the helper function to log something');

In a fresh Laravel application, any mails you send are written to the log file (as the log driver is the default mail driver). Here’s a cool feature: whenever Ray detects that a mail is written to the log, it will display that mailable.

// sending any mail when the log mailer is active,
// will render that mail-in Ray.

Mail::to('john@example.com')->send(new MyMailable());

This is what that looks like:

Displaying collections

In a Laravel app, Ray will automatically register a ray collection macro to send collections to Ray easily.

collect(['a', 'b', 'c'])
    ->ray('original collection') // displays the original collection
    ->map(fn(string $letter) => strtoupper($letter))
    ->ray('uppercased collection') // displays the modified collection

Using Ray in Blade views

You can use the @ray directive to send variables to Ray from inside a Blade view easily. You can pass as many things as you’d like.

{{-- inside a view --}}

@ray($variable, $anotherVariables)

Showing events

You can display all events that are executed by calling showEvents.

ray()->showEvents();

event(new TestEvent());

event(new TestEventWithParameter('my argument'));

To stop showing events, call stopShowingEvents.

ray()->showEvents();

event(new MyEvent()); // this event will be displayed

ray()->stopShowingEvents();

event(new MyOtherEvent()); // this event won't be displayed.

Alternatively, you can pass a callable to showEvents. Only the events fired inside that callable will be displayed in Ray.

event(new MyEvent()); // this event won't be displayed.

ray()->showEvents(function() {
    event(new MyEvent()); // this event will be displayed.
});

event(new MyEvent()); // this event won't be displayed.

In closing

The demo version of Ray allows you to send ten items per session to Ray. To send more things per session, you can pick up a license. At the time of writing, we’re running a cool promo that allows you to save a couple of bucks.

Filed in: News