Spatie Ray - Debug with Ray to fix problems faster in Laravel

Ray is a wonderful, lightweight desktop app that assists you to debug your application. There’s a free demo available that can be unlocked with a license. Ray supports PHP, Ruby, JavaScript, TypeScript, NodeJS, Go and Bash applications. After installing one of the libraries to send information to Ray, you can utilize the ray function to quickly dump stuff. Any variable(s) that you pass to ray will be displayed.

Download the app

You can download the Ray desktop application in these flavors:

• macOS (Intel)
• macOS (Apple Silicon)
• Windows
• Linux

When using macOS, you can also install Ray with Homebrew:

brew install --cask ray

Without a license, Ray allows you to send 10 items per session.

Requirements

• All PHP packages require PHP 7.3+ or higher.
• Laravel Ray requires Laravel 7 or higher.
• WordPress Ray requires WordPress 5.5 or higher
• Ruby Ray requires Ruby 3.0 or higher (may work on 2.6+).

Third-party package requirements:

• NodeJS support (node-ray) requires NodeJS 12 or higher.
• Vue support (vue-ray) requires Vue version 2.6+ or 3.0+.
• AlpineJS support (alpinejs-ray) requires Alpine.js 2.5.0 or higher.
• Go support (go-ray) is tested in Go 1.15 or higher

Installation in Laravel

To send information to the Ray desktop app, you’ll need to install a package or library in your project. If you use Laravel, you can install this package via composer:

composer require spatie/laravel-ray

By installing Ray this way it will also be installed in your production environment. This way your application will not break if you forget to remove a ray call. The package will not attempt to transmit information to Ray when the app environment is set to production.

Creating a config file

Optionally, you can run an artisan command to publish the config file into the project root.

php artisan ray:publish-config

You can also append an option for ‘docker’ or ‘homestead’ to give a base configuration for those dev environments.

php artisan ray:publish-config --docker

//or

php artisan ray:publish-config --homestead

Utilizing Ray in an Orchestra powered test suite

In order to use a Laravel specific functionality, you must call Ray’s service provider in your base test case.

// add this to your base test case

protected function getPackageProviders($app)
{
    return [
        \Spatie\LaravelRay\RayServiceProvider::class,
    ];
}

Usage

Inside a Laravel application, you can utilize all methods from the framework-agnostic version.
Additionally, you can use these Laravel specific methods.

Showing queries

You can represent all queries that are executed by calling showQueries (or queries).

ray()->showQueries();

User::firstWhere('email', 'john@example.com'); // this query will be displayed in Ray.

Counting Queries

If you’re interested in how many queries a given piece of code executes, and what the runtime of those queries is, you can use countQueries. It expects you to pass a closure in which all the executed queries will be counted.

ray()->countQueries(function() {
    User::all();
    User::all();
    User::all();
});

Manually showing a query

You can manually send a query to Ray by calling ray() on a query.

User::query()
    ->where('email', 'john@example.com')
    ->ray()
    ->first();

You can call ray() multiple times to see how a query is being built up.

User::query()
    ->where('first_name', 'John')
    ->ray()
    ->where('last_name', 'Doe')
    ->ray()
    ->first();

To stop showing events, call stopShowingEvents.

Showing Events

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

ray()->showEvents();
event(new TestEvent());
event(new TestEventWithParameter('my argument'));

To stop showing events, call stopShowingEvents.

Showing Jobs

You can display all jobs that are executed by calling showJobs (or jobs).

ray()->showJobs();
dispatch(new TestJob('my-test-job'));

To stop showing jobs, call stopShowingJobs.

Showing Cache Events

You can display all cache events using showCache

ray()->showCache()

Cache::put('my-key', ['a' => 1]);
Cache::get('my-key');
Cache::get('another-key');

To stop showing cache events, call stopShowingCache.

Showing HTTP Client Requests

You can display all HTTP client requests and responses using showHttpClientRequests

ray()->showHttpClientRequests();
Http::get('https://example.com/api/users');

To stop showing http client events, call stopShowingHttpClientRequests.

Handling Models

Using the model function, you can display the attributes and relations of a model.

ray()->model($user);

The model function can also accept multiple models and even collections.

// all of these models will be displayed in Ray
ray()->model($user, $anotherUser, $yetAnotherUser);

// all models in the collection will be display
ray()->model(User::all());

// all models in all collections will be displayed

ray()->model(User::all(), OtherModel::all());

Alternatively, you can use models() which is an alias for model().

Displaying Mailable

You can see the rendered version of mailable in Ray by passing a mailable to the mailable function.

ray()->mailable(new TestMailable());

Showing Which Views are Rendered

You can display all views that are rendered by calling showViews.

ray()->showViews();

// typically you'll do this in a controller
view('welcome', ['name' => 'John Doe'])->render();

There are a lot more features and options in Spatie/Ray package. If you want to dig more then you can visit its comprehensive documentation on its official website.