Entity Audit Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Seamless Doctrine Integration: Leverages Doctrine ORM events to transparently capture entity changes, requiring minimal application-level modifications. This aligns well with Laravel’s Eloquent ORM (which is Doctrine-inspired) and avoids reinventing audit logic.
  • Schema-Aware: Automatically generates audit tables (*_audit) during migrations, reducing manual SQL overhead. Compatible with Laravel’s migration system if configured via Doctrine extensions (e.g., doctrine/dbal).
  • Revision Tracking: Provides granular revision history (INS/UPD/DEL) with timestamps and usernames, addressing compliance/auditability needs without custom logic.
  • Query Flexibility: Offers methods to retrieve historical states (find), revision lists (findRevisions), and diffs (compare), which can be adapted for Laravel’s query builder or repositories.
  • Symfony Compatibility: While primarily Symfony-focused, the core library (simple-things/entity-audit) is framework-agnostic and can be integrated into Laravel via standalone usage (see Installation (Standalone)).

• Cons:

  • Doctrine Dependency: Requires Doctrine ORM (or DBAL) for schema management and event listeners. Laravel’s Eloquent lacks native Doctrine integration, necessitating a bridge (e.g., doctrine/dbal + custom listeners).
  • No Native Eloquent Support: Audit tables are generated as raw SQL tables, not Eloquent models. Requires manual model mapping or a wrapper layer.
  • Performance Overhead: Audit tables duplicate entity schemas, increasing storage and write latency (each CRUD operation triggers audit logs).
  • Limited Laravel Ecosystem: No built-in Laravel service providers, event dispatchers, or queue integration (e.g., async audit logging).

Integration Feasibility

• High-Level Path:

  1. Bridge Doctrine Events: Use doctrine/dbal to hook into Laravel’s Eloquent lifecycle (e.g., saving, deleted) and forward events to the audit bundle’s listeners.
  2. Schema Migration: Adapt the bundle’s SchemaTool to work with Laravel migrations (e.g., via doctrine/dbal schema updates).
  3. Query Layer: Create a facade or repository to wrap AuditReader methods for Eloquent compatibility (e.g., Audit::find(Model::class, $id, $revision)).
  4. Username Resolution: Override the username_callable to integrate with Laravel’s auth system (e.g., Auth::user()->name).

• Key Challenges:

  • Event System Mismatch: Laravel’s Eloquent events (ModelObserver, Events::dispatch) differ from Doctrine’s event system. Requires a translation layer.
  • Migration Conflicts: Laravel’s migrations may conflict with the bundle’s schema updates. Solution: Use a custom migration service or merge strategies.
  • Association Handling: The bundle supports associations, but Laravel’s polymorphic/many-to-many relationships may need special handling (e.g., custom global_ignore_columns).

Technical Risk

Key Questions

1. Is audit granularity sufficient?

   • Does the bundle’s revision model (global rev + revtype) meet requirements, or are entity-level timestamps needed?
   • Example: For financial audits, you might need per-field change tracking.

2. How to handle Laravel’s unique features?

   • Soft Deletes: The bundle marks deletions as revtype: DEL. Will this conflict with Laravel’s deleted_at?
   • Timestamps: created_at/updated_at are ignored by default. Should these be audited separately?

3. Async Logging Needs

   • Should audit logs be written synchronously (blocking) or asynchronously (e.g., via Laravel queues)?
   • Tradeoff: Async reduces latency but complicates error handling.

4. Query Performance

   • Audit tables may grow large. Are read-heavy queries (e.g., findRevisions) optimized (e.g., indexed rev columns)?

5. Testing Strategy

   • How to test audit behavior in CI? Mock Doctrine events or use a lightweight test database.

6. Rollback Support

   • Can the bundle restore entities to prior revisions? If so, how does this interact with Laravel’s transactions?

Integration Approach

Stack Fit

• Core Compatibility:

  • Laravel 10+: Works with PHP 8.2+ and Symfony components (e.g., doctrine/dbal v4).
  • Eloquent ORM: Requires a bridge to translate Eloquent events to Doctrine events. Options:
    • Option 1: Use doctrine/dbal + custom listeners to mirror Eloquent events.
    • Option 2: Extend Eloquent’s Model class to dispatch Doctrine events.
  • Database: Supports PostgreSQL, MySQL, SQLite (auto-increment IDs required).

• Dependencies:

  • Required:
    • doctrine/dbal (≥4.0) for schema management.
    • simple-things/entity-audit (≥2.0) for core logic.
  • Optional:
    • doctrine/orm (if using full Doctrine ORM; overkill for Laravel).
    • laravel/framework (≥10.0) for event/queue integration.

• Conflicts:

  • Laravel Migrations: The bundle’s SchemaTool may conflict with Laravel’s migrations. Mitigation:
    • Run bundle’s schema updates in a dedicated migration class.
    • Use --dry-run to preview SQL changes.
  • Soft Deletes: Bundle treats deletions as revtype: DEL. Ensure this aligns with Laravel’s SoftDeletes trait.

Migration Path

1. Phase 1: Proof of Concept (1–2 weeks)

   • Goal: Audit a single entity (e.g., User) to validate integration.
   • Steps:
     1. Install doctrine/dbal and simple-things/entity-audit.
     2. Create a custom AuditServiceProvider to bootstrap the bundle’s listeners.
     3. Configure entity_audit.yaml (or PHP equivalent) for the test entity.
     4. Run php artisan doctrine:schema:update --dump-sql to preview audit tables.
     5. Implement a facade to wrap AuditReader (e.g., Audit::find()).
     6. Test CRUD operations and verify audit logs.

2. Phase 2: Full Integration (2–4 weeks)

   • Goal: Scale to all critical entities with performance tuning.
   • Steps:
     1. Event Bridge: Map Eloquent events to Doctrine events (e.g., Model::saved() → preFlush).
     2. Migration Strategy:
        • Option A: Use a custom migration to run the bundle’s schema updates.
        • Option B: Merge audit table creation into existing migrations.
     3. Query Layer: Build repositories for common audit queries (e.g., UserAuditRepository).
     4. Username Resolution: Override username_callable to use Laravel’s Auth system.
     5. Performance:
        • Benchmark write operations; consider async logging (e.g., queue-based).
        • Add indexes to audit tables (e.g., rev, entity_id).
     6. Testing:
        • Unit tests for event listeners.
        • Integration tests for audit queries.

3. Phase 3: Optimization (Ongoing)

   • Goals:
     • Reduce audit table bloat (e.g., archive old revisions).
     • Optimize queries (e.g., materialized views for common reports).
     • Add Laravel-specific features (e.g., queue-based async logging).

Compatibility