Entities: Changed from *Data to a common "contents" system

Added smart loading from builder instances which should hydrate with
"contents()" loaded via join, while keeping the core model original.

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->containerData->getDescriptionHtml())
-            ->setAttribute('cover', $book->containerData->cover);
+            ->setAttribute('description_html', $book->contents()->getDescriptionHtml())
+            ->setAttribute('cover', $book->contents()->cover);
 
         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->containerData->getDescriptionHtml())
-            ->setAttribute('cover', $shelf->containerData->cover);
+            ->setAttribute('description_html', $shelf->contents()->getDescriptionHtml())
+            ->setAttribute('cover', $shelf->contents()->cover);
 
         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->containerData->getDescriptionHtml());
+        $chapter->setAttribute('description_html', $chapter->contents()->getDescriptionHtml());
 
         /** @var Book $book */
         $book = $chapter->book()->first();

app/Entities/Models/Book.php

@@ -4,11 +4,10 @@
 
 use BookStack\Sorting\SortRule;
 use BookStack\Uploads\Image;
-use Exception;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
-use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Relations\BelongsToMany;
 use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\Relations\HasOne;
 use Illuminate\Support\Collection;
 
 /**
@@ -29,6 +28,7 @@
 class Book extends Entity
 {
     use HasFactory;
+    use ContainerTrait;
 
     public float $searchFactor = 1.2;
 
@@ -47,7 +47,7 @@ public function getUrl(string $path = ''): string
      */
     public function getCover(int $width = 440, int $height = 250): string
     {
-        return $this->containerData->getCoverUrl($width, $height);
+        return $this->contents()->getCoverUrl($width, $height);
     }
 
     /**

app/Entities/Models/Bookshelf.php

@@ -8,6 +8,7 @@
 class Bookshelf extends Entity
 {
     use HasFactory;
+    use ContainerTrait;
 
     public float $searchFactor = 1.2;
 

app/Entities/Models/Chapter.php

@@ -2,7 +2,6 @@
 
 namespace BookStack\Entities\Models;
 
-use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Support\Collection;
@@ -15,6 +14,7 @@
 class Chapter extends BookChild
 {
     use HasFactory;
+    use ContainerTrait;
 
     public float $searchFactor = 1.2;
     protected $hidden = ['pivot', 'deleted_at', 'description_html'];

app/Entities/Models/ContainerTrait.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace BookStack\Entities\Models;
+
+use Illuminate\Database\Eloquent\Relations\HasOne;
+
+/**
+ * @mixin Entity
+ */
+trait ContainerTrait
+{
+    /**
+     * @return HasOne<EntityContainerContents, $this>
+     */
+    public function relatedData(): HasOne
+    {
+        return $this->hasOne(EntityContainerContents::class, 'entity_id', 'id')
+            ->where('entity_type', '=', $this->getMorphClass());
+    }
+
+    public function contents(): EntityContainerContents
+    {
+        $data = parent::contents();
+        if ($data instanceof EntityContainerContents) {
+            return $data;
+        }
+
+        /** @var EntityContainerContents $data */
+        $data = $this->relatedData()->newModelInstance();
+        $data->setRawAttributes([
+            'entity_id' => $this->id,
+            'entity_type' => $this->getMorphClass(),
+            'description' => '',
+            'description_html' => '',
+            'default_template_id' => null,
+            'image_id' => null,
+            'sort_rule_id' => null,
+        ]);
+
+        return $data;
+    }
+}

app/Entities/Models/Entity.php

@@ -34,7 +34,7 @@
 
 /**
  * Class Entity
- * The base class for book-like items such as pages, chapters & books.
+ * The base class for book-like items such as pages, chapters and books.
  * This is not a database model in itself but extended.
  *
  * @property int        $id
@@ -49,8 +49,6 @@
  * @property int        $owned_by
  * @property Collection $tags
  *
- * @property ?EntityContainerData $containerData
- *
  * @method static Entity|Builder visible()
  * @method static Builder withLastView()
  * @method static Builder withViewCount()
@@ -87,27 +85,48 @@ abstract class Entity extends Model implements
     protected $table = 'entities';
 
     /**
-     * Set global scopes to limit queries down to just the right type of entity.
+     * Set a custom query builder for entities.
      */
-    protected static function booted(): void
-    {
-        static::addGlobalScope('entity', new EntityScope());
-    }
+    protected static string $builder = EntityQueryBuilder::class;
+
+    protected static array $commonFields = [
+        'id',
+        'type',
+        'name',
+        'slug',
+        'book_id',
+        'priority',
+        'created_at',
+        'updated_at',
+        'deleted_at',
+        'created_by',
+        'updated_by',
+        'owned_by',
+    ];
 
-    public function shouldHaveContainerData(): bool
+    public function newFromBuilder($attributes = [], $connection = null): static
     {
-        return $this instanceof Bookshelf ||
-            $this instanceof Book ||
-            $this instanceof Chapter;
+        $entityFields = array_intersect_key($attributes, array_flip(static::$commonFields));
+        $extraFields = array_diff_key($attributes, $entityFields);
+
+        $instance = parent::newFromBuilder($entityFields, $connection);
+        $data = $instance->relatedData()->newModelInstance()->newFromBuilder($extraFields, $connection);
+
+        $instance->setRelation('contents', $data);
+
+        return $instance;
     }
 
+    // TODO - Move attribute usage to `->contents()->attr` calls
+
     /**
-     * Get the container-specific data for this item.
+     * Check if this item is a container item.
      */
-    public function containerData(): HasOne
+    public function isContainer(): bool
     {
-        return $this->hasOne(EntityContainerData::class, 'id', 'entity_id')
-            ->where('entity_type', '=', $this->getMorphClass());
+        return $this instanceof Bookshelf ||
+            $this instanceof Book ||
+            $this instanceof Chapter;
     }
 
     /**
@@ -168,7 +187,7 @@ public function matchesOrContains(self $entity): bool
         }
 
         if ($entity instanceof Page && $this instanceof Chapter) {
-            return $entity->chapter_id === $this->id;
+            return $entity->contents()->chapter_id === $this->id;
         }
 
         return false;
@@ -412,4 +431,26 @@ public function logDescriptor(): string
     {
         return "({$this->id}) {$this->name}";
     }
+
+    /**
+     * @return HasOne<EntityContainerContents|EntityPageContents, $this>
+     */
+    abstract public function relatedData(): HasOne;
+
+    /**
+     * Get the contents of this entity.
+     */
+    public function contents(): EntityContainerContents|EntityPageContents|null
+    {
+        if ($this->relationLoaded('contents')) {
+            return $this->getRelation('contents');
+        }
+
+        $relatedData = $this->relatedData()->first();
+        if ($relatedData) {
+            return $relatedData;
+        }
+
+        return null;
+    }
 }

app/Entities/Models/EntityContainerData.php renamed to app/Entities/Models/EntityContainerContents.php

@@ -17,7 +17,7 @@
  * @property ?int    $image_id
  * @property ?int    $sort_rule_id
  */
-class EntityContainerData extends Model
+class EntityContainerContents extends Model
 {
     public $timestamps = false;
 

app/Entities/Models/EntityPageData.php renamed to app/Entities/Models/EntityPageContents.php

@@ -4,7 +4,7 @@
 
 use Illuminate\Database\Eloquent\Model;
 
-class EntityPageData extends Model
+class EntityPageContents extends Model
 {
     public $timestamps = false;
 }