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

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