Maintenance: Finished changes to meet phpstan level 3

app/Access/Guards/AsyncExternalBaseSessionGuard.php

@@ -3,23 +3,18 @@
 namespace BookStack\Access\Guards;
 
 /**
- * Saml2 Session Guard.
+ * External Auth Session Guard.
  *
- * The saml2 login process is async in nature meaning it does not fit very well
- * into the default laravel 'Guard' auth flow. Instead most of the logic is done
- * via the Saml2 controller & Saml2Service. This class provides a safer, thin
- * version of SessionGuard.
+ * The login process for external auth (SAML2/OIDC) is async in nature, meaning it does not fit very well
+ * into the default laravel 'Guard' auth flow. Instead, most of the logic is done via the relevant
+ * controller and services. This class provides a safer, thin version of SessionGuard.
  */
 class AsyncExternalBaseSessionGuard extends ExternalBaseSessionGuard
 {
     /**
      * Validate a user's credentials.
-     *
-     * @param array $credentials
-     *
-     * @return bool
      */
-    public function validate(array $credentials = [])
+    public function validate(array $credentials = []): bool
     {
         return false;
     }
@@ -27,12 +22,9 @@ class AsyncExternalBaseSessionGuard extends ExternalBaseSessionGuard
     /**
      * Attempt to authenticate a user using the given credentials.
      *
-     * @param array $credentials
      * @param bool  $remember
-     *
-     * @return bool
      */
-    public function attempt(array $credentials = [], $remember = false)
+    public function attempt(array $credentials = [], $remember = false): bool
     {
         return false;
     }

app/Access/Guards/LdapSessionGuard.php

@@ -35,13 +35,9 @@ class LdapSessionGuard extends ExternalBaseSessionGuard
     /**
      * Validate a user's credentials.
      *
-     * @param array $credentials
-     *
      * @throws LdapException
-     *
-     * @return bool
      */
-    public function validate(array $credentials = [])
+    public function validate(array $credentials = []): bool
     {
         $userDetails = $this->ldapService->getUserDetails($credentials['username']);
 

app/Access/LoginService.php

@@ -95,7 +95,7 @@ class LoginService
     {
         $value = session()->get(self::LAST_LOGIN_ATTEMPTED_SESSION_KEY);
         if (!$value) {
-            return ['user_id' => null, 'method' => null];
+            return ['user_id' => null, 'method' => null, 'remember' => false];
         }
 
         [$id, $method, $remember, $time] = explode(':', $value);
@@ -103,18 +103,18 @@ class LoginService
         if ($time < $hourAgo) {
             $this->clearLastLoginAttempted();
 
-            return ['user_id' => null, 'method' => null];
+            return ['user_id' => null, 'method' => null, 'remember' => false];
         }
 
         return ['user_id' => $id, 'method' => $method, 'remember' => boolval($remember)];
     }
 
     /**
-     * Set the last login attempted user.
+     * Set the last login-attempted user.
      * Must be only used when credentials are correct and a login could be
-     * achieved but a secondary factor has stopped the login.
+     * achieved, but a secondary factor has stopped the login.
      */
-    protected function setLastLoginAttemptedForUser(User $user, string $method, bool $remember)
+    protected function setLastLoginAttemptedForUser(User $user, string $method, bool $remember): void
     {
         session()->put(
             self::LAST_LOGIN_ATTEMPTED_SESSION_KEY,

app/Entities/Queries/BookQueries.php

@@ -6,6 +6,9 @@ use BookStack\Entities\Models\Book;
 use BookStack\Exceptions\NotFoundException;
 use Illuminate\Database\Eloquent\Builder;
 
+/**
+ * @implements ProvidesEntityQueries<Book>
+ */
 class BookQueries implements ProvidesEntityQueries
 {
     protected static array $listAttributes = [

app/Entities/Queries/BookshelfQueries.php

@@ -6,6 +6,9 @@ use BookStack\Entities\Models\Bookshelf;
 use BookStack\Exceptions\NotFoundException;
 use Illuminate\Database\Eloquent\Builder;
 
+/**
+ * @implements ProvidesEntityQueries<Bookshelf>
+ */
 class BookshelfQueries implements ProvidesEntityQueries
 {
     protected static array $listAttributes = [

app/Entities/Queries/ChapterQueries.php

@@ -6,6 +6,9 @@ use BookStack\Entities\Models\Chapter;
 use BookStack\Exceptions\NotFoundException;
 use Illuminate\Database\Eloquent\Builder;
 
+/**
+ * @implements ProvidesEntityQueries<Chapter>
+ */
 class ChapterQueries implements ProvidesEntityQueries
 {
     protected static array $listAttributes = [

app/Entities/Queries/PageQueries.php

@@ -6,6 +6,9 @@ use BookStack\Entities\Models\Page;
 use BookStack\Exceptions\NotFoundException;
 use Illuminate\Database\Eloquent\Builder;
 
+/**
+ * @implements ProvidesEntityQueries<Page>
+ */
 class PageQueries implements ProvidesEntityQueries
 {
     protected static array $contentAttributes = [
@@ -18,6 +21,9 @@ class PageQueries implements ProvidesEntityQueries
         'template', 'text', 'created_at', 'updated_at', 'priority', 'owned_by',
     ];
 
+    /**
+     * @return Builder<Page>
+     */
     public function start(): Builder
     {
         return Page::query();

app/Entities/Queries/ProvidesEntityQueries.php

@@ -7,17 +7,20 @@ use Illuminate\Database\Eloquent\Builder;
 
 /**
  * Interface for our classes which provide common queries for our
- * entity objects. Ideally all queries for entities should run through
+ * entity objects. Ideally, all queries for entities should run through
  * these classes.
  * Any added methods should return a builder instances to allow extension
  * via building on the query, unless the method starts with 'find'
  * in which case an entity object should be returned.
  * (nullable unless it's a *OrFail method).
+ *
+ * @template TModel of Entity
  */
 interface ProvidesEntityQueries
 {
     /**
      * Start a new query for this entity type.
+     * @return Builder<TModel>
      */
     public function start(): Builder;
 
@@ -29,7 +32,7 @@ interface ProvidesEntityQueries
     /**
      * Start a query for items that are visible, with selection
      * configured for list display of this item.
-     * @return Builder<Entity>
+     * @return Builder<TModel>
      */
     public function visibleForList(): Builder;
 }

app/Entities/Tools/PageIncludeParser.php

@@ -13,8 +13,8 @@ class PageIncludeParser
     protected static string $includeTagRegex = "/{{@\s?([0-9].*?)}}/";
 
     /**
-     * Elements to clean up and remove if left empty after a parsing operation.
-     * @var DOMElement[]
+     * Nodes to clean up and remove if left empty after a parsing operation.
+     * @var DOMNode[]
      */
     protected array $toCleanup = [];
 
@@ -206,7 +206,7 @@ class PageIncludeParser
     }
 
     /**
-     * Cleanup after a parse operation.
+     * Clean up after a parse operation.
      * Removes stranded elements we may have left during the parse.
      */
     protected function cleanup(): void

app/Exceptions/Handler.php

@@ -2,7 +2,6 @@
 
 namespace BookStack\Exceptions;
 
-use Exception;
 use Illuminate\Auth\AuthenticationException;
 use Illuminate\Database\Eloquent\ModelNotFoundException;
 use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
@@ -12,6 +11,7 @@ use Illuminate\Http\Request;
 use Illuminate\Http\Response;
 use Illuminate\Validation\ValidationException;
 use Symfony\Component\ErrorHandler\Error\FatalError;
+use Symfony\Component\HttpFoundation\Response as SymfonyResponse;
 use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
 use Throwable;
 
@@ -20,7 +20,7 @@ class Handler extends ExceptionHandler
     /**
      * A list of the exception types that are not reported.
      *
-     * @var array<int, class-string<\Throwable>>
+     * @var array<int, class-string<Throwable>>
      */
     protected $dontReport = [
         NotFoundException::class,
@@ -50,11 +50,11 @@ class Handler extends ExceptionHandler
     /**
      * Report or log an exception.
      *
-     * @param \Throwable $exception
-     *
-     * @throws \Throwable
+     * @param Throwable $exception
      *
      * @return void
+     *@throws Throwable
+     *
      */
     public function report(Throwable $exception)
     {
@@ -64,12 +64,9 @@ class Handler extends ExceptionHandler
     /**
      * Render an exception into an HTTP response.
      *
-     * @param \Illuminate\Http\Request $request
-     * @param Exception                $e
-     *
-     * @return \Illuminate\Http\Response
+     * @param Request $request
      */
-    public function render($request, Throwable $e)
+    public function render($request, Throwable $e): SymfonyResponse
     {
         if ($e instanceof FatalError && str_contains($e->getMessage(), 'bytes exhausted (tried to allocate') && $this->onOutOfMemory) {
             $response = call_user_func($this->onOutOfMemory);
@@ -152,12 +149,9 @@ class Handler extends ExceptionHandler
     /**
      * Convert an authentication exception into an unauthenticated response.
      *
-     * @param \Illuminate\Http\Request                 $request
-     * @param \Illuminate\Auth\AuthenticationException $exception
-     *
-     * @return \Illuminate\Http\Response
+     * @param Request $request
      */
-    protected function unauthenticated($request, AuthenticationException $exception)
+    protected function unauthenticated($request, AuthenticationException $exception): SymfonyResponse
     {
         if ($request->expectsJson()) {
             return response()->json(['error' => 'Unauthenticated.'], 401);
@@ -169,12 +163,9 @@ class Handler extends ExceptionHandler
     /**
      * Convert a validation exception into a JSON response.
      *
-     * @param \Illuminate\Http\Request                   $request
-     * @param \Illuminate\Validation\ValidationException $exception
-     *
-     * @return \Illuminate\Http\JsonResponse
+     * @param Request $request
      */
-    protected function invalidJson($request, ValidationException $exception)
+    protected function invalidJson($request, ValidationException $exception): JsonResponse
     {
         return response()->json($exception->errors(), $exception->status);
     }

app/Permissions/EntityPermissionEvaluator.php

@@ -30,7 +30,7 @@ class EntityPermissionEvaluator
     }
 
     /**
-     * @param array<string, array<string, int>> $permitsByType
+     * @param array<string, array<int, string>> $permitsByType
      */
     protected function evaluatePermitsByType(array $permitsByType): ?int
     {
@@ -50,7 +50,7 @@ class EntityPermissionEvaluator
     /**
      * @param string[] $typeIdChain
      * @param array<string, EntityPermission[]> $permissionMapByTypeId
-     * @return array<string, array<string, int>>
+     * @return array<string, array<int, string>>
      */
     protected function collapseAndCategorisePermissions(array $typeIdChain, array $permissionMapByTypeId): array
     {