Download the PHP package yahyaerturan/audit without Composer

yahyaerturan/audit

An immutable, semantic audit-trail library for PHP. Framework-independent, portable across SQLite and PostgreSQL, and designed so a recorded fact is faithful, queryable, and never silently altered or swallowed.

An audit entry answers who did what to which thing, when, in what context, and what changed — as a durable business fact, not as a line of text in a log file.

Why an audit trail is not a log

There is deliberately no PSR-3 implementation and no log-level API (see ADR-001). Audit records are evidence, and evidence has structure, identity, and integrity requirements that log lines do not.

Why an audit trail is not event sourcing

Event sourcing rebuilds application state by replaying a full, ordered event stream; the stream is the source of truth. This library does the opposite: your database remains the source of truth, and the audit trail records semantic facts about changes you chose to make explicit. There is no projection, no replay-to-derive-state, and no requirement that every state change emit an event. You decide what is worth recording, and you record it in the same transaction as the business change when you want them to stand or fall together.

Design guarantees

• Immutable, append-only. AuditStore exposes append() only — no ordinary update or delete (ADR-004). Entries are fully validated at construction and expose no setters.
• Framework-free core. The core package has zero framework symbols; framework coupling lives in separate adapter packages (ADR-002).
• Portable persistence. Shared SQL logic targets a tiny connection port; only indexed dimensions are columns and flexible payloads are JSON — there is no arbitrary JSON-query API (ADR-005, ADR-006).
• Deterministic seams. Time comes from a PSR-20 clock and ids from a generator contract, so recording is testable and reproducible (ADR-007, ADR-009).
• Redaction before persistence. Sensitive keys are masked before an entry is ever written (ADR-011).
• Caller owns the transaction. append() never begins, commits, or rolls back (ADR-012).
• No silent failure. Every error propagates as a typed exception; nothing is caught-and-logged.

Requirements

Still on PHP 8.3 or 8.4? Use the 1.0.x line, whose last release is 1.0.1:

Installation

Quick start (SQLite)

PostgreSQL

The API is identical — only the PDO DSN changes. The driver is detected from PDO (pgsql); the schema manager then applies the PostgreSQL migrations automatically.

PostgreSQL entries use TIMESTAMPTZ(6) timestamps and JSONB payloads; SQLite uses fixed-width UTC text timestamps (so ordering is lexicographic) and canonical JSON text validated by json_valid(). Only the sqlite and pgsql PDO drivers are supported — anything else fails fast with UnsupportedDatabaseDriver.

Recording

An AuditRecord is an immutable, fluent description of an action. Every builder method returns a new instance:

Change operations preserve the difference between absent and present with null: added(null), removed(null), and replaced($from, $to) are distinct, and replaced() rejects an identical from/to (ADR-008). Event names must match ^[a-z0-9][a-z0-9_-]*(\.[a-z0-9][a-z0-9_-]*)*$ (ADR-003); uppercase or otherwise invalid names are rejected, never silently normalized.

Values are normalized (backed enums and date/time values are handled; everything else must be a strict JSON value), then redacted, then size-checked against AuditLimits before persistence.

Reading and querying

Results are ordered occurred_at DESC, id DESC and paginated by an opaque keyset cursor — there is no offset API and no total count(), because both are expensive on very large audit tables and encourage fragile pagination (ADR-010). AuditPage exposes entries(), nextCursor(), and hasMore(); pass the cursor back through after() unchanged.

Query criteria: forTenant() / withoutTenant() / anyTenant(), forEvent() / eventPrefix(), byActor(), forSubject(), withCorrelationId() / withCausationId() / withRequestId(), since() / until(), forIds(), limit(), after().

Schema migrations

The package owns its schema and never relies on a host framework's migrator. Migrations are versioned SQL assets under resources/sql/<driver>/NNN_name.sql, applied in ascending order; each runs inside its own transaction on your connection, so a failure records no version and leaves prior migrations intact.

Two tables are created: audit_entries (the facts) and audit_schema_migrations (the version ledger). The audit_entries table carries indexes for the time, tenant+time, subject, actor, event, and correlation dimensions. See docs/persistence.md for the full schema.

CodeIgniter 4 users get php spark audit:schema:migrate and php spark audit:schema:status wrappers around this same manager — see the adapter documentation below.

Transaction semantics

Normative. The store never owns the business transaction: append() does not begin, commit, or roll back. It executes its single INSERT on the connection you supply, so it participates in whatever transaction that connection is already in (ADR-012).

Use the same connection when the audit record must exist if and only if the business mutation commits:

Use a separate connection (a dedicated database) when the audit record must survive even if the business transaction rolls back. Both behaviors are covered by the test suite.

Redaction and privacy

Redaction runs before persistence, so a masked value is never written to the database in the first place (ADR-011). The default pipeline masks a conservative set of clearly sensitive keys — password, secret, access_token, refresh_token, authorization, cookie, private_key, card_number, cvv, and similar — replacing the value with the marker [REDACTED]. Matching is case-insensitive and by exact key name, so legitimate keys such as foreign_key survive. For a change, the operation and path are preserved (the fact that something changed is not lost) while the from/to values are masked.

Warning. Redaction is a safety net, not a substitute for not collecting secrets or PII in the first place. It only masks known key names; a secret stored under an innocuous key will not be caught. Audit entries are durable and append-only: once written, a value cannot be edited or removed through this library. Treat the audit store as sensitive data, restrict access to it, and review what you record. See SECURITY.md.

You can extend the default pipeline with exact paths. Each path is prefixed to say where it applies: changes.<path> masks the from/to of that exact change path, and metadata.<a.b.c> masks the addressed leaf of a (possibly nested) metadata map:

CodeIgniter 4 adapter

A separate package, in its own repository, wires everything above into CodeIgniter 4 — running audit SQL on your application's own CI4 connection, auto-discovering services, and adding Spark schema commands and an opt-in request-context filter.

Full details — configuration, actor/tenant resolution, the audit-context filter, transaction coupling, and the service reference — are in the adapter's own repository, yahyaerturan/audit-codeigniter4. The core package never depends on the adapter, and its test suite runs with the adapter absent.

Failure behavior

Nothing is silently swallowed and nothing is caught-and-logged. Failures surface as typed exceptions that all implement the YahyaErturan\Audit\Exception\AuditException marker:

Limits are enforced by throwing — data is never truncated automatically. Because the store never owns the transaction, a thrown exception leaves the surrounding transaction for your code to roll back.

Documentation

• docs/architecture.md — dependency graph, recording pipeline, persistence port, adapter model, append-only semantics.
• docs/persistence.md — schemas, indexes, transaction choices, SQLite and PostgreSQL notes, migrations.
• docs/usage.md — recording, querying, normalization, redaction, and limits in depth.
• docs/adr/ — architecture decision records.
• docs/releasing.md — packaging and release checklist.
• SECURITY.md — threat model, tamper-resistance limits, PII guidance.
• CHANGELOG.md — release history.

License

MIT — see LICENSE.