Download the PHP package lensapp-eu/lens-php without Composer

Lens (PHP client)

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.

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

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:

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:

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:

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

In Blade views you can use the @lens directive:

Exceptions

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

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

Laravel streams

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

Or enable them in code:

Pause execution

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

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

Artisan commands

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:

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

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

Configuration

Laravel

Optionally publish the config file:

Or configure everything through your .env:

Disable in production

Simply set:

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

Without Laravel (plain PHP)

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.