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 hasRestriction(int $role_id, string $action): bool
 186     {
 187         return $this->permissions()
 188                 ->where('role_id', '=', $role_id)
 189                 ->where($action, '=', true)
 190                 ->count() > 0;
 191     }
 192
 193     /**
 194      * Get the entity jointPermissions this is connected to.
 195      */
 196     public function jointPermissions(): MorphMany
 197     {
 198         return $this->morphMany(JointPermission::class, 'entity');
 199     }
 200
 201     /**
 202      * Get the related delete records for this entity.
 203      */
 204     public function deletions(): MorphMany
 205     {
 206         return $this->morphMany(Deletion::class, 'deletable');
 207     }
 208
 209     /**
 210      * Get the references pointing from this entity to other items.
 211      */
 212     public function referencesFrom(): MorphMany
 213     {
 214         return $this->morphMany(Reference::class, 'from');
 215     }
 216
 217     /**
 218      * Get the references pointing to this entity from other items.
 219      */
 220     public function referencesTo(): MorphMany
 221     {
 222         return $this->morphMany(Reference::class, 'to');
 223     }
 224
 225     /**
 226      * Check if this instance or class is a certain type of entity.
 227      * Examples of $type are 'page', 'book', 'chapter'.
 228      *
 229      * @deprecated Use instanceof instead.
 230      */
 231     public static function isA(string $type): bool
 232     {
 233         return static::getType() === strtolower($type);
 234     }
 235
 236     /**
 237      * Get the entity type as a simple lowercase word.
 238      */
 239     public static function getType(): string
 240     {
 241         $className = array_slice(explode('\\', static::class), -1, 1)[0];
 242
 243         return strtolower($className);
 244     }
 245
 246     /**
 247      * Gets a limited-length version of the entities name.
 248      */
 249     public function getShortName(int $length = 25): string
 250     {
 251         if (mb_strlen($this->name) <= $length) {
 252             return $this->name;
 253         }
 254
 255         return mb_substr($this->name, 0, $length - 3) . '...';
 256     }
 257
 258     /**
 259      * Get an excerpt of this entity's descriptive content to the specified length.
 260      */
 261     public function getExcerpt(int $length = 100): string
 262     {
 263         $text = $this->{$this->textField} ?? '';
 264
 265         if (mb_strlen($text) > $length) {
 266             $text = mb_substr($text, 0, $length - 3) . '...';
 267         }
 268
 269         return trim($text);
 270     }
 271
 272     /**
 273      * Get the url of this entity.
 274      */
 275     abstract public function getUrl(string $path = '/'): string;
 276
 277     /**
 278      * Get the parent entity if existing.
 279      * This is the "static" parent and does not include dynamic
 280      * relations such as shelves to books.
 281      */
 282     public function getParent(): ?self
 283     {
 284         if ($this instanceof Page) {
 285             return $this->chapter_id ? $this->chapter()->withTrashed()->first() : $this->book()->withTrashed()->first();
 286         }
 287         if ($this instanceof Chapter) {
 288             return $this->book()->withTrashed()->first();
 289         }
 290
 291         return null;
 292     }
 293
 294     /**
 295      * Rebuild the permissions for this entity.
 296      */
 297     public function rebuildPermissions()
 298     {
 299         app()->make(JointPermissionBuilder::class)->rebuildForEntity(clone $this);
 300     }
 301
 302     /**
 303      * Index the current entity for search.
 304      */
 305     public function indexForSearch()
 306     {
 307         app()->make(SearchIndex::class)->indexEntity(clone $this);
 308     }
 309
 310     /**
 311      * {@inheritdoc}
 312      */
 313     public function refreshSlug(): string
 314     {
 315         $this->slug = app()->make(SlugGenerator::class)->generate($this);
 316
 317         return $this->slug;
 318     }
 319
 320     /**
 321      * {@inheritdoc}
 322      */
 323     public function favourites(): MorphMany
 324     {
 325         return $this->morphMany(Favourite::class, 'favouritable');
 326     }
 327
 328     /**
 329      * Check if the entity is a favourite of the current user.
 330      */
 331     public function isFavourite(): bool
 332     {
 333         return $this->favourites()
 334             ->where('user_id', '=', user()->id)
 335             ->exists();
 336     }
 337
 338     /**
 339      * {@inheritdoc}
 340      */
 341     public function logDescriptor(): string
 342     {
 343         return "({$this->id}) {$this->name}";
 344     }
 345 }