fiachehr / laravel-logger
Privacy-first structured JSON logging and an authorized, bounded log explorer for Laravel.
Requires
- php: ~8.3.0 || ~8.4.0 || ~8.5.0
- ext-json: *
- ext-mbstring: *
- illuminate/auth: ^12.0 || ^13.0
- illuminate/console: ^12.0 || ^13.0
- illuminate/encryption: ^12.0 || ^13.0
- illuminate/http: ^12.0 || ^13.0
- illuminate/log: ^12.0 || ^13.0
- illuminate/routing: ^12.0 || ^13.0
- illuminate/session: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
- illuminate/validation: ^12.0 || ^13.0
- illuminate/view: ^12.0 || ^13.0
- monolog/monolog: ^3.0
Requires (Dev)
- laravel/pint: ^1.27
- orchestra/testbench: ^10.0 || ^11.0
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^11.5 || ^12.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Structured JSON logs and a built-in Blade log explorer, with its own username and password. Inspect exceptions, follow request IDs, and search recent events without adding a log database or building frontend assets in your application.
Where is the panel? Open <your application URL>/log-explorer after setup.
For example: http://127.0.0.1:8000/log-explorer. You will be taken to the
package's own sign-in page. Configure the dashboard login.
Contents
- Features
- Requirements
- Installation and first login
- Using the log explorer
- Logging and exceptions
- Request and queue correlation
- Using your application's login instead
- Safe diagnostic helpers
- Configuration and privacy
- Troubleshooting
- Schema and extensions
- Development and tests
- Upgrading from 0.1
- Contributing
- Security
- License
- Author
- FAQ
Features
- Built-in interface: Blade pages, bundled CSS/JavaScript, responsive table, saved display preferences, light/dark/system themes, keyboard navigation and accessible detail tabs. No CDN, mandatory asset publishing, separate frontend application, or host Node build.
- Independent login: one separately configured operator account, hashed password, CSRF protection, sign-out, session rotation, idle/absolute expiry, credential rotation invalidation, and limits on sign-in attempts. No user table or migrations.
- Optional host authentication: use an existing Laravel guard and explicit Gate instead of the separate credentials when that suits your application.
- Laravel-native logging: opt-in Monolog 3 channel for existing
Log::*calls, exception origin/line, bounded traces and request/queue correlation. - Focused exploration: literal search, severity/service/event/time/request/route/ exception/status filters, snapshot pagination, JSON/raw views and copy controls.
- Bounded local storage: private daily JSONL files, retention, locked writes, daily size quota and limited search windows. No external log service is required.
- Privacy defaults: metadata allowlists, categorical messages, secret filtering, bounded diagnostics, no automatic request bodies or arbitrary object serialization.
Logging and the dashboard are disabled on installation. Enable them explicitly. The explorer does not modify logs. Its POST endpoints sign the operator in and out and submit a search. No external telemetry is sent.
Requirements
| Component | Supported range |
|---|---|
| PHP | 8.3, 8.4 or 8.5, with JSON and mbstring |
| Laravel | 12.x or 13.x |
| Monolog | 3.x |
| Local filesystem | Linux or macOS; private writable storage |
| Dashboard sessions | Laravel web session middleware and a valid APP_KEY |
PHPUnit checks HTTP and package behavior; it does not execute browser interactions or real Octane workers. The dashboard uses Laravel's existing session and cache infrastructure: file-based sessions/cache can be used when no database or Redis is desired. Review a session driver change for the whole host app rather than changing it just for this package.
Installation and first login
1. Install the package
composer require fiachehr/laravel-logger:^0.3 php artisan log-explorer:install
Laravel auto-discovers the provider. The installer asks before publishing a missing
config/log-explorer.php, preserves an existing file, and prints the remaining
opt-in steps. It does not edit .env, logging channels, users or authorization.
For noninteractive configuration publishing:
php artisan vendor:publish --tag=log-explorer-config
If a new tag has not reached Packagist yet, use the GitHub repository directly:
composer config repositories.laravel-logger vcs https://github.com/fiachehr/laravel-logger composer require fiachehr/laravel-logger:^0.3
Run Composer and Artisan in the application's actual runtime. With Docker, run them inside the PHP service; a PHP-FPM service port is not an HTTP dashboard port.
2. Connect Laravel logging
Add this entry inside channels in config/logging.php:
'observability' => [ 'driver' => 'custom', 'via' => \Fiachehr\LaravelLogger\Logging\CreateLogger::class, 'level' => env('LOG_EXPLORER_LEVEL', 'debug'), ],
For application-wide structured logging, set:
LOG_EXPLORER_ENABLED=true LOG_EXPLORER_SERVICE=application LOG_CHANNEL=observability
To keep existing outputs, include observability once in your existing stack
and keep LOG_CHANNEL=stack. For example, a stack's channels may be
['single', 'observability']. Each destination still has its own privacy behavior;
this package does not sanitize a copy written to single, daily, or another logger.
While LOG_EXPLORER_ENABLED is false, this custom channel discards the records
routed to it. It does not forward them to single, stderr, or any other
channel. Leave it out of LOG_CHANNEL and out of stacks until you enable the
package. Channels that do not use CreateLogger are left unchanged.
3. Configure the built-in login
Generate a password hash with a hidden terminal prompt:
php artisan log-explorer:password
Enter and confirm a strong password of 12–72 bytes. The command prints a line such
as LOG_EXPLORER_PASSWORD_HASH='...'; copy the entire generated line, including
its single quotes, into your private .env. The actual password is not printed,
passed as a command argument, or written into a file by the command.
Then configure:
LOG_EXPLORER_DASHBOARD_ENABLED=true LOG_EXPLORER_AUTH_MODE=credentials LOG_EXPLORER_USERNAME=log-operator # Paste the LOG_EXPLORER_PASSWORD_HASH='...' line generated by the command here.
credentials is the default for fresh 0.2 configurations. There is no default
password, registration page, password reset endpoint or application-user lookup.
Both username and a supported password hash are required; missing/invalid
credentials fail closed with HTTP 503. Never store a plaintext password in this setting.
Keep dashboard.middleware as ['web'] for this mode. An extra host auth or
admin middleware would also require the application's login. This includes custom auth checks added to the host's web group. Choose
a suitable session middleware group for the explorer if your app customizes it.
No host Gate is needed for independent credentials mode.
Apply configuration changes in your application runtime:
php artisan config:clear php artisan route:clear
Rebuild deployment caches and restart long-running workers as part of your normal production release process. Use HTTPS and secure session cookies for remote access.
4. Open the panel
Start your application's normal web server, then visit its URL with /log-explorer:
| Your running application | Dashboard |
|---|---|
http://127.0.0.1:8000 |
http://127.0.0.1:8000/log-explorer |
http://my-app.test |
http://my-app.test/log-explorer |
https://example.com |
https://example.com/log-explorer |
The panel redirects to /log-explorer/login. Enter the separate username and
original password you configured, not the hash. You do not need to sign in to
your application's regular user panel first. Select Sign out in the explorer
to end its session; the host application's login and other session data are kept.
The two logins share Laravel's session infrastructure, with separate authentication state.
For an optional, dedicated local development port:
php artisan log-explorer:serve --port=8765
Open http://127.0.0.1:8765/log-explorer and sign in there. The command requires
APP_ENV=local or development, binds 127.0.0.1, and serves the whole host app
in the foreground. It does not start automatically. Production uses an
operator-managed Laravel web server/reverse proxy with HTTPS, secure session
cookies and correctly configured trusted proxies. Restrict any dedicated listener
with a firewall or VPN; a separate port does not replace dashboard authentication.
To change the path, set LOG_EXPLORER_PATH=internal/logs, clear/rebuild route and
config caches, and open /internal/logs. Login/logout/assets move with that prefix.
5. Write your first event
Use a normal application code path:
use Illuminate\Support\Facades\Log; Log::info('Application ready', ['event' => 'application.ready', 'count' => 1]);
For a quick terminal check if your application includes Laravel Tinker:
php artisan tinker --execute="Log::channel('observability')->info('Explorer ready', ['event' => 'application.ready']);"
php artisan log-explorer:doctor
Refresh the explorer. Daily files are created on the first write at
storage/logs/log-explorer/events-YYYY-MM-DD.jsonl. The explorer reads this package's
structured files; it does not import old laravel.log files. doctor checks
configuration, credentials or Gate, storage and assets without printing secrets;
it does not replace a real browser login test.
Using the log explorer
- Search by a literal term, select a severity/order, or open More filters for service, event, request ID, exception class, route name, HTTP status and UTC dates. The page sends those filters in the request body and does not put them in the address bar. A bookmarked query is applied once, then removed from the URL.
- Select an event to open Overview, Exception, Context, JSON or Raw. Raw means the stored sanitized JSON line, never pre-sanitization input.
- Use Show this request or a table request ID to group events with that ID. This is correlation within the configured source, not distributed tracing.
- Open Settings to choose a light/dark/system theme, accent color, severity badges/row tint/monochrome, comfortable/compact rows, contained/full panel width, side/centered event details and two-line/full messages. Changes apply immediately. Preferences and UTC/local time are saved per panel path in this browser; no log content or credentials are stored. Reset defaults restores the initial display. If browser storage is blocked, preferences still apply for the current visit.
- Copy sanitized JSON or enable auto refresh. Polling pauses while settings or event details are open or the tab is hidden.
- Next window continues a bounded search. A window may have no matches even when older files contain matches. There is no unbounded archive total.
Newest/oldest sorting follows file append order. Refresh starts a new snapshot; cursors expire after 15 minutes. The independent login expires after 30 idle minutes or eight hours total by default. Changing its username/password hash invalidates existing dashboard sessions on their next request.
Logging and exceptions
Existing Log::debug/info/warning/error/critical calls work once routed to the
channel. Use fixed developer-controlled identifiers so events remain useful with
privacy defaults:
Log::warning('Checkout retry', ['event' => 'checkout.retry', 'count' => 2]); Log::error('Checkout failed', ['event' => 'checkout.failed', 'exception' => $exception]);
Laravel-reported exceptions reach the configured default channel automatically;
no second exception reporter is installed. For a caught exception, use
report($exception) or one explicit log call containing the Throwable under
exception. A message-only call such as Log::error($exception->getMessage())
cannot retain its exception origin/trace. Avoid logging and reporting the same
failure twice. Laravel's own ignored-exception policy remains in effect.
Messages default to Application log event. The event identifier, exception type,
origin and trace carry the diagnostic information. Do not put user input or secrets
in identifiers. Direct Monolog instances, other channels and external transports
are covered only when explicitly routed here.
Request and queue correlation
For Laravel's bootstrap/app.php configuration, add the following inside your
existing withMiddleware callback, importing the package middleware:
use Fiachehr\LaravelLogger\Http\CorrelateRequest; $middleware->web(prepend: [CorrelateRequest::class]); $middleware->api(prepend: [CorrelateRequest::class]);
For apps retaining app/Http/Kernel.php, prepend the same class to the web/api
route middleware groups. Register it once per group, after the router has matched
a route; global pre-routing middleware cannot reliably capture route metadata.
Captured HTTP metadata includes method, route name/template and a generated ID, not actual route values, query strings, IPs, headers or bodies. Incoming IDs are ignored unless explicitly trusted behind an edge that strips/replaces client IDs. Queue class/attempt metadata and scoped cleanup use Laravel worker lifecycle events; job payloads are not logged. Octane lifecycle tests simulate events in-process; verify your actual Swoole/RoadRunner integration in the host application.
Using your application's login instead
Set LOG_EXPLORER_AUTH_MODE=host in a configuration that includes the new auth
block. Define the Gate in your application's provider, adapting the model/policy:
use App\Models\User; use Illuminate\Support\Facades\Gate; // Inside the provider's boot() method: Gate::define('viewLogExplorer', fn (User $user): bool => (bool) $user->is_log_operator);
is_log_operator is an example host-owned boolean, not a field created by this
package. Replace it with your actual permission policy. Select dashboard.guard
if needed and retain the host's appropriate middleware. An existing Gate::before
can grant abilities; add a direct role/admin middleware too if your policy requires
an exact role independently of those grants.
Sign in through the application's normal login page on the same origin, then open
/log-explorer. In host mode, anonymous access returns 401, a missing/denied Gate
returns 403, and the independent login routes are unavailable. Both modes protect
the explorer, JSON API and dashboard assets; only the credentials login page and
its static stylesheet are accessible before independent sign-in.
Safe diagnostic helpers
Enable diagnostics.enabled explicitly in config/log-explorer.php before use:
use function Fiachehr\LaravelLogger\log_dump; log_dump($value, 'checkout.state'); // records a bounded type/count summary and continues
Approved array fields can be included in safe payload mode. Arbitrary objects,
models and request graphs are never dumped. The namespaced log_dd helper is
rejected with LogicException unless logging, diagnostics and allow_stop are
explicitly enabled in local/development; it then logs and throws an HTTP 500
exception to unwind execution. Native dump()/dd() are unchanged. See the
security policy before enabling diagnostics.
Configuration and privacy
The publishable configuration file contains all options.
| Setting | Default |
|---|---|
| Logging / dashboard / diagnostics | Disabled |
| Authentication | Independent credentials; no default password |
| Payload / message mode | metadata / categorical |
| Context depth / items / string | 5 levels / 30 items / 1,000 bytes |
| Exception frames / previous depth | 15 / 2 |
| Event / daily file cap | 16 KiB / 64 MiB |
| Retention / searchable files | 14 days / up to 14 daily files |
| Per-request search budget | 8 MiB / 250 ms / 50 results |
| Dashboard requests | 60/minute per authorized identity |
| Login attempts | 5/IP and 20/account per 60 seconds |
| Independent session | 30 idle minutes / 8 hours maximum |
none drops user context; metadata allows operational fields; safe adds
explicitly approved fields. Sensitive-key protection applies in every mode.
Free-text message_mode=redacted is an opt-in defense in depth: regex cannot
reliably remove arbitrary secrets or personal data. Prefer categorical production
messages and review every approved field.
Keep storage canonical, private and outside the web root. New directories and
files use 0700/0600. An existing directory is changed to 0700 when this process
can do so; if group or other permission bits remain, storage is refused.
Symlinks and hardlinks are rejected. A daily file at its quota rejects new
writes. Repeated storage failures emit one fixed stderr warning per process per
minute, with a count of the warnings that were skipped. The warning never
includes the log record. Retention also runs on writes, at most once per process
per day. Schedule php artisan log-explorer:prune daily when the application
may go a day without writes. The command deletes only expired
events-YYYY-MM-DD.jsonl files in the configured directory. This package does
not register a scheduler. Login and API rate limits use the host cache;
use a persistent shared cache across workers. Review trusted proxies, HTTPS,
Secure/HttpOnly/SameSite cookies and private configuration-cache permissions.
The independent login also stores revocation tokens in that cache. Use a persistent
driver such as file for one server or an appropriate shared driver for multiple
servers; array/null do not preserve logins across requests. Clearing this cache
signs dashboard operators out. Logout revokes the token so replaying an old session
does not restore access, even when concurrent requests still hold old session data.
Troubleshooting
| Symptom | What to check |
|---|---|
| Cannot connect | Start the host web server; confirm hostname and published HTTP port. Installing a package does not start a server. |
| 404 | Both enable flags, custom prefix and cached routes/config. |
| 503 on login | Username, supported password hash, authentication mode, web session middleware and config cache. |
| Invalid credentials | Use the original password, not its hash; verify the username and quoted environment hash. |
| 419 | Reload the login page for a fresh CSRF token; check session storage, cookies and origin. |
| 401 on API/assets | Sign in again; independent sessions can expire or be invalidated by credential rotation. |
| 403 in host mode | Guard login, the configured Gate, and any role/admin middleware. |
| 429 | Pause polling/sign-in attempts, wait for Retry-After, and check the shared cache configuration. |
| Empty table | Generate a new event through the structured channel; check level, filters, daily quota and storage permissions with doctor. |
| Generic message text | This is the default categorical privacy policy; use fixed event codes and attach the Throwable. |
Schema and extensions
The default source writes one UTF-8 JSON object per line with schema_version: "1.0",
UTC timestamp, level, categorical event/message, approved application/service/
environment identifiers, optional request_id, filtered context, and optional
bounded exception/diagnostic summaries. Traces exclude arguments. External paths
become basenames. Minimal encoding-failure records can lack required reader fields
and are skipped. Monolog extra processors are not automatically serialized.
To supply another source, bind Fiachehr\LaravelLogger\Storage\LogSource and implement
search(array $filters, ?string $cursor = null, int $limit = 50): array. Return
data entries shaped as {entry: object, raw: sanitized JSON string}, an opaque
next_cursor or null, and meta containing scanned_bytes, malformed_entries,
rotated_files, bounded and order. Preserve privacy, cursor validation and
resource bounds. The built-in source is shared; tenant isolation requires a host
implementation that enforces its own tenant policy.
Development and tests
Development and automated checks use PHP and Composer only:
composer install
composer test
composer check
composer audit
composer test runs the PHPUnit unit and Laravel feature tests through Orchestra
Testbench. Coverage includes logging/privacy, bounded storage and readers,
exception context, dashboard routes, independent login, CSRF, session revocation,
rate limits and password hashing. composer check also runs Laravel Pint and
PHPStan. Run these checks in the PHP/Laravel environments your application uses;
this repository does not configure GitHub Actions.
The Blade dashboard ships with ready-to-use CSS and vanilla JavaScript; no build step or additional development runtime is required. Check actual browser behavior and host worker/server integration separately. Local PHP checks do not establish production concurrency or cold-disk performance.
Upgrading from 0.1
Version 0.2 adds independent credentials and defaults fresh configurations to
that mode. Existing published 0.1 configurations without dashboard.auth retain
their host-login behavior. To choose a mode explicitly, merge the new auth block
from the package configuration into your published file; do not blindly overwrite
host settings. Set mode through LOG_EXPLORER_AUTH_MODE, configure credentials
or the host Gate, rebuild caches, and restart workers. The JSON schema remains 1.0.
For later upgrades, review CHANGELOG.md, back up published host
configuration, run composer update fiachehr/laravel-logger, compare new defaults,
rebuild configuration/routes and restart long-running workers. Verify doctor,
a synthetic log write and authorized/unauthorized access. Roll back by restoring
the previous Composer constraint/lockfile, running composer install and rebuilding
caches/workers. Uninstall by removing the channel from logging stacks, correlation
middleware and diagnostic calls before composer remove fiachehr/laravel-logger.
Remove unused published config/Gates and rebuild caches. Existing logs are preserved.
Contributing
Describe the concrete behavior in an issue, use synthetic data, include meaningful
regression coverage, and update this README and CHANGELOG. Run
composer validate --strict, composer check and composer audit. Keep privacy
controls enabled and avoid new dependencies without a concrete need. Participate
respectfully and report private concerns through the maintainer's contact channel.
Security
Report vulnerabilities privately as described in SECURITY.md. Do not post production logs, credentials or exploit details in public issues. Review the threat model and production guidance in that policy before deployment.
License
This package is open-source software licensed under the MIT license. See LICENSE for details.
Author
Fiachehr
- GitHub: @fiachehr
- Email: mailbox@fiachehr.ir
Acknowledgments
- The Laravel and Monolog communities
- Open-source maintainers and security researchers
- Everyone contributing feedback, fixes and documentation
Useful Links
FAQ
Does the dashboard need Vue, a separate frontend or a build step?
No. Blade pages and their CSS/JavaScript ship inside the Composer package. The host application does not need to install Node dependencies or publish assets.
Can I use a different username and password from my application's users?
Yes. The default fresh configuration uses credentials mode with its own account.
It needs no application user, role or Gate. The optional host mode uses your
existing guard/Gate instead; the two modes are explicit alternatives.
Can I open it on port 8765?
For local development, run php artisan log-explorer:serve --port=8765 and visit
http://127.0.0.1:8765/log-explorer. In production, configure the listener in your
web server/reverse proxy. A port alone never grants dashboard access.
Will it display every old log or intercept native dump calls?
It displays its configured structured source. Existing text logs, unrelated logger
transports and native dump()/dd() calls are not automatically converted.
If you find this package useful, give it a ⭐️!
Made by Fiachehr with ❤️ for Laravel