Laravel Auditing Elasticsearch Driver Laravel Package

Product Decisions This Supports

• Audit trail storage strategy (build vs. buy): This package lets you keep owen-it/laravel-auditing (the de facto Laravel audit package) and swap the persistence backend to Elasticsearch. That means the decision reduces to "do we want our audit log in MySQL or in Elasticsearch?" rather than "do we build an audit system?" — a materially cheaper conversation.
• Compliance and forensic searchability: Audit records (who changed what, when, from where) are the raw material for SOC 2 / GDPR / internal incident review. Storing them in Elasticsearch turns "find every change to billing fields by this admin in Q3" from a slow SQL scan into a sub-second query, which is the difference between an audit request being answerable and being a fire drill.
• Roadmap: audit-as-a-product vs. audit-as-a-table: Once audits are queryable in ES, adjacent features become cheap — admin-facing activity feeds, tamper-evidence dashboards, anomaly alerts on privilege changes, retention/archival policies via data streams and ILM. This release's data stream handling improvements directly enable the time-based retention story you'd otherwise have to build.
• Build vs. buy on the plumbing: v2 is a major refactor of configuration validation, setup, and client behavior with retry logic coverage. That is precisely the unglamorous reliability work you don't want your team owning. Buying here (adopting the package) frees engineering for the domain-specific parts: which models are audited, what fields are captured, who can read the trail.
• Platform/infra budgeting: CI now tests an Elasticsearch version matrix (8.19.x with client ^8.19, 9.3.x with client ^9.3). This is a concrete input to your infrastructure roadmap — it tells you the package tracks both current ES majors, which de-risks an ES upgrade cycle you may already have on the calendar.
• Migration/upgrade planning as a product constraint: v2 removes deprecated JSON-based definitions and a deprecated date format from mappings. If any shipped feature or config preset depended on those, this is a scheduled piece of work with a user-visible tail (broken ingestion, mismatched indices), not a silent dependency bump.

When to Consider This Package

Adopt when:

• You already use owen-it/laravel-auditing and your audit volume or query patterns are outgrowing a relational table (large row counts, expensive ad-hoc queries, reporting on change history).
• Audit data has a read/analysis consumer — compliance reporting, admin activity views, security analytics — not just a write-and-forget requirement.
• You already operate Elasticsearch (or OpenSearch-compatible infra, verified) so the marginal infrastructure cost is near zero.
• You need time-based retention and rollover on audit data; the v2 data stream handling is aligned with modern ES patterns.
• You can absorb a v2 breaking-change migration in the current cycle: audit config reviewed, deprecated JSON definitions removed, custom mappings checked against the removed date format, and local integration environments aligned to the same ES/client version pairing CI enforces.
• Your team is comfortable with a single-maintainer package carrying production audit-critical responsibility — and you're prepared to pin versions and carry a fork-or-replace contingency.

Look elsewhere (or build thin in-house) when:

• Your audit data is low-volume and purely evidentiary; a relational table plus indexes is cheaper to operate and easier to reason about.
• You have no Elasticsearch footprint and no appetite to run one — the operational surface (cluster health, mappings, ILM, client-version coupling) is a real ongoing cost.
• You are on Elasticsearch 7.x or an unverified fork: the tested matrix covers ES 8.19.x / 9.3.x only, so you'd be off the supported path from day one.
• You need vendor-backed SLAs, guaranteed security response times, or a signed support contract for audit infrastructure — this is not that.
• You require the audit log to be immutable/WORM with cryptographic chaining; ES is a search store, not a compliance archive — you'd still need an append-only sink downstream.
• You cannot schedule the v2 migration work now. Staying on 1.4.x is viable short-term, but you inherit an unmaintained line; treat that as a dated decision, not a resting state.

How to Pitch It (Stakeholders)

For executives: We can make our audit trail genuinely usable — fast answers to "who changed this and when" for auditors, security, and support — without building or maintaining the plumbing ourselves. The package sits on top of the audit library we already use and stores records in Elasticsearch, which we already run. Version 2.0 is a stability release: cleaner configuration, better setup and data-stream handling, added retry logic for the Elasticsearch client, and CI that validates against two Elasticsearch major versions — which also de-risks our planned Elasticsearch upgrade.

For engineering: v2 is a major refactor, not a drop-in. Headline items: configuration reading/validation reworked, deprecated JSON-based definitions removed, deprecated date format removed from mappings, ElasticsearchSetupCommand reworked to resolve services via app() with container-cleanliness tests, tests moved to fixture files (including invalid-JSON failure modes), and phpstan/type definitions tightened. Client retry behavior now has test coverage. CI pins the ES PHP client to the ES minor used in testing.

The ask, framed as scope: adopting v2 = (1) audit config review and removal of any JSON-definition usage, (2) mapping override verification against the dropped date format, (3) alignment of local/CI integration environments to the tested ES + client version pairs, (4) a rollback plan — pin 1.4.x, run the upgrade behind a branch, and validate ingestion and query behavior against a staging ES cluster before touching production. Effort is bounded and config-shaped, which is the good kind of breaking change: it surfaces as a failing setup command, not as silently missing audit records.