Getting Started

1. Install with the right version pin. The version you choose depends entirely on your Laravel/Nova pair:

# Laravel 12 + the Nova line paired with v3.x
composer require "stepanenko3/nova-logs-tool:^3.0"

# Laravel 10/11 (or you haven't moved Nova yet)
composer require "stepanenko3/nova-logs-tool:^2.3"

Never use *. v3.0.0 is a major bump whose only listed change is Laravel 12 support — which almost always means older framework ranges were dropped from composer.json. Read the tag's composer.json before you bump.

2. Register the tool in app/Providers/NovaServiceProvider.php:

use Stepanenko3\NovaLogsTool\NovaLogsTool;

public function tools(): array
{
    return [
        // ...
        new NovaLogsTool(),
    ];
}

3. Publish, publish, and clear caches:

php artisan vendor:publish --provider="Stepanenko3\NovaLogsTool\ToolServiceProvider"
php artisan nova:publish        # Nova 3 only; Nova 4+ auto-discovers assets
php artisan optimize:clear

Open the published config before assuming defaults — it's where the file list, access control, and permission settings live, and those key names drive every pattern below.

4. Where to look first. Refresh Nova and open the tool from the sidebar. You land on a listing of files from storage/logs. Click a filename to view entries; the header and row actions cover refresh, download, and clear. If the list is empty, jump straight to the permissions gotcha below — that's almost always the cause.

5. Your first real use case. You're on a call with support about a production 500 and you don't have SSH. Open the newest laravel-YYYY-MM-DD.log, scroll to the tail for the stack trace, copy the exception class into your patch, download the raw file as the ticket snapshot, then clear the log so the next incident stands out on a clean file.

Implementation Patterns

Gate it before you register it. Log lines routinely contain SQL, session IDs, request payloads, and tokens. Decide the authorization boundary first, then register:

public function tools(): array
{
    return array_filter([
        Gate::allows('viewLogs') ? new NovaLogsTool() : null,
    ]);
}

Pair this with a Nova policy or gate defined in AuthServiceProvider — don't rely on the sidebar hiding the menu item, since direct URLs still resolve.

Environment-aware registration. Locally, a terminal (tail -f, less +F) is faster than any browser panel. Many teams do:

if (! app()->environment('local')) {
    $tools[] = new NovaLogsTool();
}

This also keeps a stray debug line from leaking through a shared staging panel.

One instance per non-default log directory. If a queue worker, a payment integration, or a custom channel writes to storage/logs/payments/, register a separate tool instance with a distinct label and icon rather than expecting one panel to cover every channel. The mental model is "one browser per directory," not "one browser for the app."

The incident loop. A repeatable workflow that matches the tool's read/download/delete surface — worth writing down in your runbook:

Reproduce the error.
Open the newest daily file and scan the tail for the exception class.
Copy the trace into the fix.
Download the raw file as the ticket snapshot.
Clear the log.
Verify the next request writes a clean file.

Ticket hand-off. Download-before-clear is the pattern worth institutionalizing: the raw file goes onto the Jira/Linear ticket, so a teammate (or a vendor) without Nova access can read the incident without you relaying greps over Slack.

Keep daily with a retirement window. With daily you get laravel-2025-03-09.log; with single you get one unbounded laravel.log. If you lean on this tool, set:

// config/logging.php
'daily' => [
    'driver' => 'daily',
    'path' => storage_path('logs/laravel.log'),
    'days' => env('LOG_DAILY_DAYS', 14),
],

An unbounded single file makes the listing unnavigable and the viewer slow. If you need longer retention, handle it with OS logrotate rather than growing the browsable set.

Pair with Nova dashboards, don't replace them. A small "recent errors" card that links into the tool is a good UX pairing. But this is a file browser, not an observability stack — don't expect it to surface trends, alerts, or cross-instance correlation.

Upgrade lane for 3.0.0. Treat it as a maintenance bump, not a feature adoption. Order of operations: upgrade Laravel + Nova first (Laravel 12 wants PHP 8.2+), bump the tool, then smoke-test list → view → download → delete on staging. Keep it out of unrelated feature branches — a broken tool after a framework upgrade is hard to attribute when it's tangled with product changes.

Gotchas and Tips

File permissions are the #1 cause of an empty list. The PHP-FPM/queue user (e.g. www-data) must be able to read storage/logs. The failure mode is an empty panel, not a clear error — check ls -la storage/logs and ownership before you go hunting in config.
Huge files will hang or OOM the request. Opening a multi-GB laravel.log can blow memory_limit or your gateway timeout. The fix is rotation, not tuning — download large files instead of rendering them in the browser.
Docker/Kubernetes mismatch. storage/logs inside the PHP container is not the host directory. Mount a volume, or point the tool at the container path. Otherwise you'll stare at stale files while the app logs somewhere else entirely.
Config cache bites after edits. Changed log paths or package config and nothing updated? php artisan config:clear && php artisan optimize:clear. On production deploys, remember Nova's own caches may need rebuilding too.
Confirm the Nova compatibility matrix. Check composer.json for Nova 4/5 support before installing. Nova 3 additionally needs nova:publish; Nova 4+ auto-discovers assets, so running it there is harmless but pointless.
Version constraints before upgrading. Confirm the Laravel + Nova pair on the tag; stay on ^2.3 if you haven't moved the framework. A v3 major is not a background composer update.
Symlinked or NFS log directories can be slow or partially readable — the listing lags or silently misses files. Prefer local disk paths.
Deletion/clear is permanent and unaudited. Convenient on staging, dangerous in production. Back up first (that's the download step in the incident loop), or wrap the tool if you need a record of who cleared what.
Don't rely on the tool for redaction. Handle APP_KEY, .env dumps, auth headers, and PII at the application level — config/logging.php, processors, and formatters — rather than trusting a browser to hide them.
Extension points are thin. v3.0.0 added no surface area. For regex search, tail-follow, redaction, or per-file actions, fork it (MIT) or write a sibling Nova tool over the same directory convention — don't wait on upstream.
Keep a fallback in your back pocket. One maintainer, zero dependents, 27 stars (a narrow funnel: Nova license + file logging). Keep the exit path in mind — laravel-log-viewer or a ~30-line custom Nova page. Treat it as a replaceable convenience, not infrastructure, and pin it accordingly.

Nova Logs Tool Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips