Scaffolding for creating Audit Logs in Symfony and Doctrine

dev-main 2024-04-22 14:17 UTC

This package is auto-updated.

Last update: 2024-05-22 14:30:44 UTC


A boilerplate/scaffolding library for audit logs in your Symfony application, persistable to your database layer.


Audit logging is the process of documenting activity within your application, with additional context such as: the responsible user/actor, the entry point to the application, the subject that was acted upon, and any other relevant domain logic for that activity. A series of audit logs is called an audit trail because it shows a sequential, chronological record of activity in your application.

Audit logs answer a simple question: who did what, to what, when and where?

If your project is more interested in a historical log of how your data changed, rather than actions or activity, perhaps try Loggable behaviour for your entities and/or documents by Doctrine Extensions.

Getting Started


  • Symfony 7
  • Doctrine persistence layer: either ORM or Mongo ODM.


This project is installed through Composer:

composer require "wedevelopnl/audit-scaffold"


This library does as much for you as it can, without knowing any of your application's domain or implementation logic.

This library could hook itself into Symfony's bundle system but any modifications it would make within Symfony's configuration and container would purely be assumptions about how your application may or may not work.

While this library provides the base entity/document to extend from, and various DTOs, Enums and Value Objects, your application must implement the following:

  • A single Entity or Document (including references to your user implementation, metadata such as table/collection name and indexes, and migration if applicable) implementing AuditEntityInterface.
  • Service container configuration.
  • Doctrine mapping configuration.
  • Translations for whatever languages your application supports.
  • and, of course, audit classes (that implement AuditLogInterface) for the things you want to audit in your application.

It is recommended that you extend from AbstractAuditEntity and AbstractAuditLog, which are provided for your convenience.

Example Usage

For a thorough explanation of the setup required to use this library with either Doctrine ORM or Mongo ODM, please refer to the tutorial.

Example Audit Log
<?php declare(strict_types=1);

namespace App\Audit\Account;

use App\Entity\AuditLog as AuditLogEntity;
use App\Entity\User;
use Symfony\Component\Security\Core\User\UserInterface;
use WeDevelop\Audit\AbstractAuditLog;
use WeDevelop\Audit\Entity\AuditEntityInterface;
use WeDevelop\Audit\Entity\Subject;
use WeDevelop\Audit\ValueObject\Context;

final readonly class UserBanned extends AbstractAuditLog
    public static function create(
        Context $context,
        User $bannedUser,
        ?\DateTimeInterface $bannedUntil = null,
    ): self {
        return new self($context, Subject::fromObject($bannedUser), new \DateTimeImmutable, [
            'bannedUntil' => $bannedUntil?->format(\DateTimeInterface::RFC3339),

    public function createEntity(): AuditEntityInterface
        return AuditLogEntity::fromAuditLog($this);

    public function getMessage(): string
        return 'user.banned';

    public function getParameters(): array
        return [];

    public function getAdditionalInfo(): iterable
        if (is_string($this->data['bannedUntil'] ?? null)) {
            yield 'until' => ['datetime' => $this->data['bannedUntil']];
        } else {
            yield 'indefinitely' => [];
Example Audit Logging
<?php declare(strict_types=1);

use App\Audit\Account\UserBanned;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
use WeDevelop\Audit\ValueObject\Context;

class AdminController extends AbstractController
    public function __construct(
        private readonly EntityManagerInterface $em,
        private readonly TokenStorageInterface $tokenStorage,
    ) {}

    #[Route('/users/{user}/ban', name: 'admin_user_ban')]
    public function banUserAction(Request $request, User $user): Response
        $form = $this->createForm(BanConfirmationForm::class);

        if ($form->isSubmitted() && $form->isValid()) {

            $auditLog = UserBanned::create(
                Context::ui($request, $this->tokenStorage->getToken()),


            return $this->redirectToRoute('admin_user_view', ['user' => $user->getId()]);

        return $this->render('admin/users/confirm-ban.twig.html', [
            'form' => $form,


Code of Conduct

This project includes and adheres to the Contributor Covenant as a Code of Conduct.


Please see the separate license file included in this repository for a full copy of the MIT license, which this project is licensed under.