feat: mark a library document for a specific purpose

src/Repository/UploadRepository.php

@@ -2,6 +2,7 @@
 
 namespace App\Repository;
 
+use App\Config\UploadToken;
 use App\Entity\Upload;
 use App\Model\DocumentFilterDto;
 use App\Repository\Traits\QueryHelperTrait;
@@ -231,4 +232,38 @@ class UploadRepository extends ServiceEntityRepository
             ->getSingleScalarResult()
         ;
     }
+
+    public function findByToken(UploadToken $token): ?Upload
+    {
+        return $this->findOneBy(['token' => $token]);
+    }
+
+    /**
+     * Frees a token slot, so the document taking it can be flushed without tripping the unique
+     * index. The update runs immediately rather than through the unit of work on purpose: both
+     * rows are Uploads, and nothing guarantees Doctrine writes the release before it writes the
+     * row that takes the token.
+     *
+     * Returns the id of the document that lost the slot, for the log.
+     */
+    public function releaseToken(UploadToken $token, Upload $takenBy): ?int
+    {
+        $holder = $this->findByToken($token);
+
+        if (null === $holder || $holder === $takenBy) {
+            return null;
+        }
+
+        $this
+            ->getEntityManager()
+            ->createQuery('UPDATE App\Entity\Upload u SET u.token = NULL WHERE u.id = :id')
+            ->setParameter('id', $holder->getId())
+            ->execute()
+        ;
+
+        // Keeps the loaded entity in step with the row that was just written.
+        $holder->setToken(null);
+
+        return $holder->getId();
+    }
 }