Tomato Logs Module Laravel Package

Getting Started

This is the initial v1.0.0 tag of tomatophp/tomato-logs-module, a module in the TomatoPHP admin ecosystem (Filament-based panels). The release notes are only a changelog link, so treat the README and src/ as the source of truth on first install.

Minimal path to a working screen:

1. Install into an app that already has the Tomato admin/panel installed — this module is a panel add-on, not a standalone package:

   composer require tomatophp/tomato-logs-module
   

2. Check constraints first. Open vendor/tomatophp/tomato-logs-module/composer.json and confirm the filament/filament, laravel/framework, and tomatophp/tomato-admin (or equivalent core) version ranges match what you already run. Filament v2 vs v3 mismatches are the most common install failure in this ecosystem.
3. Discover the publishable assets. Don't guess tags — list them:

   php artisan vendor:publish
   

   then publish the config and migrations under the tomato-logs tag(s) shown.
4. Migrate and clear caches:

   php artisan migrate
   php artisan optimize:clear
   

5. Register the panel plugin if the package ships one (look for a *Plugin.php class implementing Filament's Plugin contract in src/). Add it to your panel provider's ->plugin(...) chain, or to the Tomato module registry, depending on which pattern the README documents.

Where to look first: README.md → src/ (service provider + any Filament Resources/) → config/ → database/migrations/. The migration tells you what is actually being stored (log rows vs. file references vs. activity entries), which determines every downstream decision.

First real use case: give support/ops staff a read-only "Logs" screen in the admin panel so they can filter recent errors by level and date instead of SSHing in to tail -f storage/logs/laravel.log. Wire it up, confirm entries appear by triggering a known exception or failed job, then decide on retention before it accumulates data.

Implementation Patterns

Verify what "logs" means here before building on it. Tomato modules vary: some wrap spatie/laravel-activitylog (audit trail of model changes), some read Monolog/storage/logs files, some add a DB-backed Monolog handler. Read the migration and the service provider — if there's a ->pushHandler(...) or a custom channel, the module is capturing writes; if it only reads a path from config, it's a viewer over existing files. Your integration strategy differs a lot between those two.

If it's a DB-backed handler:

• Add the module's channel to config/logging.php as a stack member so you keep the file channel as a fallback:

  'stack' => [
      'driver' => 'stack',
      'channels' => ['single', 'tomato-logs'],
  ],
  

• Schedule pruning immediately, not later. A DB log table grows fast on a busy app; a daily model:prune on the module's model (if it uses MassPrunable) or a small scheduled delete keeps the table honest. Check config/tomato-logs.php for a retention key before writing your own.

If it's a file viewer:

• Point the config at an absolute path resolved at runtime (storage_path('logs/laravel.log')), not a hardcoded relative path — path resolution differs between php artisan serve, queue workers, and Octane.
• Ensure rotated files (laravel-2024-01-01.log) are within the configured directory, and confirm the reader handles them, or your history disappears at the daily rotate.

Panel integration:

• Gate the resource. In Filament terms, publish/override the policy or add a canViewAny check keyed to a permission (Tomato typically pairs with spatie/laravel-permission + Shield). Logs contain stack traces, queries, and sometimes credentials in payloads — this should not be visible to every panel user.
• For multi-tenant panels, register the plugin only on the panels that need it, and check whether the resource applies a tenant scope. A global log table shown inside a tenant panel can leak other tenants' data.

Day-to-day workflow tips:

• Use the module as the first stop in incident triage, then drop to storage/logs for full context — panel viewers usually truncate long messages.
• If the module exposes filters (level, date, channel), bookmark a filtered URL per environment; it makes "is this error new or recurring?" a two-second check.
• Keep a LOG_LEVEL per environment so local/staging capture debug into the panel while production stays at error, otherwise the table becomes noise.

Gotchas and Tips

• v1.0.0 is a first tag. There is no track record, no deprecation history, and the public API (config keys, resource class names, table schema) may shift in 1.0.x or 1.1. Pin with "tomatophp/tomato-logs-module": "1.0.*" in composer.json and read the diff before bumping.
• The changelog link is empty of substance. Before upgrading in future, diff config/ and database/migrations/ between tags manually — that's where breakage hides in this ecosystem.
• Cache after install. If routes or the panel menu don't show the new screen: php artisan optimize:clear, then php artisan filament:optimize-clear if you've run filament:optimize. Auto-discovery caches bite here regularly.
• Migration collisions. If you've previously installed a logs-ish module, check the table name in the migration before running it; duplicate table creation is a common first-install error.
• Deploy/container pitfalls. On ephemeral filesystems (ECS, Cloud Run, Heroku) storage/logs may be empty or wiped on each deploy — a file-based viewer will look broken in production while working locally. Either persist the volume or use the DB-backed mode.
• Performance. Reading a multi-hundred-MB log file through a panel request will time out and spike memory. Verify the viewer paginates and reads incrementally; if not, cap the file size it will open via config or a wrapper.
• Sensitive data. Logs routinely capture request bodies, tokens, and emails. If this feeds a DB table, treat it as PII: restrict access, avoid replicating the table to analytics, and prune aggressively.
• Assets. Filament plugin installs often need php artisan filament:assets (or vendor:publish --tag=filament-assets) for any bundled views/CSS; a broken-looking page is usually missing assets, not a broken package.
• Extension points. The service provider is the seam — macros, custom Log models, or view overrides registered there survive package upgrades better than editing files in vendor/. If you need custom columns or parsing, extend the resource class in your own app/Filament namespace rather than patching the vendor copy.