Laravel

Inside a Laravel application, you can use all methods from the framework agnostic version.

Additionally, you can use these Laravel specific methods. Sometimes you may want to log something to ray and get the resulting return value of your closure instead of an instance of Ray. You can achieve this by adding a return value type to your closure. See the examples for showQueries() and countQueries() below. Any other methods that accept a closure will function the same way.

Showing queries

You can display 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.

To stop showing queries, call stopShowingQueries.

ray()->showQueries();

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

ray()->stopShowingQueries();

User::firstWhere('email', 'jane@example.com'); // this query won't be displayed.

Alternatively, you can pass a callable to showQueries. Only the queries performed inside that callable will be displayed in Ray. If you include a return type in the callable, the return value will also be returned.

User::all(); // this query won't be displayed.

ray()->showQueries(function() {
    User::all(); // this query will be displayed.
});

$users = ray()->showQueries(function (): Illuminate\Support\Collection {
    return User::all(); // this query will be displayed and the collection will be returned.
});

User::all(); // this query won't be displayed.

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.

Similar to showQueries, you can also add a return type to your closure to return the result of the closure.

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

$user = ray()->countQueries(function (): User {
    return User::where('condition', true)->first();
});

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();

Showing duplicate queries

You can display all duplicate queries by calling showDuplicateQueries.

ray()->showDuplicateQueries();

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

To stop showing duplicate queries, call stopShowingDuplicateQueries.

Alternatively, you can pass a callable to showDuplicateQueries. Only the duplicate queries performed inside that callable will be displayed in Ray.

User::all();
User::all(); // this query won't be displayed.

ray()->showDuplicateQueries(function() {
    User::where('id', 1)->get('id');
    User::where('id', 1)->get('id'); // this query will be displayed.
});

User::all();
User::all(); // this query won't be displayed.

Showing slow queries

You can display all queries that took longer than a specified number of milliseconds to execute by calling showSlowQueries.

ray()->showSlowQueries(100);

// this query will only be displayed in Ray if it takes longer than 100ms to execute.
User::firstWhere('email', 'john@example.com');

Alternatively, you can also pass a callable to showSlowQueries. Only the slow queries performed inside that callable will be displayed in Ray.

User::all();
User::all(); // this query won't be displayed.

ray()->showSlowQueries(100, function() {
    User::where('id', 1)->get('id'); // this query will be displayed if it takes longer than 100ms.
});

You can also use the shorthand method, slowQueries():

ray()->slowQueries(); // equivalent to calling 'showSlowQueries'.

To stop showing slow queries, call stopShowingSlowQueries.

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.

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.

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.

ray()->showJobs();

dispatch(new TestJob()); // this job will be displayed

ray()->stopShowingJobs();

dispatch(new MyTestOtherJob()); // this job won't be displayed.

Alternatively, you can pass a callable to showJobs. Only the jobs dispatch inside that callable will be displayed in Ray.

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

ray()->showJobs(function() {
    dispatch(new TestJob()); // this job will be displayed.
});

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

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.

Alternatively, you can pass a callable to showHttpClientRequests. Only the http requests made inside that callable will be displayed in Ray.

Http::get('https://example.com'); // this request won't be displayed.

ray()->showHttpClientRequests(function() {
    Http::get('https://example.com'); // this request will be displayed.
});

Http::get('https://example.com'); // this request won't be displayed.

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 mailables

Mails that are sent to the log mailer are automatically shown in Ray, you can also display the rendered version of a specific 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();

To stop showing views, call stopShowingViews.

Displaying markdown

View the rendered version of a markdown string in Ray by calling the markdown function.

ray()->markdown('# Hello World');

Displaying collections

Ray will automatically register a ray collection macro to easily send collections to ray.

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

Usage with a `Stringable`

Ray will automatically register a ray macro to Stringable to easily send Stringables to Ray.

Str::of('Lorem')
   ->append(' Ipsum')
   ->ray()
   ->append(' Dolor Sit Amen');

Displaying environment variables

You can use the env() method to display all environment variables as loaded from your .env file. You may optionally pass an array of variable names to exclusively display.

ray()->env();

ray()->env(['APP_NAME', 'DB_DATABASE', 'DB_HOSTNAME', 'DB_PORT']);

Using Ray in Blade views

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

{{-- inside a view --}}

@ray($variable, $anotherVariables)

Using Ray with test responses

When testing responses, you can send a TestResponse to Ray using the ray() method.

ray() is chainable, so you can chain on any of Laravel's assertion methods.

// somewhere in your app
Route::get('api/my-endpoint', function () {
    return response()->json(['a' => 1]);
});

// somewhere in a test
/** test */
public function my_endpoint_works_correctly()
{
    $this
        ->get('api/my-endpoint')
        ->ray()
        ->assertSuccessful();
}

Displaying requests

To display all requests made in your Laravel app in Ray, you can call ray()->showRequests(). A typical place to put this would be in a service provider.

To enable this behaviour by default, you can set the send_requests_to_ray option in the config file to true.

Laravel

##Showing queries

##Counting queries

##Manually showing a query

##Showing duplicate queries

##Showing slow queries

##Showing events

##Showing jobs

##Showing cache events

##Showing http client requests

##Handling models

##Displaying mailables

##Showing which views are rendered

##Displaying markdown

##Displaying collections

##Usage with a Stringable

##Displaying environment variables

##Using Ray in Blade views

##Using Ray with test responses

##Displaying requests