Doctrine Audit Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony/Doctrine-Centric: The bundle is explicitly designed for Symfony projects leveraging Doctrine ORM, making it a near-perfect fit for Laravel applications using Doctrine DBAL (via doctrine/dbal) or Doctrine ORM (via doctrine/orm).
  • Laravel’s native Eloquent ORM is not supported, but Doctrine integration is viable if the project already uses it (e.g., legacy migration, hybrid stack, or Doctrine-based microservices).
  • If the goal is Eloquent audit logging, alternatives like spatie/laravel-activitylog may be more suitable.
• Event-Driven Design: The bundle hooks into Doctrine’s lifecycle events (prePersist, preUpdate, preRemove), aligning with Laravel’s event system but requiring custom event listeners for seamless integration.
• Extensibility: Supports custom metadata (e.g., user IDs, timestamps) via audit listeners, allowing alignment with Laravel’s authentication (e.g., Auth::user()) or middleware.

Integration Feasibility

• Doctrine Dependency:
  • High feasibility if the project already uses Doctrine ORM/DBAL.
  • Low feasibility for pure Eloquent projects (would require rewriting models or proxying events).
• Configuration Overhead:
  • Requires YAML/XML/PHP config for entity mappings (similar to Doctrine’s orm.xml or annotations).
  • Laravel’s service provider pattern can wrap configuration to reduce boilerplate.
• Database Schema Impact:
  • Automatically creates an audit_entry table (customizable).
  • No schema migrations for Laravel (must be handled via Doctrine Migrations or Laravel Migrations with Doctrine schema tool).

Technical Risk

Key Questions

1. Is Doctrine ORM/DBAL already in use?
   • If no, assess migration effort vs. alternative audit solutions (e.g., Eloquent observers, database triggers).
2. What audit granularity is needed?
   • Field-level changes? Entity-level? Only timestamps?
3. How will audit logs be queried?
   • Custom Doctrine repositories? Laravel query builder? Requires hybrid approach.
4. What’s the rollback/recovery plan for audit data?
   • Does the system need audit log purging or restoration?
5. Will this integrate with existing monitoring/logging?
   • ELK, Datadog, or custom dashboards? May need log forwarding.

Integration Approach

Stack Fit

• Best Fit:
  • Laravel + Doctrine ORM (e.g., hybrid apps, legacy migrations, or Doctrine-based services).
  • Laravel + Doctrine DBAL (for raw SQL apps needing audit trails).
• Workarounds for Eloquent:
  • Option 1: Use Doctrine ORM alongside Eloquent (e.g., via laravel-doctrine/orm).
  • Option 2: Proxy Eloquent events to Doctrine (high complexity, not recommended).
  • Option 3: Abandon this bundle in favor of Eloquent-native solutions.

Migration Path

1. Assess Current ORM:
   • If Eloquent-only, decide if Doctrine adoption is justified.
   • If Doctrine exists, proceed to integration.
2. Install Dependencies:

   composer require damienharper/auditor-bundle doctrine/orm doctrine/dbal
   

3. Configure Bundle:
   • Add to config/bundles.php (Symfony-style; Laravel may need service provider).
   • Define audit mappings (YAML/XML/PHP) for entities.
4. Entity Annotation/Mapping:
   • Use Doctrine annotations or XML/YAML to mark audited entities.
   • Example:

     /**
      * @Auditor\Audit
      */
     class User {}
     

5. Customize Metadata:
   • Extend AuditorListener to inject Laravel-specific data (e.g., Auth::user()).
6. Database Setup:
   • Run Doctrine migrations or manually create the audit_entry table.
   • Example schema:

     CREATE TABLE audit_entry (
         id INT AUTO_INCREMENT PRIMARY KEY,
         entity_class VARCHAR(255) NOT NULL,
         entity_id INT NOT NULL,
         action VARCHAR(10) NOT NULL, -- 'U' (update), 'I' (insert), 'D' (delete)
         timestamp DATETIME NOT NULL,
         user_id INT, -- Custom field for Laravel auth
         old_data JSON,
         new_data JSON,
         INDEX (entity_class, entity_id, action)
     );
     

Compatibility

Sequencing

1. Phase 1: Proof of Concept
   • Audit a single non-critical entity (e.g., LogEntry).
   • Verify data capture and performance impact.
2. Phase 2: Full Integration
   • Roll out to core entities (User, Order, etc.).
   • Implement custom metadata (e.g., user IDs from Laravel’s Auth).
3. Phase 3: Query Optimization
   • Add indexes to audit_entry.
   • Implement archiving/purging for old logs.
4. Phase 4: Monitoring
   • Track audit log query performance.
   • Set up alerts for failed audits (e.g., Doctrine event listener errors).

Operational Impact

Maintenance

• Pros:
  • Minimal manual intervention once configured (Doctrine handles event listeners).
  • Centralized audit logic (changes in one place).
• Cons:
  • Doctrine-specific maintenance (e.g., ORM updates, schema changes).
  • Custom listeners may need updates if Laravel’s Auth or User model changes.
• Tooling:
  • Use Doctrine Migrations for schema changes.
  • Laravel Artisan commands can wrap bundle utilities (e.g., php artisan audit:purge).

Support

• Debugging:
  • Doctrine events may conflict with Laravel’s model observers.
  • Audit log queries could be slow; optimize with indexes or read replicas.
• Troubleshooting:
  • Check Doctrine event listeners are registered.
  • Verify database transactions (audit logs should not fail silently).
• Documentation:
  • Bundle docs are Symfony-focused; create Laravel-specific runbooks for:
    • Entity mapping in Laravel.
    • Custom metadata injection.
    • Querying audit logs via Laravel’s query builder.

Scaling

• Performance:
  • Write Impact: Minimal (audit logs are async-friendly but not async by default).
  • Read Impact: High if querying audit_entry directly; mitigate with:
    • Materialized views (e.g., pre-aggregated audit stats).
    • Read replicas for audit queries.
    • Pagination (cursor() or offset/limit).
• Horizontal Scaling:
  • Audit logs are append-only; sharding may be needed for high-write systems.
  • Consider event sourcing for