Tomato Logs Laravel Package

Technical Evaluation

Architecture fit. tomatophp/tomato-logs is a Filament panel plugin, not a logging subsystem. It wraps jackiedo/laravel-log-reader and registers a log-browsing screen inside the TomatoPHP admin panel — listing files in storage/logs, opening them, filtering by level/date/keyword, downloading, refreshing, and clearing. Functionally it is a file viewer: no aggregation, no alerting, no retention policy, no structured queries. The architecture fit is therefore binary: if the product is already on Laravel 10/11 + Filament 3 + tomatophp/tomato-admin, this is a config file and a menu entry. If it is not, adopting it means importing a slice of the TomatoPHP ecosystem to obtain a capability that opcodesio/log-viewer already provides more maturely and with far broader adoption. That is a different decision with a different cost, and the 0-star / 0-dependent / single-maintainer profile should not be the deciding factor — stack fit should be.

Integration feasibility. High if the stack matches. Surface area is small enough to read end-to-end in minutes: a plugin class, a config file, a controller, and views. Installation is composer require, an optional install command, config/asset publishing, and one ->plugins([...]) registration in the panel provider. The realistic work is not the install; it is the access control and logging-configuration work we must do around it. Budget a day of engineering for a competent Laravel developer, most of which is the gate, the canary test, and the logging channel review.

Technical risk. The dominant risk is not code quality — it is that the package is effectively unmaintained (last release 2024-04-29, a style-only patch; no issue triage; no security-disclosure channel). Secondary, and more urgent, is authorization: a log viewer is a deliberately privileged window into stack traces, SQL with bound parameters, request payloads, and occasionally tokens or PII. Assume the package does not enforce an admin gate until we have proven otherwise by logging in as a low-privilege user. Additional risks: the reader loads file contents into memory, so large single-file logs time out; local disk only, so cloud-shipped logs render as an empty directory; the clear action is destructive with no undo; Filament v2 vs v3 plugin registration differs and a mismatch is a hard blocker rather than graceful degradation; and the registered route prefix can collide with an existing admin segment. The composite score of 0.43 is a fair read — this is a small convenience with a real carrying cost, not a platform component.

Key questions for the team.

• Are we actually on Filament 3 and tomatophp/tomato-admin, verified via composer why-not against locked versions, or only aspirationally so?
• Which role is authoritative for log access, and is that gate owned by the application or by the panel?
• Is the production logging channel daily with a LOG_MAX_FILES cap, or a single growing laravel.log?
• Do logs contain PII, credentials, or customer data, and do our privacy/compliance obligations permit a file-reading web UI in front of them?
• Who owns the fork, and what is the pre-agreed trigger?

Integration Approach

Stack fit. Hard prerequisites: PHP 8.1+, Laravel 10/11, Filament 3, tomatophp/tomato-admin installed. Confirm all four before committing. If any is missing, stop and route the requirement to opcodesio/log-viewer — off-stack, this package buys a dependency and a controller we will have to wire ourselves.

Migration path. There is no migration in the data sense — the package adds no schema of its own beyond whatever the install step optionally publishes (menu/permission tables). The migration that matters is the exit path. Constrain the blast radius from day one so a later swap is a deletion rather than a rewrite: own the menu entry and route in our code rather than letting the package define them exclusively; forbid other code from referencing the package's classes, view namespaces, or config keys directly; keep the integration to a plugin registration plus a published config. If we replace it with opcodesio/log-viewer in six months, the diff should be one line in the panel provider and one config file.

Compatibility discipline. Pin the exact version. Check php artisan route:list immediately after install for prefix collisions, and run composer why-not before planning anything, since a Filament major mismatch is a blocker. Re-publish config and run config:clear / view:clear after any upgrade before debugging a config change that "isn't taking effect."

Sequencing.

1. Verify the stack and locked versions; confirm the exact plugin FQCN and install-command signature in vendor/.
2. Confirm the logging channel. Switch to daily with a rotation cap before mounting the viewer — this is a prerequisite, not a follow-up, because it is what makes listing and reading instant and makes "show me yesterday" a file selection rather than a scroll.
3. Define the ability once, in application code: a viewLogs gate bound to an admin role. Testable, owned by us.
4. Register the plugin conditionally, so the menu entry never exists for non-admins, and add route-level middleware as defense in depth.
5. Publish config and point the path at what config/logging.php actually writes.
6. Write the canary test — a non-admin receives 403/404 on the log route — and keep it green across every Filament and Laravel upgrade.
7. Roll to staging first. Reproduce a deliberate 500, filter by error, confirm the triage loop works. Do not mount in production without redaction and a strict admin gate.
8. Document the "download, then clear" habit and, at minimum, restrict or wrap the destructive clear action outside environments where losing the log is acceptable.

Operational Impact

Maintenance. Adoption is a self-maintenance commitment. With zero dependents and no security-response path, the honest framing is: we are the maintainer. That is acceptable only because the surface area is a controller, a config, and views — roughly a day to fork under our org. The TPM deliverable here is the pre-committed trigger, written down in advance: if this breaks on the next Laravel or Filament major, we fork rather than block the upgrade. Deciding that now converts a latent surprise into a planned, cheap cost; deciding it at the moment of a blocked upgrade converts it into an incident.

Support. This is the actual value proposition and the line item worth measuring. Faster first response without SSH access; non-engineers able to pull a log for a ticket; staging debugging without escalating to engineering. The success metric is not "log viewer adopted" — it is a measurable drop in tail -f requests and infra-access escalations for routine triage. Present it to stakeholders as a small, free, MIT-licensed convenience that shortens time-to-diagnose, explicitly not as an observability platform or as monitoring risk reduction. Tiering is the key product decision it supports: fund "developers can eyeball errors in staging" here, and explicitly and visibly defer "we can investigate a production incident across instances" to Sentry/Better Stack/Datadog/CloudWatch/Loki.

Scaling. It does not scale, by design. Local disk only; no cross-host search; no retention policy; memory-bound reads that slow or fail on large files. It is appropriate for dev, staging, small single-instance production, shared hosting, single VPS, or on-prem appliance deployments where observability budget is zero and keeping logs on-box is a requirement rather than a preference. It is not appropriate where compliance obligations (GDPR, HIPAA, SOC 2) apply and logs may contain PII — a file-reading UI with no redaction guarantees is the wrong control to put in front of auditors, regardless of how well it is gated.

Failure modes to brief the team on.

• Blank UI or empty list — filesystem permissions (www-data cannot read storage/logs) or a full disk, surfacing as silence rather than an error.
• Timeouts on large files — the symptom of a single-file channel; fix the channel, not the viewer.
• Truncated stack traces — rotation mid-read; refresh before concluding the log is incomplete.
• Stale-looking filters — refresh re-reads the file; filters apply on that read.
• Irreversible clear — the one action with no recovery; make download-first the default habit, not the exception.
• Route collision or Filament major mismatch — caught by route:list and composer why-not, both of which belong in the pre-install checklist.

Ramp-up. Low. Ten minutes of source reading, one page of documentation, and one test. The onboarding risk is not technical literacy — it is behavioural: teams must internalize that this is a developer convenience for staging triage, and that proposing it as the observability story is the misread to correct early.