Audit Kit Bundle Laravel Package

Product Decisions This Supports

• Audit/traceability requirements. Supports "who changed this record, and when" for regulated or high-trust domains (finance, healthcare, HR, multi-tenant B2B admin) — a common line item in SOC 2 / GDPR accountability reviews and enterprise security questionnaires.
• Investigation and support workflows. Blame fields (created_by / updated_by) shorten "who broke this record" triage and give support a cheap, non-invasive attribution layer without building a full audit subsystem.
• Scoped, opt-in rollout. The opt-in-per-entity design is the genuinely useful product property: it lets you audit only compliance-relevant entities rather than mandating "audit everything," which limits migration risk, write-path overhead, and schema churn.
• Build vs buy. The underlying mechanism is commodity: a Doctrine event subscriber/lifecycle hook writing timestamps and the current user ID on selected entities. This is a sub-day in-house build for most teams. Buy only if you run many Symfony services and want one consistent convention — and even then, be explicit that you are buying convention, not capability.
• Roadmap classification. This is not a feature and should not appear on a roadmap as one. It is an enabler sitting behind real features ("Full change history on invoices/contracts," "Prove who approved this payment"). Value it as risk reduction and sales-cycle unblocking, not differentiation.
• Stack-fit decision (important). Despite the framing as a Laravel/PHP package, this repository is a Symfony + Doctrine bundle (PHP >= 8.2, Symfony 7/8). It does not apply to Laravel/Eloquent. For a Laravel product, the correct decision is: built-in Eloquent timestamps plus a small trait/observer you own — no cross-stack adoption, no new dependency.

When to Consider This Package

Adopt only if all hold:

• Stack is Symfony 7/8 on PHP >= 8.2 with Doctrine ORM, and the service is expected to live for years.
• You need created/updated timestamps plus user blame on a defined subset of entities.
• You have no existing auditing convention, or an inconsistent ad-hoc one, and a shared standard has real coordination value across teams.
• You can vendor or fork it, and are comfortable owning it if the maintainer disappears.

Do not adopt when:

• Stack mismatch — Laravel/Eloquent or any non-Doctrine stack. Full stop.
• You need a real audit trail. This stores last-modified metadata only: no field-level history, no before/after values, no retention or export. For "show me every change to this contract," use a dedicated Doctrine versioning/audit bundle or an append-only domain-event log you own.
• Maturity risk is unacceptable. 1 star, 0 dependents, single-maintainer, no community signal, on a compliance-relevant code path. Treat as unproven software; a compliance dependency needs a bus factor you can defend in a review.
• You can't verify actor resolution. The bundle's value is the current-user lookup, and there's no documentation here covering behavior under console commands, queue workers, impersonation, or system-initiated writes. Unverified attribution is worse than no attribution in an audit context.
• You need support, SLA, or a security review response.

Minimum validation spike (1–2 days) before any decision:

• Resolve release/version sanity — the listed release date (2026-10-25) is in the future; confirm actual versioning and tags before procurement.
• Confirm the mechanism (Doctrine listener vs lifecycle callback) and its interaction with bulk DML, fixtures, existing listeners, and transaction boundaries.
• Confirm the no-authenticated-user path (CLI, workers) writes something defensible rather than a null or a stale identity.
• Confirm migration impact on existing tables: column additions, nullability, and backfill strategy for historical rows.
• Confirm there's a test suite you can trust; a package with tests you can read is forkable, one without is a liability.

How to Pitch It (Stakeholders)

For executives (1 minute). This is a small, free (MIT-licensed) plumbing library that automatically stamps records with when they were created or updated and which user did it. It contributes to "who touched this record" accountability for compliance-sensitive data — useful, but narrow. Two caveats matter more than the feature: it is not an audit log (it keeps no history, only last-modified metadata), and it has effectively no user base (1 star, no known dependents, one maintainer). We should not make it a dependency of record. The equivalent capability is roughly a one-day internal build, and building it ourselves removes the vendor and maturity risk while letting us define the rules for background jobs and impersonation. Recommendation: do not adopt as a strategic dependency; use it as a reference design or build in-house.

For engineering (5 minutes). Scope is intentionally narrow: Doctrine lifecycle wiring on opt-in entities. That narrowness is exactly why the buy case is weak — the work is small, and the parts that actually need judgement (actor resolution across web/queue/CLI/impersonation, interaction with bulk writes and fixtures, migration and backfill on existing tables) are decisions we should own rather than inherit from an undocumented single-maintainer bundle. If the target product is Laravel, this package is out of scope entirely; we implement the equivalent Eloquent trait/observer behind the existing model conventions and move on. Concrete ask: 1–2 day spike to validate the Symfony path or write the in-house version, then decide — cheap either way, and it keeps a compliance-relevant path off an unproven dependency.