Flogger Laravel Package

Getting Started

Flogger is a web-based log viewer for Laravel: it reads the files your logging stack writes under storage/logs and renders them in a browsable, filterable UI. It is an inspection tool, not a log aggregator — treat it as the thing you open when a support ticket says "the checkout endpoint 500'd at 14:32".

Minimum setup:

composer require xoshbin/flogger
php artisan vendor:publish --tag="flogger-config"

Then open config/flogger.php before you visit anything. The two settings that matter on day one are the route prefix and the middleware stack — out of the box the UI is registered behind web middleware only, which means it is publicly reachable the moment you deploy. Set the middleware to something authenticated (['web', 'auth']) or add an IP allowlist / gate before you ship it to any environment that isn't your laptop.

First use case, end to end: reproduce a failing request, open the viewer, filter by error level, narrow to the time window of the incident, and search for the exception class or a correlation ID you injected into the log context. That path — level filter plus free-text search plus time range — covers most of what you'll ever do with it.

Confirm your log channel first. Flogger reads files that exist, so if config/logging.php points at stderr (common in containerised setups) there will be nothing to browse. daily or single channels are what you want.

Implementation Patterns

Tier the exposure per environment. Enable the viewer locally and in staging, and either disable it or gate it hard in production. A common shape is an environment check in the config plus a Gate::define('viewFlogger', ...) in a service provider, with the gate name added to the middleware array. Ops staff get access; the public internet does not.

Log with structured context, not string concatenation. The viewer is only as searchable as your logs are. Log::error('Payment capture failed', ['order_id' => $id, 'gateway' => $gateway]) gives you a token you can paste into the search box; Log::error("Payment capture failed for $id") gives you a regex problem. This is the highest-leverage habit when adopting any viewer.

Route prefix as an operational lever. If your edge proxy blocks /admin/* or you already own /logs, change the prefix rather than fighting the proxy. Keeping the viewer on a non-obvious prefix is defence in depth, not security — pair it with real authorization.

Use it alongside, not instead of, aggregation. Flogger sees the files on the node that served the request. In a multi-node deployment behind a load balancer, you're looking at one machine's slice of history. Keep it for local and single-node staging triage, and keep your centralised logging for production forensics.

Throttle and scope reads. Log files get big. If you expose the viewer to a team, put a rate limit on the route group and keep rotation tight (daily with a modest days value) so the viewer is never asked to page through a 2 GB file. Rotated, bounded files are the difference between a snappy UI and a timeout.

Wire it into your incident checklist. "Check Flogger on staging" is a cheap first step before reaching for heavier tooling, especially for reproduce-and-fix loops where you're the one generating the errors.

Gotchas and Tips

v1.2.2 — UTF-8 sanitization (patch release). This resolves a viewer inconsistency caused by log content containing invalid UTF-8 byte sequences — truncated multibyte characters, binary payloads dumped into a log line, or data written by a non-PHP service in a different encoding. Symptom was previously garbled rendering or a blank/partial entry for the affected line. The fix sanitizes content before display. Two practical consequences: it's a drop-in composer update with no config or API changes, and you should not expect byte-exact fidelity when inspecting lines that contained malformed encoding — the viewer now shows you a readable, sanitized rendering rather than the raw bytes. If you were debugging encoding issues by eyeballing the viewer, drop to tail on the file itself.

Permissions bite silently. The PHP-FPM/queue user must be able to read storage/logs. If the viewer loads but shows no files, check ls -l before you check the package config — and remember newly rotated files inherit the umask of whichever process created them.

Config caching in deployed environments. Publish the config, then php artisan config:clear (or rebuild the cache). A stale cached config is the usual cause of "I changed the middleware and nothing happened".

No auth by default. Repeated because it's the mistake people actually make. The package gives you a route and a UI; the access control decision is yours.

Timezone mismatches. Timestamps are whatever your application wrote. If other services on the same host log in UTC while Laravel runs in a local timezone, the timeline in the viewer will look subtly wrong. Standardise on UTC in config/app.php and this class of confusion disappears everywhere, not just here.

Multi-server blind spot. Covered above, but it's the single most common source of "the log says nothing happened" — the request landed on a different node than the one you're viewing.

Extension points. Published config for routes, middleware, and file discovery; published views if you need to alter the UI. Prefer the gate/middleware approach for access control over forking the views — it survives package upgrades.