systemsx/lantern

Laravel-first custom events and metrics for Lantern.

v0.1.0 2026-08-20 18:57 UTC

Requires

• php: ^8.2
• illuminate/bus: ^11.0|^12.0|^13.0
• illuminate/console: ^11.0|^12.0|^13.0
• illuminate/contracts: ^11.0|^12.0|^13.0
• illuminate/http: ^11.0|^12.0|^13.0
• illuminate/queue: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0

Requires (Dev)

• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^3.8|^4.0|^5.0
• pestphp/pest-plugin-laravel: ^3.0|^4.0|^5.0

GPL-3.0-or-later

Published on Packagist.org on 2026-08-20 19:03 UTC

README

Send type-safe Custom Events and counter, gauge, and distribution points from Laravel to Lantern. Delivery uses your Laravel queue and Lantern's native HTTP API; Laravel Nightwatch is optional and is used only for best-effort trace correlation.

composer require systemsx/lantern

LANTERN_ENABLED=true
LANTERN_INGEST_URL=https://ingress.lantern.example
LANTERN_TOKEN=
LANTERN_QUEUE_CONNECTION=
LANTERN_QUEUE=lantern
LANTERN_TIMEOUT=10
LANTERN_CONNECT_TIMEOUT=3

Ensure a worker processes the dedicated queue:

php artisan queue:work --queue=lantern,default

use SystemsX\Lantern\Facades\Lantern;

Lantern::event('ai.completion', [
    'model' => 'gpt-5',
    'input_tokens' => 1250,
    'output_tokens' => 420,
]);

Lantern::counter('ai.cost_usd', 0.0142, ['model' => 'gpt-5']);
Lantern::gauge('users.active', 428);
Lantern::distribution('checkout.duration_ms', 182.4, ['region' => 'eu-west-2']);

Records are validated synchronously, buffered for the current request, command, or queued job, and then delivered in retried queue jobs of at most 500 records. Network and receiver failures do not fail the instrumented execution. Long-running custom workers should call Lantern::flush() at their own execution boundary.

For application tests:

$lantern = Lantern::fake();

Lantern::event('order.completed', ['order_id' => '123']);

$lantern->assertEventRecorded('order.completed');

Development

composer install
composer test

The package supports PHP 8.2+ and Laravel 11, 12, and 13.