README

maatify/event-logging is a framework-agnostic standalone Composer package for registering event logging domains within the Maatify ecosystem.

This package provides strict domain isolation, MySQL persistence, and fail-open/fail-closed semantics without mandatory framework bindings. It intentionally relies on explicit Composer and runtime dependencies to operate autonomously from host applications and frameworks.

🚀 Key Features

Six Isolated Logging Domains: Explicit boundaries for audit, tracing, signals, and operations.
Domain-Specific Recorders: Tailored commands, DTOs, and repositories per domain.
MySQL-Only Persistence: Direct database persistence through domain-owned repositories.
AuthoritativeAudit Semantics: Fail-closed governance logging.
Fail-Open Boundaries: Non-authoritative domains can accept a PSR-3 fallback logger.
Optional Framework-Agnostic Provider and Bindings: Built-in optional factories and pure-PHP DI binding helpers for wiring dependencies.
Primitive Cursor-Based Read APIs: Dedicated, stable read/query capabilities.
No Mandatory Framework Bindings: Optional bindings are pure PHP convenience helpers and do not add framework runtime dependencies.
No Generic Logging API: Excludes shared generic loggers, generic log tables, or unified repositories.

📋 Requirements

PHP ^8.2
ext-json
ext-pdo

Composer/Runtime Dependencies:

psr/log
ramsey/uuid
maatify/exceptions
maatify/shared-common

📦 Installation

composer require maatify/event-logging

📖 Usage

Factory / Provider Wiring

Host applications provide their own dependencies (PDO, Clock, PSR-3 Logger) to instantiate the domain provider:

use Maatify\EventLogging\Provider\EventLoggingProviderFactory;
use Maatify\EventLogging\Common\SystemClock;

$pdo = new \PDO('mysql:host=localhost;dbname=mydb', 'user', 'pass');
$clock = new SystemClock();
$psrLogger = new \Monolog\Logger('event-logging-fallback'); // Optional for fail-open domains

// Create the provider service map
$provider = EventLoggingProviderFactory::createDefault($pdo, $clock, $psrLogger);

// Typed accessors enforce strict domain API boundaries
$auditTrail = $provider->auditTrail();

(See 01-factory-provider.php for manual factory/provider wiring. Hosts that prefer DI can also import the optional pure-PHP Maatify\EventLogging\Bootstrap\EventLoggingBindings::definitions() helper; this helper is not required and does not introduce framework-specific behavior.)

Domain Recorder Usage

Recording an authoritative audit (fail-closed, requires robust persistence):

$authoritativeAudit = $provider->authoritativeAudit();

// Using the primitive convenience record method
$authoritativeAudit->record(
    action: 'update_permissions',
    targetType: 'user',
    targetId: 123,
    riskLevel: 'HIGH',
    actorType: 'admin',
    actorId: 1,
    payload: ['role' => 'superuser'],
    correlationId: 'abc-123'
);

(See 03-authoritative-audit-record.php and 04-audit-trail-record.php for broader examples.)

🏗️ Logging Domains

The package maintains six separated event domains:

AuthoritativeAudit — Governance/security posture logging with fail-closed semantics.
AuditTrail — Reads, views, exports, and navigation visibility events.
SecuritySignals — Authentication and security anomaly signals.
BehaviorTrace — Operational activity and mutation-only behavior events.
DiagnosticsTelemetry — Technical observability and diagnostic events.
DeliveryOperations — Async jobs, notifications, webhooks, and delivery lifecycle events.

🛡️ Architecture Guarantees

Framework-Agnostic: Operates without any dependency on external framework containers or routes.
Standalone Execution: Complete isolation from host application codebases.
Domain Isolation: Every logging domain has exclusive ownership over its DTOs, tables, and policies.
Host-Provided PDO: Database connections must be injected; the package does not manage connection lifecycles.
MySQL-Only: Relies purely on MySQL schema without SQLite fallback support.
Explicit Dependencies Only: Avoids zero-dependency assumptions; explicit runtime requirements ensure robustness.
No Generic Paradigms: The package does not expose a catch-all logger, generic recorder, generic repository, or shared generic log table. PSR-3 is used only as an optional fallback logger for fail-open domains.

🧪 Examples

The examples/ directory contains plain PHP illustrative skeletons covering integration scenarios. See the Examples Coverage Plan for full context.

📚 Documentation

Integration Guides

✅ Quality Status

PHP 8.2+
PHPStan Level Max
PHPUnit testing available
GitHub Actions CI validated

🪪 License

This package is licensed under the MIT License. See the LICENSE file for details.

👤 Author

Engineered by Mohamed Abdulalim (@megyptm)
Backend Lead & Technical Architect
https://www.maatify.dev

[Built with ❤️ by Maatify.dev — Unified Ecosystem for Modern PHP Libraries]

maatify / event-logging

Maintainers

Package info

Statistics

Security