Copying: Added reference change context tracking

Added core wiring in the cloning logic, just need to implement core
logic in the updater now.

Author: ssddanbrown

app/Entities/Tools/Cloner.php

@@ -13,37 +13,62 @@
 use BookStack\Entities\Repos\ChapterRepo;
 use BookStack\Entities\Repos\PageRepo;
 use BookStack\Permissions\Permission;
+use BookStack\References\ReferenceChangeContext;
+use BookStack\References\ReferenceUpdater;
 use BookStack\Uploads\Image;
 use BookStack\Uploads\ImageService;
 use Illuminate\Http\UploadedFile;
 
 class Cloner
 {
+    protected ReferenceChangeContext $referenceChangeContext;
+
     public function __construct(
         protected PageRepo $pageRepo,
         protected ChapterRepo $chapterRepo,
         protected BookRepo $bookRepo,
         protected ImageService $imageService,
+        protected ReferenceUpdater $referenceUpdater,
     ) {
+        $this->referenceChangeContext = new ReferenceChangeContext();
     }
 
     /**
      * Clone the given page into the given parent using the provided name.
      */
     public function clonePage(Page $original, Entity $parent, string $newName): Page
+    {
+        $context = $this->newReferenceChangeContext();
+        $page = $this->createPageClone($original, $parent, $newName);
+        $this->referenceUpdater->changeReferencesUsingContext($context);
+        return $page;
+    }
+
+    protected function createPageClone(Page $original, Entity $parent, string $newName): Page
     {
         $copyPage = $this->pageRepo->getNewDraftPage($parent);
         $pageData = $this->entityToInputData($original);
         $pageData['name'] = $newName;
 
-        return $this->pageRepo->publishDraft($copyPage, $pageData);
+        $newPage = $this->pageRepo->publishDraft($copyPage, $pageData);
+        $this->referenceChangeContext->add($original, $newPage);
+
+        return $newPage;
     }
 
     /**
      * Clone the given page into the given parent using the provided name.
      * Clones all child pages.
      */
     public function cloneChapter(Chapter $original, Book $parent, string $newName): Chapter
+    {
+        $context = $this->newReferenceChangeContext();
+        $chapter = $this->createChapterClone($original, $parent, $newName);
+        $this->referenceUpdater->changeReferencesUsingContext($context);
+        return $chapter;
+    }
+
+    protected function createChapterClone(Chapter $original, Book $parent, string $newName): Chapter
     {
         $chapterDetails = $this->entityToInputData($original);
         $chapterDetails['name'] = $newName;
@@ -65,6 +90,14 @@ public function cloneChapter(Chapter $original, Book $parent, string $newName):
      * Clones all child chapters and pages.
      */
     public function cloneBook(Book $original, string $newName): Book
+    {
+        $context = $this->newReferenceChangeContext();
+        $book = $this->createBookClone($original, $newName);
+        $this->referenceUpdater->changeReferencesUsingContext($context);
+        return $book;
+    }
+
+    protected function createBookClone(Book $original, string $newName): Book
     {
         $bookDetails = $this->entityToInputData($original);
         $bookDetails['name'] = $newName;
@@ -155,4 +188,10 @@ protected function entityTagsToInputArray(Entity $entity): array
 
         return $tags;
     }
+
+    protected function newReferenceChangeContext(): ReferenceChangeContext
+    {
+        $this->referenceChangeContext = new ReferenceChangeContext();
+        return $this->referenceChangeContext;
+    }
 }

app/References/ReferenceChangeContext.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace BookStack\References;
+
+use BookStack\Entities\Models\Entity;
+
+class ReferenceChangeContext
+{
+    /**
+     * Entity pairs where the first is the old entity and the second is the new entity.
+     * @var array<array{0: Entity, 1: Entity}>
+     */
+    protected array $changes = [];
+
+    public function add(Entity $oldEntity, Entity $newEntity): void
+    {
+        $this->changes[] = [$oldEntity, $newEntity];
+    }
+}

app/References/ReferenceUpdater.php

@@ -30,6 +30,14 @@ public function updateEntityReferences(Entity $entity, string $oldLink): void
         }
     }
 
+    public function changeReferencesUsingContext(ReferenceChangeContext $context): void
+    {
+        // TODO
+
+        // We should probably have references by this point, so we could use those for efficient
+        // discovery instead of scanning each item within the context.
+    }
+
     /**
      * @return Reference[]
      */