Skip to content

NOW MANAGED ON CODEBERG

Maintenance: Finished changes to meet phpstan level 3

Dan Brown318b486e0b76
diff --git a/app/Access/Guards/AsyncExternalBaseSessionGuard.php b/app/Access/Guards/AsyncExternalBaseSessionGuard.php
index ab982a6b0..b66fbe95e 100644
--- a/app/Access/Guards/AsyncExternalBaseSessionGuard.php
+++ b/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;
}
diff --git a/app/Access/Guards/LdapSessionGuard.php b/app/Access/Guards/LdapSessionGuard.php
index bd020f70b..9455d530d 100644
--- a/app/Access/Guards/LdapSessionGuard.php
+++ b/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']);
diff --git a/app/Access/LoginService.php b/app/Access/LoginService.php
index 6607969af..76ae1938d 100644
--- a/app/Access/LoginService.php
+++ b/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,
diff --git a/app/Entities/Queries/BookQueries.php b/app/Entities/Queries/BookQueries.php
index 5ff22252c..2492f8131 100644
--- a/app/Entities/Queries/BookQueries.php
+++ b/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 = [
diff --git a/app/Entities/Queries/BookshelfQueries.php b/app/Entities/Queries/BookshelfQueries.php
index 874bc7f2f..842011a87 100644
--- a/app/Entities/Queries/BookshelfQueries.php
+++ b/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 = [
diff --git a/app/Entities/Queries/ChapterQueries.php b/app/Entities/Queries/ChapterQueries.php
index 53c5bc9d8..9bf0ff65b 100644
--- a/app/Entities/Queries/ChapterQueries.php
+++ b/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 = [
diff --git a/app/Entities/Queries/PageQueries.php b/app/Entities/Queries/PageQueries.php
index f821ee86a..ee7b201bc 100644
--- a/app/Entities/Queries/PageQueries.php
+++ b/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();
diff --git a/app/Entities/Queries/ProvidesEntityQueries.php b/app/Entities/Queries/ProvidesEntityQueries.php
index 1f8a71ae2..79fc64b3a 100644
--- a/app/Entities/Queries/ProvidesEntityQueries.php
+++ b/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;
}
diff --git a/app/Entities/Tools/PageIncludeParser.php b/app/Entities/Tools/PageIncludeParser.php
index 329a7633f..af7ed4fc6 100644
--- a/app/Entities/Tools/PageIncludeParser.php
+++ b/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
diff --git a/app/Exceptions/Handler.php b/app/Exceptions/Handler.php
index b8c3fa192..08d326ad8 100644
--- a/app/Exceptions/Handler.php
+++ b/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);
}
diff --git a/app/Permissions/EntityPermissionEvaluator.php b/app/Permissions/EntityPermissionEvaluator.php
index 98ec03306..30c97b700 100644
--- a/app/Permissions/EntityPermissionEvaluator.php
+++ b/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
{