README

Core domain model, contracts, and Artisan commands for Gesmuni Audit — 5W event model, interfaces, value objects, and CLI tools for auditable event logging and compliance.

This package provides the domain layer for audit event generation and storage, plus Artisan commands for maintenance operations. Concrete storage adapters (database, queue, etc.) are provided in separate packages.

Features

• 5W Event Model: Who, What, When, Where, Why — all as value objects and accessors
• Immutable Events: Once persisted, events cannot be modified or deleted (except via retention purge)
• Auto-enrichment: ID, timestamps, and defaults are injected automatically
• Separation of Concerns: Event generation and storage are decoupled via interfaces
• Lifecycle Auditing: Store emits lifecycle events for retention and purge operations
• Artisan Commands: Built-in gesmuni:audit:purge and gesmuni:audit:verify commands

Installation

composer require gesmuni/laravel-audit-base

The service provider is auto-discovered by Laravel. No manual registration needed.

Artisan Commands

gesmuni:audit:purge

Purge expired audit events based on the store's retention policy.

# Purge events exceeding the configured retention period
php artisan gesmuni:audit:purge

# Purge events older than a specific date
php artisan gesmuni:audit:purge --to=2025-01-01

The command asks for confirmation before deleting. If the --to date is more recent than the retention policy allows, the store raises a PurgeNotAllowed error.

gesmuni:audit:verify

Verify integrity of audit events in a date range.

# Verify the last 7 days (default)
php artisan gesmuni:audit:verify

# Verify a specific date range
php artisan gesmuni:audit:verify --from=2026-01-01 --to=2026-01-31

Displays a summary table with total, valid, invalid, and verification method. If any events fail integrity checks, a detailed table of failures is shown and the command exits with code 1.

Package Structure

src/
├── Commands/         # Artisan commands: AuditPurgeCommand, AuditVerifyCommand
├── Contracts/        # Interfaces: FiveW, AuditEventSink, AuditEventStore, etc.
├── Entities/         # AuditEvent entity
├── ValueObjects/     # Actor, Action, Source, Reason, RetentionEvent, etc.
├── Exceptions/       # Typed errors for contract enforcement
├── AuditServiceProvider.php

License

AGPL-3.0-or-later — see LICENSE