README

Audit trail for Yii3 applications: who changed what and when, with sensitive value masking. Stateless core — bring your own writer (DB adapter lives in a separate package).

Using an AI coding assistant? llms.txt has a compact API reference you can use.

Requirements

• PHP 8.3+
• psr/clock ^1.0

Installation

composer require rasuvaeff/yii3-audit-log

Yii3 config-plugin

The package ships config/di.php and config/params.php via config-plugin. It wires AuditLogger and SensitiveValueMasker, but intentionally does not bind AuditWriter or Psr\Clock\ClockInterface. Install exactly one writer adapter or bind AuditWriter in your application config:

use Psr\Clock\ClockInterface;
use Rasuvaeff\Yii3AuditLog\AuditWriter;

return [
    AuditWriter::class => MyAuditWriter::class,
    ClockInterface::class => MyClock::class,
];

Default params:

return [
    'rasuvaeff/yii3-audit-log' => [
        'sensitiveKeys' => ['password', 'secret', 'token', 'api_key', 'credit_card'],
        'skipEmptyChangeSets' => true,
    ],
];

Usage

Basic logging

use Rasuvaeff\Yii3AuditLog\AuditActor;
use Rasuvaeff\Yii3AuditLog\AuditChangeSet;
use Rasuvaeff\Yii3AuditLog\AuditLogger;
use Rasuvaeff\Yii3AuditLog\AuditSubject;
use Rasuvaeff\Yii3AuditLog\InMemoryAuditWriter;

$logger = new AuditLogger(writer: $writer, clock: $clock);

$logger->logChange(
    actor: AuditActor::user(id: $userId, name: 'John'),
    subject: AuditSubject::of(type: 'order', id: (string) $orderId),
    changes: AuditChangeSet::fromArrays(
        old: ['status' => 'new', 'total' => 0],
        new: ['status' => 'paid', 'total' => 99.95],
    ),
);

Implementing a writer

use Rasuvaeff\Yii3AuditLog\AuditEvent;
use Rasuvaeff\Yii3AuditLog\AuditWriter;

final readonly class DbAuditWriter implements AuditWriter
{
    public function write(AuditEvent $event): void
    {
        // INSERT INTO audit_log ...
        // $event->getId(), $event->getActor(), $event->getAction(),
        // $event->getSubject(), $event->getChangeSet(), $event->getOccurredAt()
    }
}

Sensitive value masking

use Rasuvaeff\Yii3AuditLog\AuditLogger;
use Rasuvaeff\Yii3AuditLog\SensitiveValueMasker;

$logger = new AuditLogger(
    writer: $writer,
    clock: $clock,
    masker: new SensitiveValueMasker(), // masks password, secret, token, api_key, credit_card
);

// Custom sensitive keys:
$masker = new SensitiveValueMasker(sensitiveKeys: ['ssn', 'pin', 'password']);

System actor

$logger->logCreate(
    actor: AuditActor::system(),
    subject: AuditSubject::of(type: 'config', id: 'smtp'),
    changes: AuditChangeSet::fromArrays(old: [], new: ['host' => 'mail.example.com']),
);

Request metadata

use Rasuvaeff\Yii3AuditLog\AuditMetadata;

$logger->logChange(
    actor: $actor,
    subject: $subject,
    changes: $changes,
    metadata: new AuditMetadata(
        requestId: $request->getHeaderLine('X-Request-Id'),
        ip: $request->getServerParams()['REMOTE_ADDR'] ?? null,
        userAgent: $request->getHeaderLine('User-Agent'),
    ),
);

API reference

AuditLogger

AuditActor

AuditSubject

AuditChangeSet

AuditChange

SensitiveValueMasker

Security

• Masker is applied inside AuditLogger before the event reaches the writer — secrets never reach storage.
• Masking is case-insensitive: Password, PASSWORD, password all masked.
• DB writer implementations must use parameterized queries.

Examples

See examples/ for complete usage examples.

Development

make install
make build
make cs-fix
make test
make test-coverage
make mutation
make release-check

make test-coverage and make mutation bootstrap pcov inside the composer:2 container because the base image has no coverage driver.

License

BSD-3-Clause. See LICENSE.md.