README

English | 中文

A Symfony bundle for tracking and auditing entity changes with automatic logging of create, update, and delete operations to help maintain data integrity and compliance requirements.

Table of Contents

• Features
• Dependencies
• Required Bundles
• Installation
• Quick Start
• Configuration
  • Environment Variables
  • Service Configuration
• Advanced Usage
  • Custom Entity Requirements
  • Understanding Log Data
  • Performance Considerations
• Contributing
• License
• Changelog

Features

• Selective Tracking: Only tracks fields explicitly marked with #[TrackColumn] attribute
• Complete Audit Trail: Records entity class, ID, action type, changed data, user, IP, and request ID
• Asynchronous Logging: Non-blocking log persistence for better performance
• Automatic Cleanup: Built-in scheduled cleanup with configurable retention period
• User Context: Automatically captures user information when available
• Request Tracking: Associates changes with request IDs for better debugging

Dependencies

• PHP >= 8.1
• Symfony >= 6.4
• Doctrine ORM >= 3.0
• Doctrine Bundle >= 2.13

Required Bundles

• tourze/doctrine-async-insert-bundle: For asynchronous log insertion
• tourze/request-id-bundle: For request ID tracking
• tourze/doctrine-user-bundle: For user context tracking
• tourze/doctrine-ip-bundle: For IP address tracking
• tourze/doctrine-timestamp-bundle: For timestamp management

Installation

Install via Composer:

composer require tourze/doctrine-track-bundle

If you're not using Symfony Flex, manually register the bundle in config/bundles.php:

return [
    // ...
    Tourze\DoctrineTrackBundle\DoctrineTrackBundle::class => ['all' => true],
];

Run database migrations to create the tracking table:

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

Quick Start

1. Mark fields to track with the #[TrackColumn] attribute:

<?php

use Doctrine\ORM\Mapping as ORM;
use Tourze\DoctrineTrackBundle\Attribute\TrackColumn;

#[ORM\Entity]
class User
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[TrackColumn]  // This field will be tracked
    #[ORM\Column]
    private string $email;

    #[TrackColumn]  // This field will be tracked
    #[ORM\Column]
    private string $username;

    #[ORM\Column]   // This field will NOT be tracked
    private \DateTime $lastLogin;
    
    // ... getters and setters
}

1. Use your entities normally - tracking happens automatically:

// Create
$user = new User();
$user->setEmail('user@example.com');
$user->setUsername('john_doe');
$entityManager->persist($user);
$entityManager->flush(); // Logs: action='create', data=['email' => 'user@example.com', 'username' => 'john_doe']

// Update
$user->setEmail('newemail@example.com');
$entityManager->flush(); // Logs: action='update', data=['email' => ['old' => 'user@example.com', 'new' => 'newemail@example.com']]

// Delete
$entityManager->remove($user);
$entityManager->flush(); // Logs: action='remove', data=['email' => 'newemail@example.com', 'username' => 'john_doe']

1. Query tracking logs:

use Tourze\DoctrineTrackBundle\Entity\EntityTrackLog;

// Find all changes to a specific entity
$logs = $entityManager->getRepository(EntityTrackLog::class)->findBy([
    'objectClass' => User::class,
    'objectId' => '123'
]);

// Find all changes by a specific action
$createLogs = $entityManager->getRepository(EntityTrackLog::class)->findBy([
    'action' => 'create'
]);

Configuration

Environment Variables

# Log retention period (default: 180 days)
ENTITY_TRACK_LOG_PERSIST_DAY_NUM=180

Service Configuration

No additional configuration is required. The bundle automatically:

• Registers Doctrine event listeners
• Configures async logging service
• Sets up cleanup scheduling

Advanced Usage

Custom Entity Requirements

Your entities must have an id property as the primary key for tracking to work:

#[ORM\Entity]
class MyEntity
{
    #[ORM\Id]  // Required for tracking
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;
    
    // ... other properties
}

Understanding Log Data

The tracking logs contain:

• objectClass: Full class name of the tracked entity
• objectId: Primary key value of the entity
• action: create, update, or remove
• data: JSON containing field changes
• createdBy: User who made the change (if available)
• createdFromIp: IP address of the request
• requestId: Unique request identifier
• createdAt: Timestamp of the change

Performance Considerations

• Logs are written asynchronously to avoid blocking entity operations
• Only marked fields are tracked, reducing overhead
• Automatic cleanup prevents log table growth
• Consider indexing on objectClass and objectId for query performance

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Ensure all tests pass (./vendor/bin/phpunit)
5. Check code quality (./vendor/bin/phpstan analyse)
6. Commit your changes (git commit -am 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

License

The MIT License (MIT). Please see License File for more information.

Changelog

Please see Releases for version history and upgrade guides.