Laravel Client Laravel Package

Getting Started

Install and publish

composer require loglia/laravel-client
php artisan vendor:publish --provider="Loglia\LaravelClient\LogliaServiceProvider"

Then read the published file — config/loglia.php — before you read anything else. The README describes capabilities (exceptions, log entries, structured context, batched delivery) but not the actual key names, and this package's changelog is one line long. The config file is the only accurate specification you have.

Minimum viable env block

LOGLIA_ENABLED=true
LOGLIA_KEY=your-project-key
LOGLIA_ENVIRONMENT=production

Treat the exact variable names as likely rather than certain — confirm them against config/loglia.php and the env() calls in the source before you commit them to your deployment manifests. Same for the API host if the package ships a self-hosted option.

Verify the wiring before writing any code

The service provider should be picked up by package discovery; if you're on an older app with dont-discover, register it manually in config/app.php. Then prove the pipe end-to-end in a staging environment with the smallest possible test:

php artisan tinker
>>> logger()->error('loglia smoke test', ['probe' => true]);

Look for the event in the Loglia dashboard within your batch interval. If it doesn't appear, stop and debug delivery (see Gotchas) — do not start layering context middleware on top of a transport that isn't confirmed working. A logging client that silently drops everything looks exactly like a healthy app.

First real use case

Don't wire it into your global log stack on day one. Start by pointing it at unhandled exceptions only in a single non-production environment, run for a week, and look at what arrives. That tells you three things at once: whether the transport is reliable, what your actual error volume is (which drives cost), and how noisy your log payloads are (which drives PII scrubbing). Only then widen it to Log:: calls and custom events.

Implementation Patterns

Pattern 1 — dedicated log channel, not the global stack

The most maintainable integration is a named channel you opt into:

// config/logging.php
'loglia' => [
    'driver'  => 'loglia',
    'level'   => env('LOG_LEVEL', 'error'),
],

Log::channel('loglia')->error('Payment gateway timeout', [
    'gateway' => 'stripe',
    'order_id' => $order->id,
]);

This keeps Loglia out of your local stack (see the stack/single channels) and lets you change the level per environment without touching application code. If the package ships a loglia driver this is one line; if it only exposes a facade, keep the facade behind a thin wrapper of your own so you can swap vendors later.

Pattern 2 — exception handling, carefully

Wire it into App\Exceptions\Handler::report() and let parent::report() do its normal thing:

public function report(Throwable $e)
{
    if ($this->shouldReport($e) && config('loglia.enabled')) {
        app(\Loglia\LaravelClient\Client::class)->captureException($e);
    }
    parent::report($e);
}

Two rules: (a) never let the Loglia call throw — wrap it if the package doesn't already, because a failing logger inside report() will mask the original exception; (b) don't capture ValidationException, AuthenticationException, or 404s. Use $this->shouldReport($e) and add a dontReport list, or the dashboard fills with noise and you'll disable the package out of frustration.

Pattern 3 — context enrichment once, via middleware

Rather than passing user/tenant data to every call, register a middleware that pushes context onto the client for the lifetime of the request:

public function handle($request, Closure $next)
{
    app(\Loglia\LaravelClient\Client::class)->addContext([
        'user_id'    => optional($request->user())->id,
        'tenant_id'  => optional($request->user())->tenant_id,
        'request_id' => $request->header('X-Request-Id'),
        'route'      => $request->route()?->getName(),
    ]);

    return $next($request);
}

Generate the request ID in the middleware if the header is absent, so you can correlate Loglia events with your access logs and any other APM. Use optional()/null-safe access — this middleware runs on unauthenticated requests too, including ones that go on to throw.

Pattern 4 — meaningful events, not just errors

The value of a centralized log platform is the events you can't get from a stack trace. Explicit captures for business-significant transitions are cheap and high-signal:

$this->loglia->capture('order.failed', [
    'order_id' => $order->id,
    'reason'   => $failure->reason(),
    'attempt'  => $attempt,
]);

Keep the payload flat and scalar where possible. Deeply nested Eloquent models serialize badly, leak columns you didn't intend to send, and inflate cost.

Pattern 5 — environment segmentation

Give each environment its own project/API key. Sharing one key across staging and production makes the dashboard unusable and means a staging exception storm can bury a real production incident. Also set the environment field explicitly — don't rely on APP_ENV being read correctly through config caching.

Pattern 6 — disable in tests and CI

Set LOGLIA_ENABLED=false in phpunit.xml. You do not want outbound HTTP in unit tests: it makes the suite slow, flaky, and dependent on network egress from CI runners. If the package offers a fake/assertSent-style testing helper, use it for one or two integration tests of your integration (the middleware, the handler) — not for every test.

Pattern 7 — batched delivery, flush before you die

Batched async delivery is the right default, but it means in-memory events evaporate on a hard crash. If you have a custom shutdown path — a queue worker's terminating handler, a long-running Artisan command, an Octane worker — explicitly flush where the package exposes it. For a queue worker that gets SIGTERM'd on deploy, this is the difference between seeing the last error and seeing nothing.

Gotchas and Tips

The support window is the headline risk, not the API. v3.1.0's only stated change is Laravel 8 support, and that release landed in October 2020. Laravel 8 went end-of-life in January 2023. Before you install, run:

composer require loglia/laravel-client --dry-run

and read the resolved illuminate/* constraint in composer.lock. If the package caps at ^8.0, installing it on L9/L10/L11 will either fail resolution or install and fail at runtime. If it's a broad >=8.0 range, that range is untested past L8 — a widened constraint is a claim, not evidence. Pin an exact version during evaluation; don't accept a caret range you haven't validated.

"Support for L8" is ambiguous. It may mean "L8 only" or "L8 through current." Diff the composer.json between the previous tag and v3.1.0 to find out. This is the single most important five minutes you'll spend on the package.

Nothing arrives — debug in this order. (1) Is the provider registered? php artisan about or php artisan config:show loglia. (2) Did you config:cache before setting the env var? Cached config ignores new .env values — php artisan config:clear and retry. (3) Are outbound requests allowed from that host? Batched senders often fail silently; check application logs for a swallowed exception and test egress with curl to the API host. (4) Has the batch interval elapsed? Wait and re-check before assuming breakage.

Async delivery hides its own failures. A logger that can't reach its endpoint is not supposed to take down your app — which is correct, but it also means failures are invisible. Run with the package's debug/verbose mode (check the config for the flag) for the first day in each new environment, and watch your dashboard's "last event received" timestamp as a health signal.

Guard against recursion. A log channel that reports its own transport errors through the Log facade will loop. Confirm the package's transport writes via a raw client, not via Log::. If it doesn't, isolate it — put the Loglia channel in its own stack, never in the default stack.

Scrub before send, not after. Structured context is exactly where PII accumulates: authorisation headers, cookies, email addresses, request bodies, query strings. Most clients of this shape capture request context automatically. Check what's included and whether the config exposes an except/scrub list. If it doesn't, add a context filter in your middleware rather than trusting the default. This is a GDPR problem the first day it happens, not a nice-to-have.

Control volume with level, not with discipline. Engineers will always log too much; set the channel level (or the package's minimum level) to error in production and debug only when actively investigating. Watch your event quota in the first month — batched delivery makes cost feel abstract until the invoice.

Don't let it become your only audit trail. A 5-star, single-maintainer package whose most recent release is a framework-compat bump should be additive observability, not the system of record for anything compliance-relevant. Keep durable business events in your own database.

Extension points worth knowing. If the package binds its client in the container (it should, given the facade), you can decorate it: bind a subclass or decorator in a ServiceProvider that adds redaction, sampling, or a synchronous fallback for APP_DEBUG=true. That's cheaper than forking and survives composer update better than editing vendor/. Also check whether the config accepts a custom context callback — if so, prefer it to middleware, since it covers queue jobs and console commands too, not just HTTP.

Register a recurring check. Add a quarterly calendar item to diff the upstream constraint range against your Laravel version. This class of package fails quietly — the release you need simply never appears — and the cost lands as an unplanned migration during an upgrade you already scheduled. Assign a named owner when you adopt; "the team" will not do this check.