Tomato User Activities Module Laravel Package

Product Decisions This Supports

• Whether to ship an audit/activity trail now, and in what form. This package is positioned as the "user activity" layer of the TomatoPHP ecosystem: a structured record of actions taken by users inside a Laravel admin application, browsable from a dashboard. That maps directly onto roadmap items like "recent activity" widgets, per-user activity timelines on a profile page, and change/moderation history on records.

• Build vs. buy. An in-house activity log is deceptively expensive: an activity table with subject/causer polymorphism, event wiring across auth and model lifecycle, before/after capture, an admin browse-and-filter UI, retention pruning, and the index work to keep the admin page fast as the table grows. That is typically multi-week work plus permanent maintenance. This module is a credible "buy" candidate for the standard Laravel + Filament admin stack — the decision this supports is whether to spend engineering weeks on a solved-shaped problem or accept a thin third-party dependency.

• Scope resolution before commitment (the decision this release actually forces). The package presents two different products in two different places: the repository/Composer description advertises "automatically log every request made to your Laravel application, each request identified by hash" (a request-correlation logger), while the module description describes a user activity audit trail with admin review and filtering. These are different features with different data models, different storage volume, and different compliance value. A PM decision is required up front: which capability are we actually buying, and does it match the roadmap item we are trying to close? Do not let a spike answer this implicitly.

• Compliance and trust commitments. Activity records are the artifact behind access-review evidence (SOC 2 / ISO 27001 style), GDPR accountability ("who accessed what"), and internal security forensics. If audit logging appears in a security questionnaire, a customer contract, or a sales deck, it becomes a delivery dependency with a deadline. Conversely — and this is the important decision — an in-app CRUD activity table does not satisfy a request for tamper-evident or certified audit. Deciding which bar we are promising to clear is a product decision, not an engineering one.

• Support and incident-response cost. Per-user timelines ("what did this account do in the 30 minutes before the ticket") shorten diagnosis for both support escalations and security questions. That is an operating-cost lever and a CSAT input, and it is usually the fastest justification for the feature to pay for itself.

• Data-policy decisions the feature drags in. IP addresses and user agents are personal data under GDPR. Adoption implies a decision on what is stored, for how long, whether it is exportable on a subject-access request, and whether it belongs in the production database at all. Agree retention before the table starts growing, because pruning retroactively is a migration project.

• Adoption posture and risk appetite. Zero stars, zero dependents, a single author, one tagged release (v1.0.0, March 2024) with a changelog-link-only release note, and no documented upgrade path. The decision this supports is scoped pilot with a version pin, not standardize across products. Treat the release as the entry point to an evaluation, not as evidence of maturity.

When to Consider This Package

Consider it when:

• You are already on Laravel, ideally with Filament or a TomatoPHP admin panel, so the module's UI, auth, and service-provider conventions line up with your stack and integration is configuration plus migrations rather than glue code.
• You need human-readable activity history for admins — who did what, to which record, when, from where — rather than a machine-consumed event stream.
• You want a small, reversible dependency you can evaluate in a branch and remove without touching domain code, and you are comfortable pinning an exact version and reading the vendor source.
• Your volume is modest (thousands to low millions of rows) and a database-backed table with scheduled pruning is acceptable.
• Your admin panel is single-guard, or you are prepared to verify and configure which guard the module resolves the user from.

Look elsewhere when:

• You need tamper-evident or regulated-grade auditing: append-only storage, hash chaining, WORM retention, external SIEM or warehouse export. A database table in the app schema does not meet that bar, and we should not represent it as if it does.
• You need high-throughput eventing or streaming. Use an event pipeline, not an Eloquent module; per-request write amplification on the request path is a real cost at scale.
• You need procurement-grade assurance: vendor SLA, security review artifacts, named maintainer team, active release cadence. A ~two-year-old single-author 1.0 package in a community ecosystem does not clear that gate.
• You are not on Laravel/Filament, or your dependency policy excludes third-party admin modules.
• You only need model-level before/after diffs — spatie/laravel-activitylog is the more established answer, and the two can coexist (this module as the "who/where" layer, Spatie as the "what changed" layer) if you accept two tables.

Evaluation gates that must be answered before this touches the roadmap:

1. Which product is it? Request-correlation logging, user-action audit trail, or both? Confirm from src/ models and migrations, not from the description.
2. What is actually captured — auth/session events only, or model create/update/delete with old-value persistence? Are old values stored, and could they contain sensitive fields?
3. PII and retention: config toggles for IP/user-agent, redaction, pruning support, exportability for subject-access requests.
4. Laravel and Filament version constraints. Filament major-version mismatch is the most common failure mode and surfaces as a confusing class-not-found in the panel provider rather than a clear dependency conflict. Check composer.json first.
5. Index and growth plan on user_id, created_at, and any polymorphic columns, since the admin table is filtered on exactly those.
6. Maintenance signal: test coverage, commit activity after v1.0.0, and realistic bus factor. Last release in March 2024 is the question to ask, not a footnote.
7. Exit cost: how entangled the module is with Filament/TomatoPHP conventions, and whether we can wrap it behind our own interface so a swap is a one-file change.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost Laravel add-on that gives us a user activity history — the "who changed what, when, and from where" record that shows up in security questionnaires, customer audits, and support escalations, and that shortens the time to diagnose both support tickets and security questions. Adopting it is a bounded, reversible decision: it does not touch business logic, and it can be removed if we change course. The trade-off is maturity, not price. It is a v1.0 community package with a single author and no release since March 2024, so we treat it as a scoped pilot behind an exact version pin rather than a company-wide standard until we have reviewed what it records and how long it keeps it. Two caveats to flag honestly: first, the package advertises itself in two different ways — a request-correlation logger and a user activity audit trail — so the first deliverable is confirming which one we are actually buying and that it closes the roadmap item. Second, if a customer or auditor requires certified, tamper-evident audit, this does not clear that bar and we should not tell anyone it does.

To engineering: Composer-installable Laravel module from the TomatoPHP family, targeting the same admin/UI conventions, so we expect integration to be configuration plus migrations rather than custom glue. It is v1.0.0 with a changelog-link-only release note, so the first task is a timeboxed spike, not an integration: read the service provider, models, and migrations directly (the vendor source is the documentation here), and determine exactly which events are recorded, whether before/after values are persisted, and whether IP and user agent are stored. Verify the Laravel and Filament version constraints against our panel before installing — a Filament major mismatch shows up as a panel-provider class-not-found, not a dependency conflict. Then: pin the exact version, review the published migrations and add our own index migration if user_id / created_at are unindexed rather than editing the vendor's, run config:clear after publishing config (a stale cache makes the module silently do nothing), decide the retention/pruning schedule before the table grows, and subclass the vendor model or widget instead of editing published files so minor bumps stay clean. Wrap access behind our own interface so a future swap is one file. Report back on data captured, PII exposure, and query performance at a realistic row count before we commit this to the roadmap.