Logs Laravel Package

Getting Started

The package is an add-on to the Enso admin suite, not a standalone log viewer. Budget for laravel-enso/enso (or at minimum the core + UI packages) before you can make use of it.

1. Install

   composer require laravel-enso/logs
   

2. Confirm prerequisites — you need a working Enso app with the permission system and the Vue SPA shell already building. If php artisan route:list doesn't show Enso routes, fix that first.
3. Seed permissions — Enso menu items are permission-gated. Run the Enso permission seeder (or the package's seeder if it ships one) so logs.* permission entries appear in Roles > Permissions. Without this, the "Logs" sidebar entry stays hidden and you'll assume the package is broken.
4. Build the front end — Enso's Vue components are compiled through the host app's mix/vite pipeline. Re-run yarn install && yarn build (or npm run dev) after install so resources/js from the package is picked up.
5. Where to look first
   • config/logs.php (if published) — filesystem disk and default log path
   • src/Http/Controllers/LogController.php — index/show/download/destroy endpoints
   • src/Services/LogService.php — the file listing, tailing, and pagination logic
   • src/routes/api.php — the API surface mounted at /api/logs
6. First use case: open the Enso sidebar → Logs, pick laravel.log, and tail recent entries in the browser. Hand the "Download" button to an admin and you've removed the most common reason to ask for SSH access.

Implementation Patterns

• Treat it as a thin read/delete layer over storage/logs. The service lists files on a Laravel filesystem disk and slices by line ranges. Point it at a dedicated disk in config/filesystems.php if your logs live off the default local disk, then reference that disk in the package config.
• Pair it with daily channels. Configure config/logging.php channels as daily so Monolog rotates; the UI is for inspecting and clearing, not rotation. A workflow of "daily rotate + admin deletes stale files from the UI" is the intended shape.
• Extend via the service, not the controller. When you need custom log paths, a different filename convention, or a parsed/structured view, bind your own implementation:

  // AppServiceProvider::register()
  $this->app->bind(LogService::class, App\Logs\MyLogService::class);
  

  Keep the public method signatures (files(), show(), download(), destroy()) intact so the front-end and routes keep working.
• Gate by permission, not route middleware alone. Enso resolves menu visibility from permissions; enforce the same permission on the API controller (authorize/can:) so a hidden menu item isn't a free URL.
• Use it during incident triage. Typical day-to-day flow: alert fires → open Enso → Logs → filter the laravel.log view for the exception class → download the file for the ticket, then delete it after rotation. No SSH round trip, no SCP.
• Integrate with existing channel naming. If you log to storage/logs/support.log via a custom channel, the file shows up automatically — no code change — as long as it lands in the configured path.

Gotchas and Tips

• Not standalone. Attempting composer require laravel-enso/logs into a plain Laravel app pulls in Enso dependencies and a Vue stack you weren't planning to run. If you only want a log viewer outside Enso, reach for rap2hpoutre/laravel-log-viewer or opcodesio/log-viewer instead.
• Version pinning matters. At 11 stars and a sub-1.0 score, expect churn. Pin the version in composer.json and check the Enso major version it expects — a mismatch surfaces as silently missing routes or Vue components that fail to register.
• Writable logs directory. The web user (www-data, etc.) must be able to read and delete files under storage/logs. Fresh deploys often leave storage/ owned by the deploy user; the Logs screen will list nothing or throw 500s. storage/logs should be 775 with a shared group.
• Large-file behavior. Verify how show() reads files before exposing it on a noisy production app. A 500 MB laravel.log read line-by-line for tailing can time out or exhaust memory. If it does, set memory_limit and max_execution_time on those routes, or cap file size in a custom LogService.
• Delete is destructive. The UI's delete removes the file outright — there's no Trash. Restrict the logs.destroy permission to trusted roles and rely on daily rotation to bound exposure.
• Path handling. Before letting non-developers use it in production, spot-check that download/show reject filenames containing .. or /. Confirm against the actual LogService — this is the one place a thin viewer package can grow a traversal bug.
• Debugging checklist when the panel is empty:

  php artisan route:list | grep -i logs   # routes registered?
  ls -la storage/logs                    # files actually present?
  php artisan db:seed --class=...        # permissions seeded?
  tail -f storage/logs/laravel.log       # did the API call itself 500?
  

  Nine times out of ten it's permissions not seeded or a stale front-end build, not the package code.
• Extension points. The service binding is the primary one; beyond that, use Enso's route/middleware config if you need to rename the /api/logs prefix to avoid conflicting with a host-app route.