From b301c543bbde75854736821a549299e1ffa8b99c Mon Sep 17 00:00:00 2001
From: Matthieu <contact@malio.fr>
Date: Fri, 19 Jun 2026 14:38:40 +0200
Subject: [PATCH] feat(shared) : add column comments catalog helper for
 migrations

---
 .../Database/ColumnCommentsCatalog.php        | 24 ++++++++++++++
 .../Database/ColumnCommentsCatalogTest.php    | 33 +++++++++++++++++++
 2 files changed, 57 insertions(+)
 create mode 100644 src/Shared/Infrastructure/Database/ColumnCommentsCatalog.php
 create mode 100644 tests/Unit/Shared/Database/ColumnCommentsCatalogTest.php

diff --git a/src/Shared/Infrastructure/Database/ColumnCommentsCatalog.php b/src/Shared/Infrastructure/Database/ColumnCommentsCatalog.php
new file mode 100644
index 0000000..16d070e
--- /dev/null
+++ b/src/Shared/Infrastructure/Database/ColumnCommentsCatalog.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Shared\Infrastructure\Database;
+
+final class ColumnCommentsCatalog
+{
+    /**
+     * SQL `COMMENT ON COLUMN` statements for the 4 standard Timestampable/Blamable columns.
+     * Call from a migration: foreach (...) { $this->addSql($statement); }.
+     *
+     * @return list<string>
+     */
+    public static function timestampableBlamableComments(string $table): array
+    {
+        return [
+            "COMMENT ON COLUMN {$table}.created_at IS 'Date de creation (UTC). Rempli automatiquement (Timestampable).'",
+            "COMMENT ON COLUMN {$table}.updated_at IS 'Date de derniere modification (UTC). Rempli automatiquement (Timestampable).'",
+            "COMMENT ON COLUMN {$table}.created_by IS 'Auteur de la creation (FK user, SET NULL). Rempli automatiquement (Blamable).'",
+            "COMMENT ON COLUMN {$table}.updated_by IS 'Auteur de la derniere modification (FK user, SET NULL). Rempli automatiquement (Blamable).'",
+        ];
+    }
+}
diff --git a/tests/Unit/Shared/Database/ColumnCommentsCatalogTest.php b/tests/Unit/Shared/Database/ColumnCommentsCatalogTest.php
new file mode 100644
index 0000000..bb41001
--- /dev/null
+++ b/tests/Unit/Shared/Database/ColumnCommentsCatalogTest.php
@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Unit\Shared\Database;
+
+use App\Shared\Infrastructure\Database\ColumnCommentsCatalog;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * @internal
+ */
+final class ColumnCommentsCatalogTest extends TestCase
+{
+    public function testTimestampableBlamableCommentsCoverFourColumns(): void
+    {
+        $sql = ColumnCommentsCatalog::timestampableBlamableComments('task');
+
+        self::assertCount(4, $sql);
+        self::assertSame(
+            "COMMENT ON COLUMN task.created_at IS 'Date de creation (UTC). Rempli automatiquement (Timestampable).'",
+            $sql[0],
+        );
+        self::assertStringContainsString('COMMENT ON COLUMN task.created_by IS', $sql[2]);
+    }
+
+    public function testTableNameIsInterpolatedForEveryColumn(): void
+    {
+        foreach (ColumnCommentsCatalog::timestampableBlamableComments('time_entry') as $statement) {
+            self::assertStringContainsString('COMMENT ON COLUMN time_entry.', $statement);
+        }
+    }
+}