README

Send debug payloads from your PHP or Laravel project straight to the Lens desktop app. Instead of polluting your response with dd() or var_dump(), use lens(...) to send neatly rendered data to a separate window, with syntax highlighting, labels, colors and the line it came from.

lens('hello');
lens($user)->green()->label('Signed-in user');
lens(['order' => $order, 'total' => $amount]);

Requirements

• PHP 8.0 or higher (with ext-curl and ext-json)
• The Lens desktop app must be running, it receives and displays the payloads. (Separate application; listens on 127.0.0.1:23600 by default.)

Installation

Install as a dev dependency (it's a debugging tool, just like dd()):

composer require lensapp-eu/lens-php --dev

In Laravel the package is auto-discovered. Nothing else to configure.

Note: because this is a dev dependency, the lens() helper does not exist in production (composer install --no-dev). So don't leave lens() calls in code that ships to production - treat it like dd(). See Prevent commits with lens().

Connect to Lens Cloud (optional)

To send this project's errors straight to Lens Cloud, no desktop app required, copy your project's key from Lens Cloud and add one line to your .env:

LENS_PROJECT_KEY=your-project-key-from-lens-cloud

That is all you need: with a key set, events go to Lens Cloud at https://app.lensapp.eu by default. Set LENS_CLOUD_URL only to point at a self-hosted or local cloud (e.g. http://localhost:3000).

Channels

Lens sends to two channels, independently toggleable:

LENS_LOCAL=true   # the desktop app (live local debugging), default on
LENS_CLOUD=true   # Lens Cloud (needs a key), default on

So LENS_LOCAL=false gives you cloud only, and LENS_CLOUD=false gives you the desktop app only. Config is read from config('lens.*'), so it survives php artisan config:cache; run php artisan config:clear after changing your .env.

Usage

The global lens() helper is available everywhere:

// A single value
lens('checkpoint reached');

// Multiple values at once
lens($request->all(), $user, $total);

// Chaining: label and color
lens($order)->label('New order')->green();

// Clear the screen
\LensApp\Lens\Lens::clear();

Available color shortcuts: ->red(), ->green(), ->blue(), ->orange(), ->purple(), ->gray().

In Blade views you can use the @lens directive:

@lens($user)
@lens(['cart' => $cart], 'Checkout')

Exceptions

Exceptions show up as a red item with an expandable stack trace:

lens($exception);                          // a Throwable is detected automatically
\LensApp\Lens\Lens::exception($e);   // explicit

In Laravel, reported exceptions are sent to Lens automatically. Disable it with:

LENS_CATCH_EXCEPTIONS=false

Laravel streams

Stream Laravel internals straight to Lens. Toggle per environment in your .env:

LENS_QUERIES=true   # every DB query (SQL + bindings + time)
LENS_MAILS=true     # outgoing mails, with a rendered HTML preview
LENS_JOBS=true      # queue jobs (processing / processed / failed)
LENS_EVENTS=true    # application events (framework noise filtered out)
LENS_MODELS=true    # Eloquent created / updated / deleted / restored

Or enable them in code:

\LensApp\Lens\Lens::showQueries();
\LensApp\Lens\Lens::showMails();   // shows the email's HTML in a sandboxed preview
\LensApp\Lens\Lens::showJobs();
\LensApp\Lens\Lens::showEvents();
\LensApp\Lens\Lens::showModels();

Pause execution

Pause your code until you click Continue or Stop in the Lens app:

\LensApp\Lens\Lens::pause();

Returns immediately if Lens is disabled or the app is not running, so it never hangs your app.

Artisan commands

php artisan lens:test           # send a test payload to the Lens app
php artisan lens:check          # scan for leftover lens() calls
php artisan lens:check --staged # only staged files (for pre-commit)
php artisan lens:install-hooks  # install a git pre-commit hook

Prevent commits with lens()

lens:check scans for leftover lens() calls and returns exit code 1 when it finds any (useful in CI). A git pre-commit hook then automatically blocks any commit containing a lens() call.

Automatic (recommended)

The package installs the pre-commit hook by itself on composer install/update, but Composer requires your one-time consent for this. Add this to your project's composer.json:

"config": {
  "allow-plugins": {
    "lensapp-eu/lens-php": true
  }
}

The hook is only installed:

• in dev (never on composer install --no-dev / production / CI deploy);
• in a Laravel project (an artisan file must be present);
• when there is a .git directory and no pre-commit hook exists yet (an existing hook is never overwritten).

Manual

php artisan lens:install-hooks

If a pre-commit hook already exists, use --force or add this line yourself:

php artisan lens:check --staged || exit 1

Configuration

Laravel

Optionally publish the config file:

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

Or configure everything through your .env:

LENS_ENABLED=true
LENS_HOST=127.0.0.1
LENS_PORT=23600

Disable in production

Simply set:

LENS_ENABLED=false

All lens() calls then become no-ops, no network traffic, no overhead touching your app.

Without Laravel (plain PHP)

require __DIR__ . '/vendor/autoload.php';

use LensApp\Lens\Lens;

Lens::configure('127.0.0.1', 23600); // optional; these are the defaults
lens('works without a framework too');

How it works

lens() builds a JSON payload and makes a short HTTP POST to the Lens desktop app (http://LENS_HOST:LENS_PORT). If that fails (app not open, timeout) the error is silently ignored, debugging should never break your application.

License

MIT, see LICENSE.