feat: mark a library document for a specific purpose

tests/Repository/UploadRepositoryTokenTest.php

@@ -0,0 +1,90 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests\Repository;
+
+use App\Config\UploadToken;
+use App\Entity\Upload;
+use App\Repository\UploadRepository;
+use Doctrine\ORM\EntityManagerInterface;
+use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
+
+/**
+ * The token column is unique, so taking a slot from another document has to free it first - and
+ * both rows are Uploads, which means nothing guarantees Doctrine writes the release before the
+ * row that takes it. A single flush would trip the index; these tests pin that it does not.
+ */
+class UploadRepositoryTokenTest extends KernelTestCase
+{
+    private EntityManagerInterface $entityManager;
+
+    private UploadRepository $repository;
+
+    protected function setUp(): void
+    {
+        self::bootKernel();
+
+        $this->entityManager = self::getContainer()->get(EntityManagerInterface::class);
+        $this->repository = self::getContainer()->get(UploadRepository::class);
+
+        $this->entityManager->createQuery(sprintf('DELETE FROM %s', Upload::class))->execute();
+    }
+
+    public function testADocumentIsFoundByItsToken(): void
+    {
+        $document = $this->document('handout.pdf')->setToken(UploadToken::APPLICATION_FORM_HANDOUT);
+        $this->entityManager->flush();
+
+        $this->assertSame($document, $this->repository->findByToken(UploadToken::APPLICATION_FORM_HANDOUT));
+    }
+
+    public function testNothingIsFoundWhileNoDocumentHoldsTheToken(): void
+    {
+        $this->document('handout.pdf');
+        $this->entityManager->flush();
+
+        $this->assertNull($this->repository->findByToken(UploadToken::APPLICATION_FORM_HANDOUT));
+    }
+
+    public function testTakingTheTokenMovesItOffThePreviousDocument(): void
+    {
+        $old = $this->document('handout-2025.pdf')->setToken(UploadToken::APPLICATION_FORM_HANDOUT);
+        $this->entityManager->flush();
+
+        $new = $this->document('handout-2026.pdf')->setToken(UploadToken::APPLICATION_FORM_HANDOUT);
+        $releasedFrom = $this->repository->releaseToken(UploadToken::APPLICATION_FORM_HANDOUT, $new);
+        $this->entityManager->flush();
+
+        $this->assertSame($old->getId(), $releasedFrom);
+        $this->assertNull($old->getToken());
+        $this->assertSame($new, $this->repository->findByToken(UploadToken::APPLICATION_FORM_HANDOUT));
+    }
+
+    public function testReleasingForTheDocumentThatAlreadyHoldsItChangesNothing(): void
+    {
+        $document = $this->document('handout.pdf')->setToken(UploadToken::APPLICATION_FORM_HANDOUT);
+        $this->entityManager->flush();
+
+        $this->assertNull($this->repository->releaseToken(UploadToken::APPLICATION_FORM_HANDOUT, $document));
+
+        $this->entityManager->flush();
+
+        $this->assertSame($document, $this->repository->findByToken(UploadToken::APPLICATION_FORM_HANDOUT));
+    }
+
+    private function document(string $filename): Upload
+    {
+        $upload = (new Upload())
+            ->setType(Upload::TYPE_DOCUMENT)
+            ->setFilename($filename)
+            ->setOriginalFilename($filename)
+            ->setMimeType('application/pdf')
+            ->setSize(1024)
+        ;
+
+        $this->entityManager->persist($upload);
+
+        return $upload;
+    }
+}