thewonderjoy/gaze-laravel

See what your Laravel app is doing in the Gaze desktop app. You get your own gaze() calls plus queries, logs, exceptions, mails, jobs and more, grouped by the request, job, command or test they came from.

Gaze is a desktop debug window for PHP, Laravel and JavaScript apps, on Mac, Windows and Linux. This package builds on thewonderjoy/gaze-php.

Get the app: download Gaze from thewonderjoy.com/products/gaze.

Install

composer require thewonderjoy/gaze-laravel

It needs PHP 8.2+ and Laravel 12 or 13. Laravel finds the service provider by itself. Open the Gaze app, then check that your app can reach it:

php artisan gaze:doctor

If it can't, for example under Sail, Docker or WSL, or because Gaze runs on another port, the command prints the .env lines to add. To change settings, publish the config with php artisan vendor:publish --tag=gaze-config.

Normal or --dev?

Install it as a normal dependency, as above. --dev keeps the package off your servers, but then a call you forgot to remove breaks there:

Environments

Gaze is off when APP_ENV=production and on everywhere else, staging and testing included. Set GAZE_ENABLED=false on servers where you don't want it. To use it in production for a while, set GAZE_ENABLED=true.

Use

gaze('Hello', $user);                       // everything from gaze-php works
gaze()->model($order)->green();             // an Eloquent model with its relations
gaze()->mailable(new OrderShipped($order)); // a rendered mail
gaze()->showQueries();                      // show queries from here on
$total = gaze()->countQueries(fn () => $report->build());

collect($rows)->gaze('rows')->map(...);     // on collections, strings, query builders
User::where('active', true)->gaze()->get(); // the SQL with bindings, before it runs
$this->get('/orders')->gaze()->assertOk();  // on test responses

@gaze($order)
@gazeAll        {{-- every variable in this view --}}
@gazeMeasure    {{-- stopwatch --}}

Methods

gaze() has every method of gaze-php: values, colours, tables, pause(), measure(), count(), screens and the rest. This package adds the Laravel ones below.

Laravel values

Turn a watcher on for part of your code

Each watcher in the list below has three methods. With queries as the example:

Short forms: queries(), slowQueries(), events(), jobs(), views(), requests(), httpClientRequests().

To send only some queries, pass a condition: showConditionalQueries(fn (QueryExecuted $query) => ..., $callback = null, $name = 'default'). Stop it with stopShowingConditionalQueries($name).

On other objects

Each one returns the object you called it on, so you can keep chaining.

Blade

Traces

Everything that happens during one request ends up together in the app, closed by a summary with the status, time, memory, query count and any N+1 warnings. Queued jobs, artisan commands and tests work the same way, and a job shows which request dispatched it.

A request sent from the browser links back to the call that sent it, so its trace shows from browser POST /api/cart. Gaze reads the W3C traceparent header for this, which gaze-js adds to the page's fetch and XHR calls once its network capture is on. There's nothing to set up on the Laravel side. To turn it off, set traces.accept_traceparent to false in config/gaze.php.

To get one trace per test, add the trait to your base test case:

use TheWonderJoy\Gaze\Laravel\Testing\TracesTests;

abstract class TestCase extends BaseTestCase
{
    use TracesTests;
}

Watchers

You can switch each watcher in config/gaze.php, with an env variable, or for part of your code with gaze()->showX().

When the same query runs again and again (N+1), the app folds the runs into one row that lists each of them. A watcher that is off registers nothing, so it costs nothing.

The query switches add up: a query is sent when any of them matches it. queries sends every query, so while it's on, the switches below change nothing. GAZE_INSERT_QUERIES=false doesn't hide inserts. To see only some queries, turn queries off and switch on the ones you want:

For example, GAZE_QUERIES=false with GAZE_SLOW_QUERIES=true sends only slow queries. Request summaries still count every query while any query switch is on, but N+1 detection only sees the queries that are sent. With every query switch off, request summaries show no query count and exceptions don't list the last queries.

Secrets are masked

Before anything leaves your app, Gaze masks passwords, tokens, cookies, Authorization headers and .env secrets (*_KEY, *_SECRET, *_PASSWORD, *_TOKEN). This is on by default. See redact in the config.

Settings

config/gaze.php works with php artisan config:cache.

Artisan commands

• php artisan gaze:doctor shows where PHP runs (Windows, WSL2, Docker, Sail), whether Gaze is on and why, which hosts answer, and the exact .env lines to add.
• php artisan gaze:clean [--dry-run] removes gaze() and gaze_dd() calls from app, routes, config, resources, tests and database.

Ray compatibility

You can keep spatie/laravel-ray installed next to this package, because the Gaze app also accepts Ray's messages. To move over, replace ray( with gaze(. The method names are the same, apart from these:

The gaze-php README lists the Ray methods it doesn't have.

If you'd rather not rename your calls, remove laravel-ray and set GAZE_DEFINE_RAY_HELPER=true (define_ray_helper in the config). Your ray() calls then go to Gaze. A call to one of the missing methods throws an error.

RAY_HOST and RAY_PORT are read when GAZE_HOST and GAZE_PORT aren't set.

License

MIT