BookStack Code Mirror - bookstack/blob - app/Entities/Models/Entity.php

   1 <?php
   2
   3 namespace BookStack\Entities\Models;
   4
   5 use BookStack\Activity\Models\Activity;
   6 use BookStack\Activity\Models\Comment;
   7 use BookStack\Activity\Models\Favouritable;
   8 use BookStack\Activity\Models\Favourite;
   9 use BookStack\Activity\Models\Loggable;
  10 use BookStack\Activity\Models\Tag;
  11 use BookStack\Activity\Models\View;
  12 use BookStack\Activity\Models\Viewable;
  13 use BookStack\Activity\Models\Watch;
  14 use BookStack\App\Model;
  15 use BookStack\App\Sluggable;
  16 use BookStack\Entities\Tools\SlugGenerator;
  17 use BookStack\Permissions\JointPermissionBuilder;
  18 use BookStack\Permissions\Models\EntityPermission;
  19 use BookStack\Permissions\Models\JointPermission;
  20 use BookStack\Permissions\PermissionApplicator;
  21 use BookStack\References\Reference;
  22 use BookStack\Search\SearchIndex;
  23 use BookStack\Search\SearchTerm;
  24 use BookStack\Users\Models\HasCreatorAndUpdater;
  25 use BookStack\Users\Models\HasOwner;
  26 use Carbon\Carbon;
  27 use Illuminate\Database\Eloquent\Builder;
  28 use Illuminate\Database\Eloquent\Collection;
  29 use Illuminate\Database\Eloquent\Relations\BelongsTo;
  30 use Illuminate\Database\Eloquent\Relations\MorphMany;
  31 use Illuminate\Database\Eloquent\SoftDeletes;
  32
  33 /**
  34  * Class Entity
  35  * The base class for book-like items such as pages, chapters & books.
  36  * This is not a database model in itself but extended.
  37  *
  38  * @property int        $id
  39  * @property string     $name
  40  * @property string     $slug
  41  * @property Carbon     $created_at
  42  * @property Carbon     $updated_at
  43  * @property Carbon     $deleted_at
  44  * @property int        $created_by
  45  * @property int        $updated_by
  46  * @property Collection $tags
  47  *
  48  * @method static Entity|Builder visible()
  49  * @method static Builder withLastView()
  50  * @method static Builder withViewCount()
  51  */
  52 abstract class Entity extends Model implements Sluggable, Favouritable, Viewable, Deletable, Loggable
  53 {
  54     use SoftDeletes;
  55     use HasCreatorAndUpdater;
  56     use HasOwner;
  57
  58     /**
  59      * @var string - Name of property where the main text content is found
  60      */
  61     public string $textField = 'description';
  62
  63     /**
  64      * @var string - Name of the property where the main HTML content is found
  65      */
  66     public string $htmlField = 'description_html';
  67
  68     /**
  69      * @var float - Multiplier for search indexing.
  70      */
  71     public float $searchFactor = 1.0;
  72
  73     /**
  74      * Get the entities that are visible to the current user.
  75      */
  76     public function scopeVisible(Builder $query): Builder
  77     {
  78         return app()->make(PermissionApplicator::class)->restrictEntityQuery($query);
  79     }
  80
  81     /**
  82      * Query scope to get the last view from the current user.
  83      */
  84     public function scopeWithLastView(Builder $query)
  85     {
  86         $viewedAtQuery = View::query()->select('updated_at')
  87             ->whereColumn('viewable_id', '=', $this->getTable() . '.id')
  88             ->where('viewable_type', '=', $this->getMorphClass())
  89             ->where('user_id', '=', user()->id)
  90             ->take(1);
  91
  92         return $query->addSelect(['last_viewed_at' => $viewedAtQuery]);
  93     }
  94
  95     /**
  96      * Query scope to get the total view count of the entities.
  97      */
  98     public function scopeWithViewCount(Builder $query)
  99     {
 100         $viewCountQuery = View::query()->selectRaw('SUM(views) as view_count')
 101             ->whereColumn('viewable_id', '=', $this->getTable() . '.id')
 102             ->where('viewable_type', '=', $this->getMorphClass())->take(1);
 103
 104         $query->addSelect(['view_count' => $viewCountQuery]);
 105     }
 106
 107     /**
 108      * Compares this entity to another given entity.
 109      * Matches by comparing class and id.
 110      */
 111     public function matches(self $entity): bool
 112     {
 113         return [get_class($this), $this->id] === [get_class($entity), $entity->id];
 114     }
 115
 116     /**
 117      * Checks if the current entity matches or contains the given.
 118      */
 119     public function matchesOrContains(self $entity): bool
 120     {
 121         if ($this->matches($entity)) {
 122             return true;
 123         }
 124
 125         if (($entity instanceof BookChild) && $this instanceof Book) {
 126             return $entity->book_id === $this->id;
 127         }
 128
 129         if ($entity instanceof Page && $this instanceof Chapter) {
 130             return $entity->chapter_id === $this->id;
 131         }
 132
 133         return false;
 134     }
 135
 136     /**
 137      * Gets the activity objects for this entity.
 138      */
 139     public function activity(): MorphMany
 140     {
 141         return $this->morphMany(Activity::class, 'loggable')
 142             ->orderBy('created_at', 'desc');
 143     }
 144
 145     /**
 146      * Get View objects for this entity.
 147      */
 148     public function views(): MorphMany
 149     {
 150         return $this->morphMany(View::class, 'viewable');
 151     }
 152
 153     /**
 154      * Get the Tag models that have been user assigned to this entity.
 155      */
 156     public function tags(): MorphMany
 157     {
 158         return $this->morphMany(Tag::class, 'entity')->orderBy('order', 'asc');
 159     }
 160
 161     /**
 162      * Get the comments for an entity.
 163      */
 164     public function comments(bool $orderByCreated = true): MorphMany
 165     {
 166         $query = $this->morphMany(Comment::class, 'entity');
 167
 168         return $orderByCreated ? $query->orderBy('created_at', 'asc') : $query;
 169     }
 170
 171     /**
 172      * Get the related search terms.
 173      */
 174     public function searchTerms(): MorphMany
 175     {
 176         return $this->morphMany(SearchTerm::class, 'entity');
 177     }
 178
 179     /**
 180      * Get this entities restrictions.
 181      */
 182     public function permissions(): MorphMany
 183     {
 184         return $this->morphMany(EntityPermission::class, 'entity');
 185     }
 186
 187     /**
 188      * Check if this entity has a specific restriction set against it.
 189      */
 190     public function hasPermissions(): bool
 191     {
 192         return $this->permissions()->count() > 0;
 193     }
 194
 195     /**
 196      * Get the entity jointPermissions this is connected to.
 197      */
 198     public function jointPermissions(): MorphMany
 199     {
 200         return $this->morphMany(JointPermission::class, 'entity');
 201     }
 202
 203     /**
 204      * Get the related delete records for this entity.
 205      */
 206     public function deletions(): MorphMany
 207     {
 208         return $this->morphMany(Deletion::class, 'deletable');
 209     }
 210
 211     /**
 212      * Get the references pointing from this entity to other items.
 213      */
 214     public function referencesFrom(): MorphMany
 215     {
 216         return $this->morphMany(Reference::class, 'from');
 217     }
 218
 219     /**
 220      * Get the references pointing to this entity from other items.
 221      */
 222     public function referencesTo(): MorphMany
 223     {
 224         return $this->morphMany(Reference::class, 'to');
 225     }
 226
 227     /**
 228      * Check if this instance or class is a certain type of entity.
 229      * Examples of $type are 'page', 'book', 'chapter'.
 230      *
 231      * @deprecated Use instanceof instead.
 232      */
 233     public static function isA(string $type): bool
 234     {
 235         return static::getType() === strtolower($type);
 236     }
 237
 238     /**
 239      * Get the entity type as a simple lowercase word.
 240      */
 241     public static function getType(): string
 242     {
 243         $className = array_slice(explode('\\', static::class), -1, 1)[0];
 244
 245         return strtolower($className);
 246     }
 247
 248     /**
 249      * Gets a limited-length version of the entities name.
 250      */
 251     public function getShortName(int $length = 25): string
 252     {
 253         if (mb_strlen($this->name) <= $length) {
 254             return $this->name;
 255         }
 256
 257         return mb_substr($this->name, 0, $length - 3) . '...';
 258     }
 259
 260     /**
 261      * Get an excerpt of this entity's descriptive content to the specified length.
 262      */
 263     public function getExcerpt(int $length = 100): string
 264     {
 265         $text = $this->{$this->textField} ?? '';
 266
 267         if (mb_strlen($text) > $length) {
 268             $text = mb_substr($text, 0, $length - 3) . '...';
 269         }
 270
 271         return trim($text);
 272     }
 273
 274     /**
 275      * Get the url of this entity.
 276      */
 277     abstract public function getUrl(string $path = '/'): string;
 278
 279     /**
 280      * Get the parent entity if existing.
 281      * This is the "static" parent and does not include dynamic
 282      * relations such as shelves to books.
 283      */
 284     public function getParent(): ?self
 285     {
 286         if ($this instanceof Page) {
 287             /** @var BelongsTo<Chapter|Book, Page>  $builder */
 288             $builder = $this->chapter_id ? $this->chapter() : $this->book();
 289             return $builder->withTrashed()->first();
 290         }
 291         if ($this instanceof Chapter) {
 292             /** @var BelongsTo<Book, Page>  $builder */
 293             $builder = $this->book();
 294             return $builder->withTrashed()->first();
 295         }
 296
 297         return null;
 298     }
 299
 300     /**
 301      * Rebuild the permissions for this entity.
 302      */
 303     public function rebuildPermissions(): void
 304     {
 305         app()->make(JointPermissionBuilder::class)->rebuildForEntity(clone $this);
 306     }
 307
 308     /**
 309      * Index the current entity for search.
 310      */
 311     public function indexForSearch(): void
 312     {
 313         app()->make(SearchIndex::class)->indexEntity(clone $this);
 314     }
 315
 316     /**
 317      * {@inheritdoc}
 318      */
 319     public function refreshSlug(): string
 320     {
 321         $this->slug = app()->make(SlugGenerator::class)->generate($this);
 322
 323         return $this->slug;
 324     }
 325
 326     /**
 327      * {@inheritdoc}
 328      */
 329     public function favourites(): MorphMany
 330     {
 331         return $this->morphMany(Favourite::class, 'favouritable');
 332     }
 333
 334     /**
 335      * Check if the entity is a favourite of the current user.
 336      */
 337     public function isFavourite(): bool
 338     {
 339         return $this->favourites()
 340             ->where('user_id', '=', user()->id)
 341             ->exists();
 342     }
 343
 344     /**
 345      * Get the related watches for this entity.
 346      */
 347     public function watches(): MorphMany
 348     {
 349         return $this->morphMany(Watch::class, 'watchable');
 350     }
 351
 352     /**
 353      * {@inheritdoc}
 354      */
 355     public function logDescriptor(): string
 356     {
 357         return "({$this->id}) {$this->name}";
 358     }
 359 }