Entities: Moved entity description/covers to own non-model classes

Added back some interfaces.

Author: ssddanbrown

app/Entities/Controllers/BookApiController.php

@@ -124,8 +124,8 @@ protected function forJsonDisplay(Book $book): Book
 
         $book->load(['tags']);
         $book->makeVisible(['cover', 'description_html'])
-            ->setAttribute('description_html', $book->contents()->getDescriptionHtml())
-            ->setAttribute('cover', $book->contents()->cover);
+            ->setAttribute('description_html', $book->description()->getHtml())
+            ->setAttribute('cover', $book->cover()->getImage());
 
         return $book;
     }

app/Entities/Controllers/BookshelfApiController.php

@@ -118,8 +118,8 @@ protected function forJsonDisplay(Bookshelf $shelf): Bookshelf
 
         $shelf->load(['tags']);
         $shelf->makeVisible(['cover', 'description_html'])
-            ->setAttribute('description_html', $shelf->contents()->getDescriptionHtml())
-            ->setAttribute('cover', $shelf->contents()->cover);
+            ->setAttribute('description_html', $shelf->description()->getHtml())
+            ->setAttribute('cover', $shelf->cover()->getImage());
 
         return $shelf;
     }

app/Entities/Controllers/ChapterApiController.php

@@ -144,7 +144,7 @@ protected function forJsonDisplay(Chapter $chapter): Chapter
 
         $chapter->load(['tags']);
         $chapter->makeVisible('description_html');
-        $chapter->setAttribute('description_html', $chapter->contents()->getDescriptionHtml());
+        $chapter->setAttribute('description_html', $chapter->description()->getHtml());
 
         /** @var Book $book */
         $book = $chapter->book()->first();

app/Entities/Models/Book.php

@@ -2,18 +2,19 @@
 
 namespace BookStack\Entities\Models;
 
+use BookStack\Entities\Tools\EntityCover;
 use BookStack\Sorting\SortRule;
 use BookStack\Uploads\Image;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 use Illuminate\Database\Eloquent\Relations\HasMany;
-use Illuminate\Database\Eloquent\Relations\HasOne;
 use Illuminate\Support\Collection;
 
 /**
  * Class Book.
  *
  * @property string                                   $description
+ * @property string                                   $description_html
  * @property int                                      $image_id
  * @property ?int                                     $default_template_id
  * @property ?int                                     $sort_rule_id
@@ -25,14 +26,14 @@
  * @property ?Page                                    $defaultTemplate
  * @property ?SortRule                                 $sortRule
  */
-class Book extends Entity
+class Book extends Entity implements DescriptionInterface, CoverInterface
 {
     use HasFactory;
     use ContainerTrait;
 
     public float $searchFactor = 1.2;
 
-    protected $hidden = ['pivot', 'image_id', 'deleted_at', 'description_html'];
+    protected $hidden = ['pivot', 'deleted_at'];
 
     /**
      * Get the url for this book.
@@ -44,12 +45,18 @@ public function getUrl(string $path = ''): string
 
     /**
      * Returns a book cover image URL or a default URL if no cover image set.
+     * TODO - Delete
      */
     public function getCover(int $width = 440, int $height = 250): string
     {
         return $this->contents()->getCoverUrl($width, $height);
     }
 
+    public function cover(): EntityCover
+    {
+        return new EntityCover($this);
+    }
+
     /**
      * Get all pages within this book.
      * @return HasMany<Page, $this>

app/Entities/Models/Bookshelf.php

@@ -2,10 +2,15 @@
 
 namespace BookStack\Entities\Models;
 
+use BookStack\Entities\Tools\EntityCover;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 
-class Bookshelf extends Entity
+/**
+ * @property string $description
+ * @property string $description_html
+ */
+class Bookshelf extends Entity implements DescriptionInterface, CoverInterface
 {
     use HasFactory;
     use ContainerTrait;
@@ -61,4 +66,9 @@ public function appendBook(Book $book): void
         $maxOrder = $this->books()->max('order');
         $this->books()->attach($book->id, ['order' => $maxOrder + 1]);
     }
+
+    public function cover(): EntityCover
+    {
+        return new EntityCover($this);
+    }
 }

app/Entities/Models/Chapter.php

@@ -10,8 +10,10 @@
  * @property Collection<Page> $pages
  * @property ?int             $default_template_id
  * @property ?Page            $defaultTemplate
+ * @property string $description
+ * @property string $description_html
  */
-class Chapter extends BookChild
+class Chapter extends BookChild implements DescriptionInterface
 {
     use HasFactory;
     use ContainerTrait;

app/Entities/Models/ContainerTrait.php

@@ -2,13 +2,19 @@
 
 namespace BookStack\Entities\Models;
 
+use BookStack\Entities\Tools\EntityHtmlDescription;
 use Illuminate\Database\Eloquent\Relations\HasOne;
 
 /**
  * @mixin Entity
  */
 trait ContainerTrait
 {
+    public function description(): EntityHtmlDescription
+    {
+        return new EntityHtmlDescription($this);
+    }
+
     /**
      * @return HasOne<EntityContainerContents, $this>
      */

app/Entities/Models/CoverInterface.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace BookStack\Entities\Models;
+
+use BookStack\Entities\Tools\EntityCover;
+
+interface CoverInterface
+{
+    public function cover(): EntityCover;
+}

app/Entities/Models/DescriptionInterface.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace BookStack\Entities\Models;
+
+use BookStack\Entities\Tools\EntityHtmlDescription;
+
+interface DescriptionInterface
+{
+    public function description(): EntityHtmlDescription;
+}

app/Entities/Models/Entity.php

@@ -104,20 +104,35 @@ abstract class Entity extends Model implements
         'owned_by',
     ];
 
-    public function newFromBuilder($attributes = [], $connection = null): static
+    // TODO - To Remove, reduce contents/relatedData to just one of them.
+    // TODO - Update/remove existing usages of contents/relatedData
+    // TODO - Review usages of query-time update or mass insert of entity model data since those will still need to consider the multi-table layout.
+
+    /**
+     * Override the save method to also save the contents for convenience.
+     */
+    public function save(array $options = []): bool
     {
-        $entityFields = array_intersect_key($attributes, array_flip(static::$commonFields));
-        $extraFields = array_diff_key($attributes, $entityFields);
+        $contents = $this->relatedData()->firstOrNew();
+        $contentFields = $this->getContentsAttributes();
 
-        $instance = parent::newFromBuilder($entityFields, $connection);
-        $data = $instance->relatedData()->newModelInstance()->newFromBuilder($extraFields, $connection);
+        foreach ($contentFields as $key => $value) {
+            $contents->setAttribute($key, $value);
+            unset($this->attributes[$key]);
+        }
 
-        $instance->setRelation('contents', $data);
+        $result = parent::save($options);
+        $contentsResult = true;
 
-        return $instance;
-    }
+        if ($result && $contents->isDirty()) {
+            $contentsResult = $contents->save();
+            $this->touch();
+        }
 
-    // TODO - Move attribute usage to `->contents()->attr` calls
+        $this->forceFill($contentFields);
+
+        return $result && $contentsResult;
+    }
 
     /**
      * Check if this item is a container item.
@@ -187,7 +202,7 @@ public function matchesOrContains(self $entity): bool
         }
 
         if ($entity instanceof Page && $this instanceof Chapter) {
-            return $entity->contents()->chapter_id === $this->id;
+            return $entity->chapter_id === $this->id;
         }
 
         return false;
@@ -438,19 +453,36 @@ public function logDescriptor(): string
     abstract public function relatedData(): HasOne;
 
     /**
-     * Get the contents of this entity.
+     * Get the attributes that are intended for the related contents model.
+     * @return array<string, mixed>
      */
-    public function contents(): EntityContainerContents|EntityPageContents|null
+    protected function getContentsAttributes(): array
     {
-        if ($this->relationLoaded('contents')) {
-            return $this->getRelation('contents');
-        }
+        $contentFields = [];
 
-        $relatedData = $this->relatedData()->first();
-        if ($relatedData) {
-            return $relatedData;
+        foreach ($this->attributes as $key => $value) {
+            if (!in_array($key, static::$commonFields)) {
+                $contentFields[$key] = $value;
+            }
         }
 
-        return null;
+        return $contentFields;
+    }
+
+    /**
+     * Get the contents model of this entity.
+     * Should only really be used if accessing the methods of the contents model
+     * since the properties would already be part of the fetched entity model.
+     */
+    public function contents(): EntityContainerContents|EntityPageContents
+    {
+        $contentsData = $this->getContentsAttributes();
+
+        /**
+         * @var EntityContainerContents|EntityPageContents $instance
+         */
+        $instance = $this->relatedData()->newModelInstance()->newFromBuilder($contentsData, $this->getConnection());
+
+        return $instance;
     }
 }