Maintenance: Reached PHPstan level 2

Reworked some stuff around slugs to use interface in a better way.
Also standardised phpdoc to use @return instead of @returns

Author: ssddanbrown

app/Access/Saml2Service.php

@@ -51,7 +51,7 @@ public function login(): array
      * Returns the SAML2 request ID, and the URL to redirect the user to.
      *
      * @throws Error
-     * @returns array{url: string, id: ?string}
+     * @return array{url: string, id: ?string}
      */
     public function logout(User $user): array
     {

app/Access/SocialDriverManager.php

@@ -55,7 +55,7 @@ public function isAutoConfirmEmailEnabled(string $driver): bool
 
     /**
      * Gets the names of the active social drivers, keyed by driver id.
-     * @returns array<string, string>
+     * @return array<string, string>
      */
     public function getActive(): array
     {

app/Activity/Models/Comment.php

@@ -4,6 +4,8 @@
 
 use BookStack\App\Model;
 use BookStack\Users\Models\HasCreatorAndUpdater;
+use BookStack\Users\Models\OwnableInterface;
+use BookStack\Users\Models\User;
 use BookStack\Util\HtmlContentFilter;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
@@ -17,12 +19,10 @@
  * @property int      $local_id
  * @property string   $entity_type
  * @property int      $entity_id
- * @property int      $created_by
- * @property int      $updated_by
  * @property string   $content_ref
  * @property bool     $archived
  */
-class Comment extends Model implements Loggable
+class Comment extends Model implements Loggable, OwnableInterface
 {
     use HasFactory;
     use HasCreatorAndUpdater;
@@ -39,6 +39,7 @@ public function entity(): MorphTo
 
     /**
      * Get the parent comment this is in reply to (if existing).
+     * @return BelongsTo<Comment, Comment>
      */
     public function parent(): BelongsTo
     {

app/Activity/WatchLevels.php

@@ -36,7 +36,7 @@ class WatchLevels
 
     /**
      * Get all the possible values as an option_name => value array.
-     * @returns array<string, int>
+     * @return array<string, int>
      */
     public static function all(): array
     {
@@ -50,7 +50,7 @@ public static function all(): array
 
     /**
      * Get the watch options suited for the given entity.
-     * @returns array<string, int>
+     * @return array<string, int>
      */
     public static function allSuitedFor(Entity $entity): array
     {

app/App/Model.php

@@ -8,7 +8,7 @@ class Model extends EloquentModel
 {
     /**
      * Provides public access to get the raw attribute value from the model.
-     * Used in areas where no mutations are required but performance is critical.
+     * Used in areas where no mutations are required, but performance is critical.
      *
      * @return mixed
      */

app/App/Sluggable.php app/App/SluggableInterface.phpapp/App/Sluggable.php renamed to app/App/SluggableInterface.php

@@ -5,11 +5,8 @@
 /**
  * Assigned to models that can have slugs.
  * Must have the below properties.
- *
- * @property int    $id
- * @property string $name
  */
-interface Sluggable
+interface SluggableInterface
 {
     /**
      * Regenerate the slug for this model.

app/Entities/Controllers/RecycleBinApiController.php

@@ -6,10 +6,10 @@
 use BookStack\Entities\Models\BookChild;
 use BookStack\Entities\Models\Chapter;
 use BookStack\Entities\Models\Deletion;
+use BookStack\Entities\Models\Page;
 use BookStack\Entities\Repos\DeletionRepo;
 use BookStack\Http\ApiController;
-use Closure;
-use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Relations\HasMany;
 
 class RecycleBinApiController extends ApiController
 {
@@ -40,7 +40,7 @@ public function list()
             'updated_at',
             'deletable_type',
             'deletable_id',
-        ], [Closure::fromCallable([$this, 'listFormatter'])]);
+        ], [$this->listFormatter(...)]);
     }
 
     /**
@@ -72,7 +72,6 @@ public function destroy(DeletionRepo $deletionRepo, string $deletionId)
     protected function listFormatter(Deletion $deletion)
     {
         $deletable = $deletion->deletable;
-        $withTrashedQuery = fn (Builder $query) => $query->withTrashed();
 
         if ($deletable instanceof BookChild) {
             $parent = $deletable->getParent();
@@ -81,11 +80,19 @@ protected function listFormatter(Deletion $deletion)
         }
 
         if ($deletable instanceof Book || $deletable instanceof Chapter) {
-            $countsToLoad = ['pages' => $withTrashedQuery];
+            $countsToLoad = ['pages' => static::withTrashedQuery(...)];
             if ($deletable instanceof Book) {
-                $countsToLoad['chapters'] = $withTrashedQuery;
+                $countsToLoad['chapters'] = static::withTrashedQuery(...);
             }
             $deletable->loadCount($countsToLoad);
         }
     }
+
+    /**
+     * @param HasMany<Chapter|Page, Book|Chapter> $query
+     */
+    protected static function withTrashedQuery(HasMany $query): void
+    {
+        $query->withTrashed();
+    }
 }

app/Entities/Models/Book.php

@@ -95,6 +95,7 @@ public function sortRule(): BelongsTo
 
     /**
      * Get all pages within this book.
+     * @return HasMany<Page, $this>
      */
     public function pages(): HasMany
     {
@@ -111,7 +112,7 @@ public function directPages(): HasMany
 
     /**
      * Get all chapters within this book.
-     * @return HasMany<Chapter>
+     * @return HasMany<Chapter, $this>
      */
     public function chapters(): HasMany
     {

app/Entities/Models/Bookshelf.php

@@ -70,6 +70,7 @@ public function getBookCover(int $width = 440, int $height = 250): string
 
     /**
      * Get the cover image of the shelf.
+     * @return BelongsTo<Image, $this>
      */
     public function cover(): BelongsTo
     {

app/Entities/Models/Chapter.php

@@ -27,7 +27,7 @@ class Chapter extends BookChild implements HtmlDescriptionInterface
     /**
      * Get the pages that this chapter contains.
      *
-     * @return HasMany<Page>
+     * @return HasMany<Page, $this>
      */
     public function pages(string $dir = 'ASC'): HasMany
     {
@@ -60,7 +60,7 @@ public function defaultTemplate(): BelongsTo
 
     /**
      * Get the visible pages in this chapter.
-     * @returns Collection<Page>
+     * @return Collection<Page>
      */
     public function getVisiblePages(): Collection
     {