Maatify Event Logging

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:

1. AuthoritativeAudit — Governance/security posture logging with fail-closed semantics.
2. AuditTrail — Reads, views, exports, and navigation visibility events.
3. SecuritySignals — Authentication and security anomaly signals.
4. BehaviorTrace — Operational activity and mutation-only behavior events.
5. DiagnosticsTelemetry — Technical observability and diagnostic events.
6. 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.

• 01-factory-provider.php
• 02-manual-wiring.php
• 03-authoritative-audit-record.php
• 09-admin-read-audit-trail.php
• 11-cursor-pagination.php
• 13-psr-fallback-logger.php

---

📚 Documentation

• Event Logging Package Reference
• Schema Layout
• Testing Strategy

Architecture

• Unified Logging Architecture
• Logging Domain Rules
• CI Workflow Standard
• Storage & Schema Guarantees
• Deferred Scope & Future Considerations
• Authoritative Audit Pipeline
• Admin Query API Roadmap

Integration Guides

• Installation Guide
• Factory Usage
• Manual Wiring
• DI Bindings
• Admin Read Usage

---

✅ 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