From 8c88fca2ee0d1cb58aab66a6f2873bc06d62814d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Julien=20Fastr=C3=A9?= <julien.fastre@champs-libres.coop>
Date: Thu, 26 Feb 2026 14:13:44 +0100
Subject: [PATCH] Add `TriggerAuditInterface` and `TriggerAuditService` to
 handle audit event triggering

- Introduced `TriggerAuditInterface` to define the contract for triggering audit events.
- Implemented `TriggerAuditService` to encapsulate audit event creation and persistence logic.
- Added methods to handle audit actions with metadata and translatable descriptions.
---
 .../Audit/TriggerAuditInterface.php           | 39 +++++++++++++++
 .../Audit/TriggerAuditService.php             | 50 +++++++++++++++++++
 2 files changed, 89 insertions(+)
 create mode 100644 src/Bundle/ChillMainBundle/Audit/TriggerAuditInterface.php
 create mode 100644 src/Bundle/ChillMainBundle/Audit/TriggerAuditService.php

diff --git a/src/Bundle/ChillMainBundle/Audit/TriggerAuditInterface.php b/src/Bundle/ChillMainBundle/Audit/TriggerAuditInterface.php
new file mode 100644
index 000000000..a8d05c95c
--- /dev/null
+++ b/src/Bundle/ChillMainBundle/Audit/TriggerAuditInterface.php
@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Chill is a software for social workers
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Chill\MainBundle\Audit;
+
+use Symfony\Contracts\Translation\TranslatableInterface;
+
+interface TriggerAuditInterface
+{
+    /**
+     * Handles the triggering of an audit event with the provided details.
+     *
+     * @param string                       $action      the action to be performed
+     * @param object                       $mainSubject the primary subject on which the action is performed
+     * @param array                        $subjects    an array of additional subjects related to the action
+     * @param string|TranslatableInterface $description a description of the action, which can be a string or a translatable interface
+     * @param array                        $metadata    optional metadata associated with the action
+     */
+    public function triggerAudit(string $action, object $mainSubject, array $subjects = [], string|TranslatableInterface $description = '', array $metadata = []): void;
+
+    /**
+     * Handles the invocation of an action with the provided main subject and additional subjects.
+     *
+     * @param string                       $action      the action to be performed
+     * @param object                       $mainSubject the primary subject on which the action is performed
+     * @param array                        $subjects    an array of additional subjects related to the action
+     * @param string|TranslatableInterface $description a description of the action, which can be a string or a translatable interface
+     * @param array                        $metadata    optional metadata associated with the action
+     */
+    public function __invoke(string $action, object $mainSubject, array $subjects = [], string|TranslatableInterface $description = '', array $metadata = []): void;
+}
diff --git a/src/Bundle/ChillMainBundle/Audit/TriggerAuditService.php b/src/Bundle/ChillMainBundle/Audit/TriggerAuditService.php
new file mode 100644
index 000000000..40bb9d3c2
--- /dev/null
+++ b/src/Bundle/ChillMainBundle/Audit/TriggerAuditService.php
@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Chill is a software for social workers
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace Chill\MainBundle\Audit;
+
+use Symfony\Contracts\Translation\TranslatableInterface;
+
+final readonly class TriggerAuditService implements TriggerAuditInterface
+{
+    public function __construct(
+        private AuditTrailPersister $auditTrailPersister,
+        private AuditEvent2TrailInterface $auditEvent2Trail,
+    ) {}
+
+    public function triggerAudit(
+        string $action,
+        object $mainSubject,
+        array $subjects = [],
+        string|TranslatableInterface $description = '',
+        array $metadata = [],
+    ): void {
+        $event = new AuditEvent(
+            $action,
+            $mainSubject,
+            $subjects,
+            $description,
+            $metadata,
+        );
+
+        $this->auditTrailPersister->persistAuditTrail($this->auditEvent2Trail->convertToTrail($event));
+    }
+
+    public function __invoke(
+        string $action,
+        object $mainSubject,
+        array $subjects = [],
+        string|TranslatableInterface $description = '',
+        array $metadata = [],
+    ): void {
+        $this->triggerAudit($action, $mainSubject, $subjects, $description, $metadata);
+    }
+}