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

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