fix(tags): race condition when creating tags (#120)

Author: HugoFara

CHANGELOG.md

@@ -67,6 +67,11 @@ ones are marked like "v1.0.0-fork".
 
 ### Fixed
 
+* **Tag Duplicate Key Error** ([#120](https://github.com/HugoFara/lwt/issues/120)):
+  Fixed rare error when updating a word with tags. When the session cache was
+  stale, saving a word with an existing tag would fail with "Duplicate entry
+  for key 'TgText'" and remove the tag from the word. Changed tag insertion
+  to use `INSERT IGNORE` to handle race conditions and stale cache gracefully.
 * **Japanese Annotations** ([#101](https://github.com/HugoFara/lwt/issues/101)):
   Fixed annotations not displaying correctly in Japanese texts. The
   `annotationToJson()` function was using an off-by-one index that didn't

src/backend/Services/TagService.php

@@ -630,7 +630,11 @@ public static function saveWordTags(int $wordId): void
         foreach ($tagList as $tag) {
             $tag = (string) $tag;
             if (!in_array($tag, $_SESSION['TAGS'])) {
-                QueryBuilder::table('tags')->insertPrepared(['TgText' => $tag]);
+                // Use INSERT IGNORE to handle race condition / stale cache (Issue #120)
+                Connection::preparedExecute(
+                    'INSERT IGNORE INTO tags (TgText) VALUES (?)',
+                    [$tag]
+                );
             }
             // Use raw SQL for INSERT...SELECT subquery
             Connection::preparedExecute(
@@ -676,7 +680,11 @@ public static function saveTextTags(int $textId, ?array $textTags = null): void
         foreach ($tagList as $tag) {
             $tag = (string) $tag;
             if (!in_array($tag, $_SESSION['TEXTTAGS'])) {
-                QueryBuilder::table('tags2')->insertPrepared(['T2Text' => $tag]);
+                // Use INSERT IGNORE to handle race condition / stale cache (Issue #120)
+                Connection::preparedExecute(
+                    'INSERT IGNORE INTO tags2 (T2Text) VALUES (?)',
+                    [$tag]
+                );
             }
             // Use raw SQL for INSERT...SELECT subquery
             Connection::preparedExecute(
@@ -719,7 +727,11 @@ public static function saveArchivedTextTags(int $textId): void
         foreach ($tagList as $tag) {
             $tag = (string) $tag;
             if (!in_array($tag, $_SESSION['TEXTTAGS'])) {
-                QueryBuilder::table('tags2')->insertPrepared(['T2Text' => $tag]);
+                // Use INSERT IGNORE to handle race condition / stale cache (Issue #120)
+                Connection::preparedExecute(
+                    'INSERT IGNORE INTO tags2 (T2Text) VALUES (?)',
+                    [$tag]
+                );
             }
             // Use raw SQL for INSERT...SELECT subquery
             Connection::preparedExecute(
@@ -1472,8 +1484,12 @@ public static function saveWordTagsFromArray(int $wordId, array $tagNames): void
             }
 
             // Create tag if it doesn't exist
+            // Use INSERT IGNORE to handle race condition / stale cache (Issue #120)
             if (!in_array($tag, $_SESSION['TAGS'])) {
-                QueryBuilder::table('tags')->insertPrepared(['TgText' => $tag]);
+                Connection::preparedExecute(
+                    'INSERT IGNORE INTO tags (TgText) VALUES (?)',
+                    [$tag]
+                );
             }
 
             // Link tag to word using raw SQL for INSERT...SELECT

tests/backend/Core/Tag/TagsTest.php

@@ -3,9 +3,12 @@
 namespace Lwt\Tests\Core\Tag;
 
 require_once __DIR__ . '/../../../../src/backend/Core/Bootstrap/EnvLoader.php';
+require_once __DIR__ . '/../../../../src/backend/Core/Http/url_utilities.php';
 
 use Lwt\Core\EnvLoader;
 use Lwt\Core\Globals;
+use Lwt\Database\Connection;
+use Lwt\Database\QueryBuilder;
 use Lwt\Services\TagService;
 use PHPUnit\Framework\TestCase;
 
@@ -750,4 +753,58 @@ public function testRemoveTagFromArchivedTextsEmptyTag(): void
         $this->assertIsString($result);
         $this->assertStringContainsString('not found', $result);
     }
+
+    /**
+     * Test saveWordTagsFromArray handles duplicate tags gracefully (Issue #120)
+     *
+     * This tests the scenario where a tag exists in the database but the
+     * session cache is stale. The function should not throw a duplicate
+     * key error.
+     */
+    public function testSaveWordTagsFromArrayHandlesDuplicateTags(): void
+    {
+        if (!Globals::getDbConnection()) {
+            $this->markTestSkipped('Database connection not available');
+        }
+
+        // Use a highly unique tag name with microseconds
+        $uniqueTagName = 'DupTest_' . uniqid('', true);
+
+        // Clean up any pre-existing tag with this name (shouldn't exist, but be safe)
+        Connection::preparedExecute(
+            'DELETE FROM tags WHERE TgText = ?',
+            [$uniqueTagName]
+        );
+
+        try {
+            // Insert the tag directly into the database
+            Connection::preparedExecute(
+                'INSERT INTO tags (TgText) VALUES (?)',
+                [$uniqueTagName]
+            );
+
+            // Clear the session cache to simulate stale cache
+            $_SESSION['TAGS'] = [];
+
+            // Try to save a word with this tag - should NOT throw exception
+            // even though the tag exists but is not in the cache
+            TagService::saveWordTagsFromArray(1, [$uniqueTagName]);
+            $this->assertTrue(true, 'saveWordTagsFromArray should handle duplicate tags gracefully');
+        } catch (\RuntimeException $e) {
+            if (strpos($e->getMessage(), 'Duplicate entry') !== false) {
+                $this->fail('Issue #120: saveWordTagsFromArray throws duplicate key error when cache is stale: ' . $e->getMessage());
+            }
+            throw $e;
+        } finally {
+            // Cleanup: remove the test tag and wordtags associations
+            Connection::preparedExecute(
+                'DELETE FROM wordtags WHERE WtTgID IN (SELECT TgID FROM tags WHERE TgText = ?)',
+                [$uniqueTagName]
+            );
+            Connection::preparedExecute(
+                'DELETE FROM tags WHERE TgText = ?',
+                [$uniqueTagName]
+            );
+        }
+    }
 }