Audit Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require data-dog/audit-bundle
   

   Add to config/bundles.php:

   DataDog\AuditBundle\DataDogAuditBundle::class => ['all' => true],
   

2. Database Setup: Run migrations or schema update:

   php bin/console doctrine:migrations:diff && php bin/console doctrine:migrations:migrate
   

   (or doctrine:schema:update --force)

3. First Audit: Perform a CRUD operation on any Doctrine entity (e.g., User):

   $user = new User();
   $user->setName('Test');
   $em->persist($user);
   $em->flush(); // Audit log auto-generated
   

Key First Use Case

Verify audit logs in the database (audit_entry table) after modifying an entity. Check fields like:

• action (e.g., INSERT, UPDATE)
• entity_class (e.g., App\Entity\User)
• changes (JSON diff of modified fields)
• user_id (if authenticated via TokenStorage)

Implementation Patterns

Core Workflow

1. Automatic Auditing:

   • All Doctrine ORM operations (persist(), merge(), remove()) trigger audits on flush().
   • No manual annotations or configuration needed for most entities.

2. Excluding Entities: Use entities config to exclude specific entities:

   # config/packages/data_dog_audit.yaml
   data_dog_audit:
       entities:
           exclude:
               - 'App\Entity\UnimportantEntity'
   

3. Customizing Audit Fields: Extend the AuditEntry entity (e.g., add ip_address):

   // src/Entity/AuditEntry.php
   use DataDog\AuditBundle\Entity\AuditEntry as BaseAuditEntry;
   
   class AuditEntry extends BaseAuditEntry {
       /**
        * @ORM\Column(type="string", nullable=true)
        */
       private $ipAddress;
   }
   

4. Linking Users to Audits: Ensure TokenStorage is configured (e.g., Symfony’s security.token_storage). The bundle auto-links the current user to audits.

5. Querying Audits: Use Doctrine queries to filter audits:

   $audits = $em->getRepository(AuditEntry::class)
       ->findBy(['entityClass' => User::class, 'action' => 'UPDATE']);
   

Integration Tips

• Transactions: Audits are inserted in the same transaction as the original operation. Rollbacks preserve data consistency.
• Performance: For high-traffic apps, consider batching audits or using async processing (e.g., Symfony Messenger).
• Testing: Mock AuditEntry in tests to avoid DB writes:

  $this->entityManager->getConnection()->getConfiguration()->setSQLLogger(null);
  

Gotchas and Tips

Pitfalls

1. Direct SQL/DQL Bypasses Audits:

   • The bundle only tracks Doctrine ORM operations. Raw SQL (e.g., entityManager->createNativeQuery()) or DQL queries are not audited.
   • Workaround: Use Doctrine repositories for all queries.

2. Circular References in Diffs:

   • Complex entity relationships (e.g., bidirectional associations) may cause infinite recursion in diff generation.
   • Fix: Exclude problematic fields from auditing via entities.ignore_fields:

     data_dog_audit:
         entities:
             ignore_fields:
                 - 'App\Entity\Post#comments' # Skip comments collection
     

3. User Linking Failures:

   • If TokenStorage is empty (e.g., API requests without auth), audits will lack user_id.
   • Tip: Set a default user or use middleware to inject context:

     $auditEntry->setUser($this->getAnonymousUser());
     

4. Schema Updates:

   • If you modify AuditEntry, run migrations after disabling the bundle temporarily:

     php bin/console config:dump --env=prod | grep -v data_dog_audit
     

Debugging

• Enable Logging: Set debug: true in config to log audit events to Symfony’s logger:

  data_dog_audit:
      debug: true
  

• Check Diffs: Audit changes field may contain malformed JSON if entity getters/setters throw exceptions. Validate with:

  json_decode($auditEntry->getChanges(), true);
  

Extension Points

1. Custom Actions: Trigger audits manually for non-ORM changes:

   $auditManager = $this->container->get('data_dog_audit.manager.audit');
   $auditManager->audit($entity, 'CUSTOM_ACTION', ['custom_data' => 'value']);
   

2. Event Listeners: Subscribe to data_dog_audit.pre_audit or data_dog_audit.post_audit events to modify audit data:

   // src/EventListener/AuditListener.php
   public function onPreAudit(AuditEvent $event) {
       $event->getAuditEntry()->setIpAddress($this->getClientIp());
   }
   

3. Async Processing: Offload audit writes to a queue (e.g., Symfony Messenger) to reduce transaction time:

   # config/packages/messenger.yaml
   framework:
       messenger:
           transports:
               audit: '%env(MESSENGER_TRANSPORT_DSN)%'
           routing:
               'DataDog\AuditBundle\Message\AuditMessage': audit