Updated version and assets for release v25.07

New WYSIWYG editor changes for July 2025

.env.example.complete

@@ -56,6 +56,7 @@ APP_PROXIES=null
 
 # Database details
 # Host can contain a port (localhost:3306) or a separate DB_PORT option can be used.
+# An ipv6 address can be used via the square bracket format ([::1]).
 DB_HOST=localhost
 DB_PORT=3306
 DB_DATABASE=database_database

.github/ISSUE_TEMPLATE/support_request.yml

@@ -42,6 +42,7 @@ body:
       label: Log Content
       description: If the issue has produced an error, provide any [BookStack or server log](https://www.bookstackapp.com/docs/admin/debugging/) content below.
       placeholder: Be sure to remove any confidential details in your logs
+      render: text
     validations:
       required: false
   - type: textarea

.github/ISSUE_TEMPLATE/z_blank_request.yml

@@ -0,0 +1,9 @@
+name: Blank Request (Maintainers Only)
+description: For maintainers only - Start a blank request
+body:
+  - type: markdown
+    attributes:
+      value: "**This blank request option is only for existing official maintainers of the project!** Please instead use a different request option. If you use this your issue will be closed off."
+  - type: textarea
+    attributes:
+      label: Description

.github/translators.txt

@@ -461,3 +461,42 @@ Yannis Karlaftis (meliseus) :: Greek
 felixxx :: German Informal
 randi (randi65535) :: Korean
 test65428 :: Greek
+zeronell :: Chinese Simplified
+julien Vinber (julienVinber) :: French
+Hyunwoo Park (oksure) :: Korean
+aram.rafeq.7 (aramrafeq2) :: Kurdish
+Raphael Moreno (RaphaelMoreno) :: Portuguese, Brazilian
+yn (user99) :: Arabic
+Pavel Zlatarov (pzlatarov) :: Bulgarian
+ingelres :: French
+mabdullah :: Arabic
+Skrabák Csaba (kekcsi) :: Hungarian
+Evert Meulie (Evert) :: Norwegian Bokmal
+Jasper Backer (jasperb) :: Dutch
+Alexandar Cavdarovski (ace.200112) :: Swedish
+구닥다리TV (yjj8353) :: Korean
+Onur Oskay (o.oskay) :: Turkish
+Sébastien Merveille (SebastienMerv) :: French
+Maxim Kouznetsov (masya.work) :: Hebrew
+neodvisnost :: Slovenian
+Soubi Agatsuma (bisouya) :: Hebrew
+Ilya Shaulov (ishaulov) :: Russian
+Konstantin Bobkov (b.konstantv) :: Russian
+Ruben Sutter (rubensutter) :: German
+jellium :: French
+Qxlkdr :: Swedish
+Hari (muhhari) :: Indonesian
+仙君御 (xjy) :: Chinese Simplified
+TapioM :: Finnish
+lingb58 :: Chinese Traditional
+Angel Pandey (angel-pandey) :: Nepali
+Supriya Shrestha (supriyashrestha) :: Nepali
+gprabhat :: Nepali
+CellCat :: Chinese Simplified
+Al Desrahim (aldesrahim) :: Indonesian
+ahmad abbaspour (deshneh.dar.diss) :: Persian
+Erjon K. (ekr) :: Albanian
+LiZerui (iamzrli) :: Chinese Traditional
+Ticker (ticker.com) :: Hebrew
+CrazyComputer :: Chinese Simplified
+Firr (FirrV) :: Russian

.github/workflows/test-migrations.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-24.04
     strategy:
       matrix:
-        php: ['8.1', '8.2', '8.3', '8.4']
+        php: ['8.2', '8.3', '8.4']
     steps:
       - uses: actions/checkout@v4
 

.github/workflows/test-php.yml

@@ -13,10 +13,10 @@ on:
 jobs:
   build:
     if: ${{ github.ref != 'refs/heads/l10n_development' }}
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
     strategy:
       matrix:
-        php: ['8.1', '8.2', '8.3', '8.4']
+        php: ['8.2', '8.3', '8.4']
     steps:
     - uses: actions/checkout@v4
 

.gitignore

@@ -32,3 +32,4 @@ webpack-stats.json
 phpstan.neon
 esbuild-meta.json
 .phpactor.json
+/*.zip

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015-2024, Dan Brown and the BookStack Project contributors.
+Copyright (c) 2015-2025, Dan Brown and the BookStack project contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

app/Access/ExternalBaseUserProvider.php

@@ -8,27 +8,15 @@ use Illuminate\Database\Eloquent\Model;
 
 class ExternalBaseUserProvider implements UserProvider
 {
-    /**
-     * The user model.
-     *
-     * @var string
-     */
-    protected $model;
-
-    /**
-     * LdapUserProvider constructor.
-     */
-    public function __construct(string $model)
-    {
-        $this->model = $model;
+    public function __construct(
+        protected string $model
+    ) {
     }
 
     /**
      * Create a new instance of the model.
-     *
-     * @return Model
      */
-    public function createModel()
+    public function createModel(): Model
     {
         $class = '\\' . ltrim($this->model, '\\');
 
@@ -37,12 +25,8 @@ class ExternalBaseUserProvider implements UserProvider
 
     /**
      * Retrieve a user by their unique identifier.
-     *
-     * @param mixed $identifier
-     *
-     * @return Authenticatable|null
      */
-    public function retrieveById($identifier)
+    public function retrieveById(mixed $identifier): ?Authenticatable
     {
         return $this->createModel()->newQuery()->find($identifier);
     }
@@ -50,12 +34,9 @@ class ExternalBaseUserProvider implements UserProvider
     /**
      * Retrieve a user by their unique identifier and "remember me" token.
      *
-     * @param mixed  $identifier
      * @param string $token
-     *
-     * @return Authenticatable|null
      */
-    public function retrieveByToken($identifier, $token)
+    public function retrieveByToken(mixed $identifier, $token): null
     {
         return null;
     }
@@ -75,12 +56,8 @@ class ExternalBaseUserProvider implements UserProvider
 
     /**
      * Retrieve a user by the given credentials.
-     *
-     * @param array $credentials
-     *
-     * @return Authenticatable|null
      */
-    public function retrieveByCredentials(array $credentials)
+    public function retrieveByCredentials(array $credentials): ?Authenticatable
     {
         // Search current user base by looking up a uid
         $model = $this->createModel();
@@ -92,15 +69,15 @@ class ExternalBaseUserProvider implements UserProvider
 
     /**
      * Validate a user against the given credentials.
-     *
-     * @param Authenticatable $user
-     * @param array           $credentials
-     *
-     * @return bool
      */
-    public function validateCredentials(Authenticatable $user, array $credentials)
+    public function validateCredentials(Authenticatable $user, array $credentials): bool
     {
         // Should be done in the guard.
         return false;
     }
+
+    public function rehashPasswordIfRequired(Authenticatable $user, #[\SensitiveParameter] array $credentials, bool $force = false)
+    {
+        // No action to perform, any passwords are external in the auth system
+    }
 }

app/Access/Ldap.php

@@ -54,7 +54,7 @@ class Ldap
      *
      * @return \LDAP\Result|array|false
      */
-    public function search($ldapConnection, string $baseDn, string $filter, array $attributes = null)
+    public function search($ldapConnection, string $baseDn, string $filter, array $attributes = [])
     {
         return ldap_search($ldapConnection, $baseDn, $filter, $attributes);
     }
@@ -66,7 +66,7 @@ class Ldap
      *
      * @return \LDAP\Result|array|false
      */
-    public function read($ldapConnection, string $baseDn, string $filter, array $attributes = null)
+    public function read($ldapConnection, string $baseDn, string $filter, array $attributes = [])
     {
         return ldap_read($ldapConnection, $baseDn, $filter, $attributes);
     }
@@ -87,7 +87,7 @@ class Ldap
      *
      * @param resource|\LDAP\Connection   $ldapConnection
      */
-    public function searchAndGetEntries($ldapConnection, string $baseDn, string $filter, array $attributes = null): array|false
+    public function searchAndGetEntries($ldapConnection, string $baseDn, string $filter, array $attributes = []): array|false
     {
         $search = $this->search($ldapConnection, $baseDn, $filter, $attributes);
 
@@ -99,7 +99,7 @@ class Ldap
      *
      * @param resource|\LDAP\Connection $ldapConnection
      */
-    public function bind($ldapConnection, string $bindRdn = null, string $bindPassword = null): bool
+    public function bind($ldapConnection, ?string $bindRdn = null, ?string $bindPassword = null): bool
     {
         return ldap_bind($ldapConnection, $bindRdn, $bindPassword);
     }

app/Access/LdapService.php

@@ -112,10 +112,14 @@ class LdapService
             return null;
         }
 
-        $userCn = $this->getUserResponseProperty($user, 'cn', null);
+        $nameDefault = $this->getUserResponseProperty($user, 'cn', null);
+        if (is_null($nameDefault)) {
+            $nameDefault = ldap_explode_dn($user['dn'], 1)[0] ?? $user['dn'];
+        }
+
         $formatted = [
             'uid'   => $this->getUserResponseProperty($user, $idAttr, $user['dn']),
-            'name'  => $this->getUserDisplayName($user, $displayNameAttrs, $userCn),
+            'name'  => $this->getUserDisplayName($user, $displayNameAttrs, $nameDefault),
             'dn'    => $user['dn'],
             'email' => $this->getUserResponseProperty($user, $emailAttr, null),
             'avatar' => $thumbnailAttr ? $this->getUserResponseProperty($user, $thumbnailAttr, null) : null,

app/Access/Oidc/OidcService.php

@@ -11,6 +11,7 @@ use BookStack\Exceptions\UserRegistrationException;
 use BookStack\Facades\Theme;
 use BookStack\Http\HttpRequestService;
 use BookStack\Theming\ThemeEvents;
+use BookStack\Uploads\UserAvatars;
 use BookStack\Users\Models\User;
 use Illuminate\Support\Facades\Cache;
 use League\OAuth2\Client\OptionProvider\HttpBasicAuthOptionProvider;
@@ -26,7 +27,8 @@ class OidcService
         protected RegistrationService $registrationService,
         protected LoginService $loginService,
         protected HttpRequestService $http,
-        protected GroupSyncService $groupService
+        protected GroupSyncService $groupService,
+        protected UserAvatars $userAvatars
     ) {
     }
 
@@ -220,6 +222,10 @@ class OidcService
             throw new OidcException($exception->getMessage());
         }
 
+        if ($this->config()['fetch_avatar'] && !$user->avatar()->exists() && $userDetails->picture) {
+            $this->userAvatars->assignToUserFromUrl($user, $userDetails->picture);
+        }
+
         if ($this->shouldSyncGroups()) {
             $detachExisting = $this->config()['remove_from_groups'];
             $this->groupService->syncUserWithFoundGroups($user, $userDetails->groups ?? [], $detachExisting);

app/Access/Oidc/OidcUserDetails.php

@@ -11,6 +11,7 @@ class OidcUserDetails
         public ?string $email = null,
         public ?string $name = null,
         public ?array $groups = null,
+        public ?string $picture = null,
     ) {
     }
 
@@ -40,15 +41,16 @@ class OidcUserDetails
         $this->email = $claims->getClaim('email') ?? $this->email;
         $this->name = static::getUserDisplayName($displayNameClaims, $claims) ?? $this->name;
         $this->groups = static::getUserGroups($groupsClaim, $claims) ?? $this->groups;
+        $this->picture = static::getPicture($claims) ?: $this->picture;
     }
 
-    protected static function getUserDisplayName(string $displayNameClaims, ProvidesClaims $token): string
+    protected static function getUserDisplayName(string $displayNameClaims, ProvidesClaims $claims): string
     {
         $displayNameClaimParts = explode('|', $displayNameClaims);
 
         $displayName = [];
         foreach ($displayNameClaimParts as $claim) {
-            $component = $token->getClaim(trim($claim)) ?? '';
+            $component = $claims->getClaim(trim($claim)) ?? '';
             if ($component !== '') {
                 $displayName[] = $component;
             }
@@ -57,13 +59,13 @@ class OidcUserDetails
         return implode(' ', $displayName);
     }
 
-    protected static function getUserGroups(string $groupsClaim, ProvidesClaims $token): ?array
+    protected static function getUserGroups(string $groupsClaim, ProvidesClaims $claims): ?array
     {
         if (empty($groupsClaim)) {
             return null;
         }
 
-        $groupsList = Arr::get($token->getAllClaims(), $groupsClaim);
+        $groupsList = Arr::get($claims->getAllClaims(), $groupsClaim);
         if (!is_array($groupsList)) {
             return null;
         }
@@ -72,4 +74,14 @@ class OidcUserDetails
             return is_string($val);
         }));
     }
+
+    protected static function getPicture(ProvidesClaims $claims): ?string
+    {
+        $picture = $claims->getClaim('picture');
+        if (is_string($picture) && str_starts_with($picture, 'http')) {
+            return $picture;
+        }
+
+        return null;
+    }
 }

app/Access/SocialDriverManager.php

@@ -92,7 +92,7 @@ class SocialDriverManager
         string $driverName,
         array $config,
         string $socialiteHandler,
-        callable $configureForRedirect = null
+        ?callable $configureForRedirect = null
     ) {
         $this->validDrivers[] = $driverName;
         config()->set('services.' . $driverName, $config);

app/Activity/ActivityType.php

@@ -71,6 +71,10 @@ class ActivityType
     const IMPORT_RUN = 'import_run';
     const IMPORT_DELETE = 'import_delete';
 
+    const SORT_RULE_CREATE = 'sort_rule_create';
+    const SORT_RULE_UPDATE = 'sort_rule_update';
+    const SORT_RULE_DELETE = 'sort_rule_delete';
+
     /**
      * Get all the possible values.
      */

app/Activity/CommentRepo.php

@@ -4,6 +4,8 @@ namespace BookStack\Activity;
 
 use BookStack\Activity\Models\Comment;
 use BookStack\Entities\Models\Entity;
+use BookStack\Exceptions\NotifyException;
+use BookStack\Exceptions\PrettyException;
 use BookStack\Facades\Activity as ActivityService;
 use BookStack\Util\HtmlDescriptionFilter;
 
@@ -20,7 +22,7 @@ class CommentRepo
     /**
      * Create a new comment on an entity.
      */
-    public function create(Entity $entity, string $html, ?int $parent_id): Comment
+    public function create(Entity $entity, string $html, ?int $parentId, string $contentRef): Comment
     {
         $userId = user()->id;
         $comment = new Comment();
@@ -29,7 +31,8 @@ class CommentRepo
         $comment->created_by = $userId;
         $comment->updated_by = $userId;
         $comment->local_id = $this->getNextLocalId($entity);
-        $comment->parent_id = $parent_id;
+        $comment->parent_id = $parentId;
+        $comment->content_ref = preg_match('/^bkmrk-(.*?):\d+:(\d*-\d*)?$/', $contentRef) === 1 ? $contentRef : '';
 
         $entity->comments()->save($comment);
         ActivityService::add(ActivityType::COMMENT_CREATE, $comment);
@@ -52,6 +55,41 @@ class CommentRepo
         return $comment;
     }
 
+
+    /**
+     * Archive an existing comment.
+     */
+    public function archive(Comment $comment): Comment
+    {
+        if ($comment->parent_id) {
+            throw new NotifyException('Only top-level comments can be archived.', '/', 400);
+        }
+
+        $comment->archived = true;
+        $comment->save();
+
+        ActivityService::add(ActivityType::COMMENT_UPDATE, $comment);
+
+        return $comment;
+    }
+
+    /**
+     * Un-archive an existing comment.
+     */
+    public function unarchive(Comment $comment): Comment
+    {
+        if ($comment->parent_id) {
+            throw new NotifyException('Only top-level comments can be un-archived.', '/', 400);
+        }
+
+        $comment->archived = false;
+        $comment->save();
+
+        ActivityService::add(ActivityType::COMMENT_UPDATE, $comment);
+
+        return $comment;
+    }
+
     /**
      * Delete a comment from the system.
      */

app/Activity/Controllers/AuditLogController.php

@@ -5,6 +5,7 @@ namespace BookStack\Activity\Controllers;
 use BookStack\Activity\ActivityType;
 use BookStack\Activity\Models\Activity;
 use BookStack\Http\Controller;
+use BookStack\Sorting\SortUrl;
 use BookStack\Util\SimpleListOptions;
 use Illuminate\Http\Request;
 
@@ -65,6 +66,7 @@ class AuditLogController extends Controller
             'filters'       => $filters,
             'listOptions'   => $listOptions,
             'activityTypes' => $types,
+            'filterSortUrl' => new SortUrl('settings/audit', array_filter($request->except('page')))
         ]);
     }
 }

app/Activity/Controllers/CommentController.php

@@ -3,6 +3,8 @@
 namespace BookStack\Activity\Controllers;
 
 use BookStack\Activity\CommentRepo;
+use BookStack\Activity\Tools\CommentTree;
+use BookStack\Activity\Tools\CommentTreeNode;
 use BookStack\Entities\Queries\PageQueries;
 use BookStack\Http\Controller;
 use Illuminate\Http\Request;
@@ -26,6 +28,7 @@ class CommentController extends Controller
         $input = $this->validate($request, [
             'html'      => ['required', 'string'],
             'parent_id' => ['nullable', 'integer'],
+            'content_ref' => ['string'],
         ]);
 
         $page = $this->pageQueries->findVisibleById($pageId);
@@ -40,14 +43,12 @@ class CommentController extends Controller
 
         // Create a new comment.
         $this->checkPermission('comment-create-all');
-        $comment = $this->commentRepo->create($page, $input['html'], $input['parent_id'] ?? null);
+        $contentRef = $input['content_ref'] ?? '';
+        $comment = $this->commentRepo->create($page, $input['html'], $input['parent_id'] ?? null, $contentRef);
 
         return view('comments.comment-branch', [
             'readOnly' => false,
-            'branch' => [
-                'comment' => $comment,
-                'children' => [],
-            ]
+            'branch' => new CommentTreeNode($comment, 0, []),
         ]);
     }
 
@@ -74,6 +75,46 @@ class CommentController extends Controller
         ]);
     }
 
+    /**
+     * Mark a comment as archived.
+     */
+    public function archive(int $id)
+    {
+        $comment = $this->commentRepo->getById($id);
+        $this->checkOwnablePermission('page-view', $comment->entity);
+        if (!userCan('comment-update', $comment) && !userCan('comment-delete', $comment)) {
+            $this->showPermissionError();
+        }
+
+        $this->commentRepo->archive($comment);
+
+        $tree = new CommentTree($comment->entity);
+        return view('comments.comment-branch', [
+            'readOnly' => false,
+            'branch' => $tree->getCommentNodeForId($id),
+        ]);
+    }
+
+    /**
+     * Unmark a comment as archived.
+     */
+    public function unarchive(int $id)
+    {
+        $comment = $this->commentRepo->getById($id);
+        $this->checkOwnablePermission('page-view', $comment->entity);
+        if (!userCan('comment-update', $comment) && !userCan('comment-delete', $comment)) {
+            $this->showPermissionError();
+        }
+
+        $this->commentRepo->unarchive($comment);
+
+        $tree = new CommentTree($comment->entity);
+        return view('comments.comment-branch', [
+            'readOnly' => false,
+            'branch' => $tree->getCommentNodeForId($id),
+        ]);
+    }
+
     /**
      * Delete a comment from the system.
      */

app/Activity/Models/Comment.php

@@ -19,6 +19,8 @@ use Illuminate\Database\Eloquent\Relations\MorphTo;
  * @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
 {
@@ -26,7 +28,6 @@ class Comment extends Model implements Loggable
     use HasCreatorAndUpdater;
 
     protected $fillable = ['parent_id'];
-    protected $appends = ['created', 'updated'];
 
     /**
      * Get the entity that this comment belongs to.
@@ -54,22 +55,6 @@ class Comment extends Model implements Loggable
         return $this->updated_at->timestamp > $this->created_at->timestamp;
     }
 
-    /**
-     * Get created date as a relative diff.
-     */
-    public function getCreatedAttribute(): string
-    {
-        return $this->created_at->diffForHumans();
-    }
-
-    /**
-     * Get updated date as a relative diff.
-     */
-    public function getUpdatedAttribute(): string
-    {
-        return $this->updated_at->diffForHumans();
-    }
-
     public function logDescriptor(): string
     {
         return "Comment #{$this->local_id} (ID: {$this->id}) for {$this->entity_type} (ID: {$this->entity_id})";

app/Activity/Models/Tag.php

@@ -12,6 +12,8 @@ use Illuminate\Database\Eloquent\Relations\MorphTo;
  * @property int    $id
  * @property string $name
  * @property string $value
+ * @property int    $entity_id
+ * @property string $entity_type
  * @property int    $order
  */
 class Tag extends Model

app/Activity/Tools/CommentTree.php

@@ -9,7 +9,7 @@ class CommentTree
 {
     /**
      * The built nested tree structure array.
-     * @var array{comment: Comment, depth: int, children: array}[]
+     * @var CommentTreeNode[]
      */
     protected array $tree;
     protected array $comments;
@@ -28,7 +28,7 @@ class CommentTree
 
     public function empty(): bool
     {
-        return count($this->tree) === 0;
+        return count($this->getActive()) === 0;
     }
 
     public function count(): int
@@ -36,9 +36,35 @@ class CommentTree
         return count($this->comments);
     }
 
-    public function get(): array
+    public function getActive(): array
     {
-        return $this->tree;
+        return array_filter($this->tree, fn (CommentTreeNode $node) => !$node->comment->archived);
+    }
+
+    public function activeThreadCount(): int
+    {
+        return count($this->getActive());
+    }
+
+    public function getArchived(): array
+    {
+        return array_filter($this->tree, fn (CommentTreeNode $node) => $node->comment->archived);
+    }
+
+    public function archivedThreadCount(): int
+    {
+        return count($this->getArchived());
+    }
+
+    public function getCommentNodeForId(int $commentId): ?CommentTreeNode
+    {
+        foreach ($this->tree as $node) {
+            if ($node->comment->id === $commentId) {
+                return $node;
+            }
+        }
+
+        return null;
     }
 
     public function canUpdateAny(): bool
@@ -54,6 +80,7 @@ class CommentTree
 
     /**
      * @param Comment[] $comments
+     * @return CommentTreeNode[]
      */
     protected function createTree(array $comments): array
     {
@@ -77,26 +104,22 @@ class CommentTree
 
         $tree = [];
         foreach ($childMap[0] ?? [] as $childId) {
-            $tree[] = $this->createTreeForId($childId, 0, $byId, $childMap);
+            $tree[] = $this->createTreeNodeForId($childId, 0, $byId, $childMap);
         }
 
         return $tree;
     }
 
-    protected function createTreeForId(int $id, int $depth, array &$byId, array &$childMap): array
+    protected function createTreeNodeForId(int $id, int $depth, array &$byId, array &$childMap): CommentTreeNode
     {
         $childIds = $childMap[$id] ?? [];
         $children = [];
 
         foreach ($childIds as $childId) {
-            $children[] = $this->createTreeForId($childId, $depth + 1, $byId, $childMap);
+            $children[] = $this->createTreeNodeForId($childId, $depth + 1, $byId, $childMap);
         }
 
-        return [
-            'comment' => $byId[$id],
-            'depth' => $depth,
-            'children' => $children,
-        ];
+        return new CommentTreeNode($byId[$id], $depth, $children);
     }
 
     protected function loadComments(): array

app/Activity/Tools/CommentTreeNode.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace BookStack\Activity\Tools;
+
+use BookStack\Activity\Models\Comment;
+
+class CommentTreeNode
+{
+    public Comment $comment;
+    public int $depth;
+
+    /**
+     * @var CommentTreeNode[]
+     */
+    public array $children;
+
+    public function __construct(Comment $comment, int $depth, array $children)
+    {
+        $this->comment = $comment;
+        $this->depth = $depth;
+        $this->children = $children;
+    }
+}

app/Activity/Tools/TagClassGenerator.php

@@ -3,17 +3,15 @@
 namespace BookStack\Activity\Tools;
 
 use BookStack\Activity\Models\Tag;
+use BookStack\Entities\Models\BookChild;
+use BookStack\Entities\Models\Entity;
+use BookStack\Entities\Models\Page;
 
 class TagClassGenerator
 {
-    protected array $tags;
-
-    /**
-     * @param Tag[] $tags
-     */
-    public function __construct(array $tags)
-    {
-        $this->tags = $tags;
+    public function __construct(
+        protected Entity $entity
+    ) {
     }
 
     /**
@@ -22,14 +20,23 @@ class TagClassGenerator
     public function generate(): array
     {
         $classes = [];
+        $tags = $this->entity->tags->all();
 
-        foreach ($this->tags as $tag) {
-            $name = $this->normalizeTagClassString($tag->name);
-            $value = $this->normalizeTagClassString($tag->value);
-            $classes[] = 'tag-name-' . $name;
-            if ($value) {
-                $classes[] = 'tag-value-' . $value;
-                $classes[] = 'tag-pair-' . $name . '-' . $value;
+        foreach ($tags as $tag) {
+             array_push($classes, ...$this->generateClassesForTag($tag));
+        }
+
+        if ($this->entity instanceof BookChild && userCan('view', $this->entity->book)) {
+            $bookTags = $this->entity->book->tags;
+            foreach ($bookTags as $bookTag) {
+                 array_push($classes, ...$this->generateClassesForTag($bookTag, 'book-'));
+            }
+        }
+
+        if ($this->entity instanceof Page && $this->entity->chapter && userCan('view', $this->entity->chapter)) {
+            $chapterTags = $this->entity->chapter->tags;
+            foreach ($chapterTags as $chapterTag) {
+                 array_push($classes, ...$this->generateClassesForTag($chapterTag, 'chapter-'));
             }
         }
 
@@ -41,6 +48,22 @@ class TagClassGenerator
         return implode(' ', $this->generate());
     }
 
+    /**
+     * @return string[]
+     */
+    protected function generateClassesForTag(Tag $tag, string $prefix = ''): array
+    {
+        $classes = [];
+        $name = $this->normalizeTagClassString($tag->name);
+        $value = $this->normalizeTagClassString($tag->value);
+        $classes[] = "{$prefix}tag-name-{$name}";
+        if ($value) {
+            $classes[] = "{$prefix}tag-value-{$value}";
+            $classes[] = "{$prefix}tag-pair-{$name}-{$value}";
+        }
+        return $classes;
+    }
+
     protected function normalizeTagClassString(string $value): string
     {
         $value = str_replace(' ', '', strtolower($value));

app/Api/ApiDocsGenerator.php

@@ -2,6 +2,7 @@
 
 namespace BookStack\Api;
 
+use BookStack\App\AppVersion;
 use BookStack\Http\ApiController;
 use Exception;
 use Illuminate\Contracts\Container\BindingResolutionException;
@@ -25,7 +26,7 @@ class ApiDocsGenerator
      */
     public static function generateConsideringCache(): Collection
     {
-        $appVersion = trim(file_get_contents(base_path('version')));
+        $appVersion = AppVersion::get();
         $cacheKey = 'api-docs::' . $appVersion;
         $isProduction = config('app.env') === 'production';
         $cacheVal = $isProduction ? Cache::get($cacheKey) : null;

app/App/AppVersion.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace BookStack\App;
+
+class AppVersion
+{
+    protected static string $version = '';
+
+    /**
+     * Get the application's version number from its top-level `version` text file.
+     */
+    public static function get(): string
+    {
+        if (!empty(static::$version)) {
+            return static::$version;
+        }
+
+        $versionFile = base_path('version');
+        $version = trim(file_get_contents($versionFile));
+        static::$version = $version;
+
+        return $version;
+    }
+}

app/App/Providers/EventServiceProvider.php

@@ -42,4 +42,12 @@ class EventServiceProvider extends ServiceProvider
     {
         return false;
     }
+
+    /**
+     * Overrides the registration of Laravel's default email verification system
+     */
+    protected function configureEmailVerification(): void
+    {
+        //
+    }
 }

app/App/Providers/RouteServiceProvider.php

@@ -85,5 +85,12 @@ class RouteServiceProvider extends ServiceProvider
         RateLimiter::for('public', function (Request $request) {
             return Limit::perMinute(10)->by($request->ip());
         });
+
+        RateLimiter::for('exports', function (Request $request) {
+            $user = user();
+            $attempts = $user->isGuest() ? 4 : 10;
+            $key = $user->isGuest() ? $request->ip() : $user->id;
+            return Limit::perMinute($attempts)->by($key);
+        });
     }
 }

app/App/SystemApiController.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace BookStack\App;
+
+use BookStack\Http\ApiController;
+use Illuminate\Http\JsonResponse;
+
+class SystemApiController extends ApiController
+{
+    /**
+     * Read details regarding the BookStack instance.
+     * Some details may be null where not set, like the app logo for example.
+     */
+    public function read(): JsonResponse
+    {
+        $logoSetting = setting('app-logo', '');
+        if ($logoSetting === 'none') {
+            $logo = null;
+        } else {
+            $logo = $logoSetting ? url($logoSetting) : url('/logo.png');
+        }
+
+        return response()->json([
+            'version' => AppVersion::get(),
+            'instance_id' => setting('instance-id'),
+            'app_name' => setting('app-name'),
+            'app_logo' => $logo,
+            'base_url' => url('/'),
+        ]);
+    }
+}

app/App/helpers.php

@@ -1,6 +1,8 @@
 <?php
 
+use BookStack\App\AppVersion;
 use BookStack\App\Model;
+use BookStack\Facades\Theme;
 use BookStack\Permissions\PermissionApplicator;
 use BookStack\Settings\SettingService;
 use BookStack\Users\Models\User;
@@ -12,12 +14,7 @@ use BookStack\Users\Models\User;
  */
 function versioned_asset(string $file = ''): string
 {
-    static $version = null;
-
-    if (is_null($version)) {
-        $versionFile = base_path('version');
-        $version = trim(file_get_contents($versionFile));
-    }
+    $version = AppVersion::get();
 
     $additional = '';
     if (config('app.env') === 'development') {
@@ -42,9 +39,9 @@ function user(): User
  * Check if the current user has a permission. If an ownable element
  * is passed in the jointPermissions are checked against that particular item.
  */
-function userCan(string $permission, Model $ownable = null): bool
+function userCan(string $permission, ?Model $ownable = null): bool
 {
-    if ($ownable === null) {
+    if (is_null($ownable)) {
         return user()->can($permission);
     }
 
@@ -70,7 +67,7 @@ function userCanOnAny(string $action, string $entityClass = ''): bool
  *
  * @return mixed|SettingService
  */
-function setting(string $key = null, $default = null)
+function setting(?string $key = null, mixed $default = null): mixed
 {
     $settingService = app()->make(SettingService::class);
 
@@ -88,43 +85,10 @@ function setting(string $key = null, $default = null)
  */
 function theme_path(string $path = ''): ?string
 {
-    $theme = config('view.theme');
-
+    $theme = Theme::getTheme();
     if (!$theme) {
         return null;
     }
 
     return base_path('themes/' . $theme . ($path ? DIRECTORY_SEPARATOR . $path : $path));
 }
-
-/**
- * Generate a URL with multiple parameters for sorting purposes.
- * Works out the logic to set the correct sorting direction
- * Discards empty parameters and allows overriding.
- */
-function sortUrl(string $path, array $data, array $overrideData = []): string
-{
-    $queryStringSections = [];
-    $queryData = array_merge($data, $overrideData);
-
-    // Change sorting direction is already sorted on current attribute
-    if (isset($overrideData['sort']) && $overrideData['sort'] === $data['sort']) {
-        $queryData['order'] = ($data['order'] === 'asc') ? 'desc' : 'asc';
-    } elseif (isset($overrideData['sort'])) {
-        $queryData['order'] = 'asc';
-    }
-
-    foreach ($queryData as $name => $value) {
-        $trimmedVal = trim($value);
-        if ($trimmedVal === '') {
-            continue;
-        }
-        $queryStringSections[] = urlencode($name) . '=' . urlencode($trimmedVal);
-    }
-
-    if (count($queryStringSections) === 0) {
-        return url($path);
-    }
-
-    return url($path . '?' . implode('&', $queryStringSections));
-}

app/Config/broadcasting.php

@@ -1,37 +0,0 @@
-<?php
-
-/**
- * Broadcasting configuration options.
- *
- * Changes to these config files are not supported by BookStack and may break upon updates.
- * Configuration should be altered via the `.env` file or environment variables.
- * Do not edit this file unless you're happy to maintain any changes yourself.
- */
-
-return [
-
-    // Default Broadcaster
-    // This option controls the default broadcaster that will be used by the
-    // framework when an event needs to be broadcast. This can be set to
-    // any of the connections defined in the "connections" array below.
-    'default' => 'null',
-
-    // Broadcast Connections
-    // Here you may define all of the broadcast connections that will be used
-    // to broadcast events to other systems or over websockets. Samples of
-    // each available type of connection are provided inside this array.
-    'connections' => [
-
-        // Default options removed since we don't use broadcasting.
-
-        'log' => [
-            'driver' => 'log',
-        ],
-
-        'null' => [
-            'driver' => 'null',
-        ],
-
-    ],
-
-];

app/Config/cache.php

@@ -35,10 +35,6 @@ return [
     // Available caches stores
     'stores' => [
 
-        'apc' => [
-            'driver' => 'apc',
-        ],
-
         'array' => [
             'driver'    => 'array',
             'serialize' => false,
@@ -49,6 +45,7 @@ return [
             'table'           => 'cache',
             'connection'      => null,
             'lock_connection' => null,
+            'lock_table'      => null,
         ],
 
         'file' => [

app/Config/database.php

@@ -40,12 +40,16 @@ if (env('REDIS_SERVERS', false)) {
 
 // MYSQL
 // Split out port from host if set
-$mysql_host = env('DB_HOST', 'localhost');
-$mysql_host_exploded = explode(':', $mysql_host);
-$mysql_port = env('DB_PORT', 3306);
-if (count($mysql_host_exploded) > 1) {
-    $mysql_host = $mysql_host_exploded[0];
-    $mysql_port = intval($mysql_host_exploded[1]);
+$mysqlHost = env('DB_HOST', 'localhost');
+$mysqlHostExploded = explode(':', $mysqlHost);
+$mysqlPort = env('DB_PORT', 3306);
+$mysqlHostIpv6 = str_starts_with($mysqlHost, '[');
+if ($mysqlHostIpv6 && str_contains($mysqlHost, ']:')) {
+    $mysqlHost = implode(':', array_slice($mysqlHostExploded, 0, -1));
+    $mysqlPort = intval(end($mysqlHostExploded));
+} else if (!$mysqlHostIpv6 && count($mysqlHostExploded) > 1) {
+    $mysqlHost = $mysqlHostExploded[0];
+    $mysqlPort = intval($mysqlHostExploded[1]);
 }
 
 return [
@@ -61,12 +65,12 @@ return [
         'mysql' => [
             'driver'         => 'mysql',
             'url'            => env('DATABASE_URL'),
-            'host'           => $mysql_host,
+            'host'           => $mysqlHost,
             'database'       => env('DB_DATABASE', 'forge'),
             'username'       => env('DB_USERNAME', 'forge'),
             'password'       => env('DB_PASSWORD', ''),
             'unix_socket'    => env('DB_SOCKET', ''),
-            'port'           => $mysql_port,
+            'port'           => $mysqlPort,
             'charset'        => 'utf8mb4',
             'collation'      => 'utf8mb4_unicode_ci',
             // Prefixes are only semi-supported and may be unstable
@@ -88,7 +92,7 @@ return [
             'database'       => 'bookstack-test',
             'username'       => env('MYSQL_USER', 'bookstack-test'),
             'password'       => env('MYSQL_PASSWORD', 'bookstack-test'),
-            'port'           => $mysql_port,
+            'port'           => $mysqlPort,
             'charset'        => 'utf8mb4',
             'collation'      => 'utf8mb4_unicode_ci',
             'prefix'         => '',

app/Config/exports.php

@@ -114,6 +114,7 @@ return [
          * @var array
          */
         'allowed_protocols' => [
+            "data://" => ["rules" => []],
             'file://'  => ['rules' => []],
             'http://'  => ['rules' => []],
             'https://' => ['rules' => []],

app/Config/filesystems.php

@@ -32,20 +32,22 @@ return [
         'local' => [
             'driver'     => 'local',
             'root'       => public_path(),
-            'visibility' => 'public',
+            'serve'      => false,
             'throw'      => true,
+            'directory_visibility' => 'public',
         ],
 
         'local_secure_attachments' => [
             'driver' => 'local',
             'root'   => storage_path('uploads/files/'),
+            'serve'  => false,
             'throw'  => true,
         ],
 
         'local_secure_images' => [
             'driver'     => 'local',
             'root'       => storage_path('uploads/images/'),
-            'visibility' => 'public',
+            'serve'      => false,
             'throw'      => true,
         ],
 

app/Config/mail.php

@@ -11,6 +11,7 @@
 // Configured mail encryption method.
 // STARTTLS should still be attempted, but tls/ssl forces TLS usage.
 $mailEncryption = env('MAIL_ENCRYPTION', null);
+$mailPort = intval(env('MAIL_PORT', 587));
 
 return [
 
@@ -33,13 +34,13 @@ return [
             'transport' => 'smtp',
             'scheme' => null,
             'host' => env('MAIL_HOST', 'smtp.mailgun.org'),
-            'port' => env('MAIL_PORT', 587),
+            'port' => $mailPort,
             'username' => env('MAIL_USERNAME'),
             'password' => env('MAIL_PASSWORD'),
             'verify_peer' => env('MAIL_VERIFY_SSL', true),
             'timeout' => null,
-            'local_domain' => env('MAIL_EHLO_DOMAIN'),
-            'tls_required' => ($mailEncryption === 'tls' || $mailEncryption === 'ssl'),
+            'local_domain' => null,
+            'require_tls' => ($mailEncryption === 'tls' || $mailEncryption === 'ssl' || $mailPort === 465),
         ],
 
         'sendmail' => [
@@ -64,12 +65,4 @@ return [
             ],
         ],
     ],
-
-    // Email markdown configuration
-    'markdown' => [
-        'theme' => 'default',
-        'paths' => [
-            resource_path('views/vendor/mail'),
-        ],
-    ],
 ];

app/Config/oidc.php

@@ -47,6 +47,12 @@ return [
     // Multiple values can be provided comma seperated.
     'additional_scopes' => env('OIDC_ADDITIONAL_SCOPES', null),
 
+    // Enable fetching of the user's avatar from the 'picture' claim on login.
+    // Will only be fetched if the user doesn't already have an avatar image assigned.
+    // This can be a security risk due to performing server-side fetching (with up to 3 redirects) of
+    // data from external URLs. Only enable if you trust the OIDC auth provider to provide safe URLs for user images.
+    'fetch_avatar' => env('OIDC_FETCH_AVATAR', false),
+
     // Group sync options
     // Enable syncing, upon login, of OIDC groups to BookStack roles
     'user_to_groups' => env('OIDC_USER_TO_GROUPS', false),

app/Config/queue.php

@@ -23,6 +23,7 @@ return [
 
         'database' => [
             'driver'       => 'database',
+            'connection'   => null,
             'table'        => 'jobs',
             'queue'        => 'default',
             'retry_after'  => 90,

app/Console/Commands/AssignSortRuleCommand.php

@@ -0,0 +1,99 @@
+<?php
+
+namespace BookStack\Console\Commands;
+
+use BookStack\Entities\Models\Book;
+use BookStack\Sorting\BookSorter;
+use BookStack\Sorting\SortRule;
+use Illuminate\Console\Command;
+
+class AssignSortRuleCommand extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'bookstack:assign-sort-rule
+                            {sort-rule=0: ID of the sort rule to apply}
+                            {--all-books : Apply to all books in the system}
+                            {--books-without-sort : Apply to only books without a sort rule already assigned}
+                            {--books-with-sort= : Apply to only books with the sort rule of given id}';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Assign a sort rule to content in the system';
+
+    /**
+     * Execute the console command.
+     */
+    public function handle(BookSorter $sorter): int
+    {
+        $sortRuleId = intval($this->argument('sort-rule')) ?? 0;
+        if ($sortRuleId === 0) {
+            return $this->listSortRules();
+        }
+
+        $rule = SortRule::query()->find($sortRuleId);
+        if ($this->option('all-books')) {
+            $query = Book::query();
+        } else if ($this->option('books-without-sort')) {
+            $query = Book::query()->whereNull('sort_rule_id');
+        } else if ($this->option('books-with-sort')) {
+            $sortId = intval($this->option('books-with-sort')) ?: 0;
+            if (!$sortId) {
+                $this->error("Provided --books-with-sort option value is invalid");
+                return 1;
+            }
+            $query = Book::query()->where('sort_rule_id', $sortId);
+        } else {
+            $this->error("No option provided to specify target. Run with the -h option to see all available options.");
+            return 1;
+        }
+
+        if (!$rule) {
+            $this->error("Sort rule of provided id {$sortRuleId} not found!");
+            return 1;
+        }
+
+        $count = $query->clone()->count();
+        $this->warn("This will apply sort rule [{$rule->id}: {$rule->name}] to {$count} book(s) and run the sort on each.");
+        $confirmed = $this->confirm("Are you sure you want to continue?");
+
+        if (!$confirmed) {
+            return 1;
+        }
+
+        $processed = 0;
+        $query->chunkById(10, function ($books) use ($rule, $sorter, $count, &$processed) {
+            $max = min($count, ($processed + 10));
+            $this->info("Applying to {$processed}-{$max} of {$count} books");
+            foreach ($books as $book) {
+                $book->sort_rule_id = $rule->id;
+                $book->save();
+                $sorter->runBookAutoSort($book);
+            }
+            $processed = $max;
+        });
+
+        $this->info("Sort applied to {$processed} book(s)!");
+
+        return 0;
+    }
+
+    protected function listSortRules(): int
+    {
+
+        $rules = SortRule::query()->orderBy('id', 'asc')->get();
+        $this->error("Sort rule ID required!");
+        $this->warn("\nAvailable sort rules:");
+        foreach ($rules as $rule) {
+            $this->info("{$rule->id}: {$rule->name}");
+        }
+
+        return 1;
+    }
+}

app/Entities/Controllers/BookController.php

@@ -18,6 +18,7 @@ use BookStack\Exceptions\NotFoundException;
 use BookStack\Facades\Activity;
 use BookStack\Http\Controller;
 use BookStack\References\ReferenceFetcher;
+use BookStack\Util\DatabaseTransaction;
 use BookStack\Util\SimpleListOptions;
 use Illuminate\Http\Request;
 use Illuminate\Validation\ValidationException;
@@ -70,7 +71,7 @@ class BookController extends Controller
     /**
      * Show the form for creating a new book.
      */
-    public function create(string $shelfSlug = null)
+    public function create(?string $shelfSlug = null)
     {
         $this->checkPermission('book-create-all');
 
@@ -93,7 +94,7 @@ class BookController extends Controller
      * @throws ImageUploadException
      * @throws ValidationException
      */
-    public function store(Request $request, string $shelfSlug = null)
+    public function store(Request $request, ?string $shelfSlug = null)
     {
         $this->checkPermission('book-create-all');
         $validated = $this->validate($request, [
@@ -263,7 +264,9 @@ class BookController extends Controller
         $this->checkPermission('bookshelf-create-all');
         $this->checkPermission('book-create-all');
 
-        $shelf = $transformer->transformBookToShelf($book);
+        $shelf = (new DatabaseTransaction(function () use ($book, $transformer) {
+            return $transformer->transformBookToShelf($book);
+        }))->run();
 
         return redirect($shelf->getUrl());
     }

app/Entities/Controllers/ChapterApiController.php

@@ -9,12 +9,11 @@ use BookStack\Entities\Repos\ChapterRepo;
 use BookStack\Exceptions\PermissionsException;
 use BookStack\Http\ApiController;
 use Exception;
-use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Http\Request;
 
 class ChapterApiController extends ApiController
 {
-    protected $rules = [
+    protected array $rules = [
         'create' => [
             'book_id'             => ['required', 'integer'],
             'name'                => ['required', 'string', 'max:255'],

app/Entities/Controllers/ChapterController.php

@@ -18,6 +18,7 @@ use BookStack\Exceptions\NotifyException;
 use BookStack\Exceptions\PermissionsException;
 use BookStack\Http\Controller;
 use BookStack\References\ReferenceFetcher;
+use BookStack\Util\DatabaseTransaction;
 use Illuminate\Http\Request;
 use Illuminate\Validation\ValidationException;
 use Throwable;
@@ -269,7 +270,9 @@ class ChapterController extends Controller
         $this->checkOwnablePermission('chapter-delete', $chapter);
         $this->checkPermission('book-create-all');
 
-        $book = $transformer->transformChapterToBook($chapter);
+        $book = (new DatabaseTransaction(function () use ($chapter, $transformer) {
+            return $transformer->transformChapterToBook($chapter);
+        }))->run();
 
         return redirect($book->getUrl());
     }

app/Entities/Controllers/PageApiController.php

@@ -12,7 +12,7 @@ use Illuminate\Http\Request;
 
 class PageApiController extends ApiController
 {
-    protected $rules = [
+    protected array $rules = [
         'create' => [
             'book_id'    => ['required_without:chapter_id', 'integer'],
             'chapter_id' => ['required_without:book_id', 'integer'],

app/Entities/Controllers/PageController.php

@@ -17,6 +17,7 @@ use BookStack\Entities\Tools\PageContent;
 use BookStack\Entities\Tools\PageEditActivity;
 use BookStack\Entities\Tools\PageEditorData;
 use BookStack\Exceptions\NotFoundException;
+use BookStack\Exceptions\NotifyException;
 use BookStack\Exceptions\PermissionsException;
 use BookStack\Http\Controller;
 use BookStack\References\ReferenceFetcher;
@@ -41,7 +42,7 @@ class PageController extends Controller
      *
      * @throws Throwable
      */
-    public function create(string $bookSlug, string $chapterSlug = null)
+    public function create(string $bookSlug, ?string $chapterSlug = null)
     {
         if ($chapterSlug) {
             $parent = $this->entityQueries->chapters->findVisibleBySlugsOrFail($bookSlug, $chapterSlug);
@@ -69,7 +70,7 @@ class PageController extends Controller
      *
      * @throws ValidationException
      */
-    public function createAsGuest(Request $request, string $bookSlug, string $chapterSlug = null)
+    public function createAsGuest(Request $request, string $bookSlug, ?string $chapterSlug = null)
     {
         $this->validate($request, [
             'name' => ['required', 'string', 'max:255'],
@@ -196,7 +197,7 @@ class PageController extends Controller
     public function edit(Request $request, string $bookSlug, string $pageSlug)
     {
         $page = $this->queries->findVisibleBySlugsOrFail($bookSlug, $pageSlug);
-        $this->checkOwnablePermission('page-update', $page);
+        $this->checkOwnablePermission('page-update', $page, $page->getUrl());
 
         $editorData = new PageEditorData($page, $this->entityQueries, $request->query('editor', ''));
         if ($editorData->getWarnings()) {

app/Entities/Controllers/PageRevisionController.php

@@ -43,7 +43,6 @@ class PageRevisionController extends Controller
             ->selectRaw("IF(markdown = '', false, true) as is_markdown")
             ->with(['page.book', 'createdBy'])
             ->reorder('id', $listOptions->getOrder())
-            ->reorder('created_at', $listOptions->getOrder())
             ->paginate(50);
 
         $this->setPageTitle(trans('entities.pages_revisions_named', ['pageName' => $page->getShortName()]));
@@ -52,6 +51,7 @@ class PageRevisionController extends Controller
             'revisions'   => $revisions,
             'page'        => $page,
             'listOptions' => $listOptions,
+            'oldestRevisionId' => $page->revisions()->min('id'),
         ]);
     }
 

app/Entities/Models/Book.php

@@ -2,6 +2,7 @@
 
 namespace BookStack\Entities\Models;
 
+use BookStack\Sorting\SortRule;
 use BookStack\Uploads\Image;
 use Exception;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
@@ -16,12 +17,14 @@ use Illuminate\Support\Collection;
  * @property string                                   $description
  * @property int                                      $image_id
  * @property ?int                                     $default_template_id
+ * @property ?int                                     $sort_rule_id
  * @property Image|null                               $cover
  * @property \Illuminate\Database\Eloquent\Collection $chapters
  * @property \Illuminate\Database\Eloquent\Collection $pages
  * @property \Illuminate\Database\Eloquent\Collection $directPages
  * @property \Illuminate\Database\Eloquent\Collection $shelves
  * @property ?Page                                    $defaultTemplate
+ * @property ?SortRule                                 $sortRule
  */
 class Book extends Entity implements HasCoverImage
 {
@@ -82,6 +85,14 @@ class Book extends Entity implements HasCoverImage
         return $this->belongsTo(Page::class, 'default_template_id');
     }
 
+    /**
+     * Get the sort set assigned to this book, if existing.
+     */
+    public function sortRule(): BelongsTo
+    {
+        return $this->belongsTo(SortRule::class);
+    }
+
     /**
      * Get all pages within this book.
      */

app/Entities/Queries/QueryPopular.php

@@ -18,7 +18,7 @@ class QueryPopular
     ) {
     }
 
-    public function run(int $count, int $page, array $filterModels = null): Collection
+    public function run(int $count, int $page, array $filterModels): Collection
     {
         $query = $this->permissions
             ->restrictEntityRelationQuery(View::query(), 'views', 'viewable_id', 'viewable_type')
@@ -26,7 +26,7 @@ class QueryPopular
             ->groupBy('viewable_id', 'viewable_type')
             ->orderBy('view_count', 'desc');
 
-        if ($filterModels) {
+        if (!empty($filterModels)) {
             $query->whereIn('viewable_type', $this->entityProvider->getMorphClasses($filterModels));
         }
 

app/Entities/Repos/BaseRepo.php

@@ -4,6 +4,7 @@ namespace BookStack\Entities\Repos;
 
 use BookStack\Activity\TagRepo;
 use BookStack\Entities\Models\Book;
+use BookStack\Entities\Models\BookChild;
 use BookStack\Entities\Models\Chapter;
 use BookStack\Entities\Models\Entity;
 use BookStack\Entities\Models\HasCoverImage;
@@ -12,6 +13,7 @@ use BookStack\Entities\Queries\PageQueries;
 use BookStack\Exceptions\ImageUploadException;
 use BookStack\References\ReferenceStore;
 use BookStack\References\ReferenceUpdater;
+use BookStack\Sorting\BookSorter;
 use BookStack\Uploads\ImageRepo;
 use BookStack\Util\HtmlDescriptionFilter;
 use Illuminate\Http\UploadedFile;
@@ -24,6 +26,7 @@ class BaseRepo
         protected ReferenceUpdater $referenceUpdater,
         protected ReferenceStore $referenceStore,
         protected PageQueries $pageQueries,
+        protected BookSorter $bookSorter,
     ) {
     }
 
@@ -74,7 +77,6 @@ class BaseRepo
             $entity->touch();
         }
 
-        $entity->rebuildPermissions();
         $entity->indexForSearch();
         $this->referenceStore->updateForEntity($entity);
 
@@ -134,6 +136,18 @@ class BaseRepo
         $entity->save();
     }
 
+    /**
+     * Sort the parent of the given entity, if any auto sort actions are set for it.
+     * Typically ran during create/update/insert events.
+     */
+    public function sortParent(Entity $entity): void
+    {
+        if ($entity instanceof BookChild) {
+            $book = $entity->book;
+            $this->bookSorter->runBookAutoSort($book);
+        }
+    }
+
     protected function updateDescription(Entity $entity, array $input): void
     {
         if (!in_array(HasHtmlDescription::class, class_uses($entity))) {

app/Entities/Repos/BookRepo.php

@@ -8,7 +8,9 @@ use BookStack\Entities\Models\Book;
 use BookStack\Entities\Tools\TrashCan;
 use BookStack\Exceptions\ImageUploadException;
 use BookStack\Facades\Activity;
+use BookStack\Sorting\SortRule;
 use BookStack\Uploads\ImageRepo;
+use BookStack\Util\DatabaseTransaction;
 use Exception;
 use Illuminate\Http\UploadedFile;
 
@@ -27,13 +29,22 @@ class BookRepo
      */
     public function create(array $input): Book
     {
-        $book = new Book();
-        $this->baseRepo->create($book, $input);
-        $this->baseRepo->updateCoverImage($book, $input['image'] ?? null);
-        $this->baseRepo->updateDefaultTemplate($book, intval($input['default_template_id'] ?? null));
-        Activity::add(ActivityType::BOOK_CREATE, $book);
+        return (new DatabaseTransaction(function () use ($input) {
+            $book = new Book();
 
-        return $book;
+            $this->baseRepo->create($book, $input);
+            $this->baseRepo->updateCoverImage($book, $input['image'] ?? null);
+            $this->baseRepo->updateDefaultTemplate($book, intval($input['default_template_id'] ?? null));
+            Activity::add(ActivityType::BOOK_CREATE, $book);
+
+            $defaultBookSortSetting = intval(setting('sorting-book-default', '0'));
+            if ($defaultBookSortSetting && SortRule::query()->find($defaultBookSortSetting)) {
+                $book->sort_rule_id = $defaultBookSortSetting;
+                $book->save();
+            }
+
+            return $book;
+        }))->run();
     }
 
     /**

app/Entities/Repos/BookshelfRepo.php

@@ -7,6 +7,7 @@ use BookStack\Entities\Models\Bookshelf;
 use BookStack\Entities\Queries\BookQueries;
 use BookStack\Entities\Tools\TrashCan;
 use BookStack\Facades\Activity;
+use BookStack\Util\DatabaseTransaction;
 use Exception;
 
 class BookshelfRepo
@@ -23,13 +24,14 @@ class BookshelfRepo
      */
     public function create(array $input, array $bookIds): Bookshelf
     {
-        $shelf = new Bookshelf();
-        $this->baseRepo->create($shelf, $input);
-        $this->baseRepo->updateCoverImage($shelf, $input['image'] ?? null);
-        $this->updateBooks($shelf, $bookIds);
-        Activity::add(ActivityType::BOOKSHELF_CREATE, $shelf);
-
-        return $shelf;
+        return (new DatabaseTransaction(function () use ($input, $bookIds) {
+            $shelf = new Bookshelf();
+            $this->baseRepo->create($shelf, $input);
+            $this->baseRepo->updateCoverImage($shelf, $input['image'] ?? null);
+            $this->updateBooks($shelf, $bookIds);
+            Activity::add(ActivityType::BOOKSHELF_CREATE, $shelf);
+            return $shelf;
+        }))->run();
     }
 
     /**

app/Entities/Repos/ChapterRepo.php

@@ -11,6 +11,7 @@ use BookStack\Entities\Tools\TrashCan;
 use BookStack\Exceptions\MoveOperationException;
 use BookStack\Exceptions\PermissionsException;
 use BookStack\Facades\Activity;
+use BookStack\Util\DatabaseTransaction;
 use Exception;
 
 class ChapterRepo
@@ -27,14 +28,18 @@ class ChapterRepo
      */
     public function create(array $input, Book $parentBook): Chapter
     {
-        $chapter = new Chapter();
-        $chapter->book_id = $parentBook->id;
-        $chapter->priority = (new BookContents($parentBook))->getLastPriority() + 1;
-        $this->baseRepo->create($chapter, $input);
-        $this->baseRepo->updateDefaultTemplate($chapter, intval($input['default_template_id'] ?? null));
-        Activity::add(ActivityType::CHAPTER_CREATE, $chapter);
+        return (new DatabaseTransaction(function () use ($input, $parentBook) {
+            $chapter = new Chapter();
+            $chapter->book_id = $parentBook->id;
+            $chapter->priority = (new BookContents($parentBook))->getLastPriority() + 1;
+            $this->baseRepo->create($chapter, $input);
+            $this->baseRepo->updateDefaultTemplate($chapter, intval($input['default_template_id'] ?? null));
+            Activity::add(ActivityType::CHAPTER_CREATE, $chapter);
 
-        return $chapter;
+            $this->baseRepo->sortParent($chapter);
+
+            return $chapter;
+        }))->run();
     }
 
     /**
@@ -50,6 +55,8 @@ class ChapterRepo
 
         Activity::add(ActivityType::CHAPTER_UPDATE, $chapter);
 
+        $this->baseRepo->sortParent($chapter);
+
         return $chapter;
     }
 
@@ -84,10 +91,14 @@ class ChapterRepo
             throw new PermissionsException('User does not have permission to create a chapter within the chosen book');
         }
 
-        $chapter->changeBook($parent->id);
-        $chapter->rebuildPermissions();
-        Activity::add(ActivityType::CHAPTER_MOVE, $chapter);
+        return (new DatabaseTransaction(function () use ($chapter, $parent) {
+            $chapter->changeBook($parent->id);
+            $chapter->rebuildPermissions();
+            Activity::add(ActivityType::CHAPTER_MOVE, $chapter);
 
-        return $parent;
+            $this->baseRepo->sortParent($chapter);
+
+            return $parent;
+        }))->run();
     }
 }

app/Entities/Repos/PageRepo.php

@@ -18,6 +18,7 @@ use BookStack\Exceptions\PermissionsException;
 use BookStack\Facades\Activity;
 use BookStack\References\ReferenceStore;
 use BookStack\References\ReferenceUpdater;
+use BookStack\Util\DatabaseTransaction;
 use Exception;
 
 class PageRepo
@@ -61,8 +62,10 @@ class PageRepo
             ]);
         }
 
-        $page->save();
-        $page->refresh()->rebuildPermissions();
+        (new DatabaseTransaction(function () use ($page) {
+            $page->save();
+            $page->refresh()->rebuildPermissions();
+        }))->run();
 
         return $page;
     }
@@ -72,25 +75,29 @@ class PageRepo
      */
     public function publishDraft(Page $draft, array $input): Page
     {
-        $draft->draft = false;
-        $draft->revision_count = 1;
-        $draft->priority = $this->getNewPriority($draft);
-        $this->updateTemplateStatusAndContentFromInput($draft, $input);
-        $this->baseRepo->update($draft, $input);
+        return (new DatabaseTransaction(function () use ($draft, $input) {
+            $draft->draft = false;
+            $draft->revision_count = 1;
+            $draft->priority = $this->getNewPriority($draft);
+            $this->updateTemplateStatusAndContentFromInput($draft, $input);
+            $this->baseRepo->update($draft, $input);
+            $draft->rebuildPermissions();
 
-        $summary = trim($input['summary'] ?? '') ?: trans('entities.pages_initial_revision');
-        $this->revisionRepo->storeNewForPage($draft, $summary);
-        $draft->refresh();
+            $summary = trim($input['summary'] ?? '') ?: trans('entities.pages_initial_revision');
+            $this->revisionRepo->storeNewForPage($draft, $summary);
+            $draft->refresh();
 
-        Activity::add(ActivityType::PAGE_CREATE, $draft);
+            Activity::add(ActivityType::PAGE_CREATE, $draft);
+            $this->baseRepo->sortParent($draft);
 
-        return $draft;
+            return $draft;
+        }))->run();
     }
 
     /**
      * Directly update the content for the given page from the provided input.
      * Used for direct content access in a way that performs required changes
-     * (Search index & reference regen) without performing an official update.
+     * (Search index and reference regen) without performing an official update.
      */
     public function setContentFromInput(Page $page, array $input): void
     {
@@ -115,7 +122,7 @@ class PageRepo
         $page->revision_count++;
         $page->save();
 
-        // Remove all update drafts for this user & page.
+        // Remove all update drafts for this user and page.
         $this->revisionRepo->deleteDraftsForCurrentUser($page);
 
         // Save a revision after updating
@@ -128,6 +135,7 @@ class PageRepo
         }
 
         Activity::add(ActivityType::PAGE_UPDATE, $page);
+        $this->baseRepo->sortParent($page);
 
         return $page;
     }
@@ -243,6 +251,8 @@ class PageRepo
         Activity::add(ActivityType::PAGE_RESTORE, $page);
         Activity::add(ActivityType::REVISION_RESTORE, $revision);
 
+        $this->baseRepo->sortParent($page);
+
         return $page;
     }
 
@@ -265,14 +275,18 @@ class PageRepo
             throw new PermissionsException('User does not have permission to create a page within the new parent');
         }
 
-        $page->chapter_id = ($parent instanceof Chapter) ? $parent->id : null;
-        $newBookId = ($parent instanceof Chapter) ? $parent->book->id : $parent->id;
-        $page->changeBook($newBookId);
-        $page->rebuildPermissions();
+        return (new DatabaseTransaction(function () use ($page, $parent) {
+            $page->chapter_id = ($parent instanceof Chapter) ? $parent->id : null;
+            $newBookId = ($parent instanceof Chapter) ? $parent->book->id : $parent->id;
+            $page->changeBook($newBookId);
+            $page->rebuildPermissions();
 
-        Activity::add(ActivityType::PAGE_MOVE, $page);
+            Activity::add(ActivityType::PAGE_MOVE, $page);
 
-        return $parent;
+            $this->baseRepo->sortParent($page);
+
+            return $parent;
+        }))->run();
     }
 
     /**

app/Entities/Repos/RevisionRepo.php

@@ -46,7 +46,7 @@ class RevisionRepo
     /**
      * Store a new revision in the system for the given page.
      */
-    public function storeNewForPage(Page $page, string $summary = null): PageRevision
+    public function storeNewForPage(Page $page, ?string $summary = null): PageRevision
     {
         $revision = new PageRevision();
 

app/Entities/Tools/BookContents.php

@@ -8,6 +8,8 @@ use BookStack\Entities\Models\Chapter;
 use BookStack\Entities\Models\Entity;
 use BookStack\Entities\Models\Page;
 use BookStack\Entities\Queries\EntityQueries;
+use BookStack\Sorting\BookSortMap;
+use BookStack\Sorting\BookSortMapItem;
 use Illuminate\Support\Collection;
 
 class BookContents
@@ -103,211 +105,4 @@ class BookContents
 
         return $query->where('book_id', '=', $this->book->id)->get();
     }
-
-    /**
-     * Sort the books content using the given sort map.
-     * Returns a list of books that were involved in the operation.
-     *
-     * @returns Book[]
-     */
-    public function sortUsingMap(BookSortMap $sortMap): array
-    {
-        // Load models into map
-        $modelMap = $this->loadModelsFromSortMap($sortMap);
-
-        // Sort our changes from our map to be chapters first
-        // Since they need to be process to ensure book alignment for child page changes.
-        $sortMapItems = $sortMap->all();
-        usort($sortMapItems, function (BookSortMapItem $itemA, BookSortMapItem $itemB) {
-            $aScore = $itemA->type === 'page' ? 2 : 1;
-            $bScore = $itemB->type === 'page' ? 2 : 1;
-
-            return $aScore - $bScore;
-        });
-
-        // Perform the sort
-        foreach ($sortMapItems as $item) {
-            $this->applySortUpdates($item, $modelMap);
-        }
-
-        /** @var Book[] $booksInvolved */
-        $booksInvolved = array_values(array_filter($modelMap, function (string $key) {
-            return str_starts_with($key, 'book:');
-        }, ARRAY_FILTER_USE_KEY));
-
-        // Update permissions of books involved
-        foreach ($booksInvolved as $book) {
-            $book->rebuildPermissions();
-        }
-
-        return $booksInvolved;
-    }
-
-    /**
-     * Using the given sort map item, detect changes for the related model
-     * and update it if required. Changes where permissions are lacking will
-     * be skipped and not throw an error.
-     *
-     * @param array<string, Entity> $modelMap
-     */
-    protected function applySortUpdates(BookSortMapItem $sortMapItem, array $modelMap): void
-    {
-        /** @var BookChild $model */
-        $model = $modelMap[$sortMapItem->type . ':' . $sortMapItem->id] ?? null;
-        if (!$model) {
-            return;
-        }
-
-        $priorityChanged = $model->priority !== $sortMapItem->sort;
-        $bookChanged = $model->book_id !== $sortMapItem->parentBookId;
-        $chapterChanged = ($model instanceof Page) && $model->chapter_id !== $sortMapItem->parentChapterId;
-
-        // Stop if there's no change
-        if (!$priorityChanged && !$bookChanged && !$chapterChanged) {
-            return;
-        }
-
-        $currentParentKey = 'book:' . $model->book_id;
-        if ($model instanceof Page && $model->chapter_id) {
-            $currentParentKey = 'chapter:' . $model->chapter_id;
-        }
-
-        $currentParent = $modelMap[$currentParentKey] ?? null;
-        /** @var Book $newBook */
-        $newBook = $modelMap['book:' . $sortMapItem->parentBookId] ?? null;
-        /** @var ?Chapter $newChapter */
-        $newChapter = $sortMapItem->parentChapterId ? ($modelMap['chapter:' . $sortMapItem->parentChapterId] ?? null) : null;
-
-        if (!$this->isSortChangePermissible($sortMapItem, $model, $currentParent, $newBook, $newChapter)) {
-            return;
-        }
-
-        // Action the required changes
-        if ($bookChanged) {
-            $model->changeBook($newBook->id);
-        }
-
-        if ($model instanceof Page && $chapterChanged) {
-            $model->chapter_id = $newChapter->id ?? 0;
-        }
-
-        if ($priorityChanged) {
-            $model->priority = $sortMapItem->sort;
-        }
-
-        if ($chapterChanged || $priorityChanged) {
-            $model->save();
-        }
-    }
-
-    /**
-     * Check if the current user has permissions to apply the given sorting change.
-     * Is quite complex since items can gain a different parent change. Acts as a:
-     * - Update of old parent element (Change of content/order).
-     * - Update of sorted/moved element.
-     * - Deletion of element (Relative to parent upon move).
-     * - Creation of element within parent (Upon move to new parent).
-     */
-    protected function isSortChangePermissible(BookSortMapItem $sortMapItem, BookChild $model, ?Entity $currentParent, ?Entity $newBook, ?Entity $newChapter): bool
-    {
-        // Stop if we can't see the current parent or new book.
-        if (!$currentParent || !$newBook) {
-            return false;
-        }
-
-        $hasNewParent = $newBook->id !== $model->book_id || ($model instanceof Page && $model->chapter_id !== ($sortMapItem->parentChapterId ?? 0));
-        if ($model instanceof Chapter) {
-            $hasPermission = userCan('book-update', $currentParent)
-                && userCan('book-update', $newBook)
-                && userCan('chapter-update', $model)
-                && (!$hasNewParent || userCan('chapter-create', $newBook))
-                && (!$hasNewParent || userCan('chapter-delete', $model));
-
-            if (!$hasPermission) {
-                return false;
-            }
-        }
-
-        if ($model instanceof Page) {
-            $parentPermission = ($currentParent instanceof Chapter) ? 'chapter-update' : 'book-update';
-            $hasCurrentParentPermission = userCan($parentPermission, $currentParent);
-
-            // This needs to check if there was an intended chapter location in the original sort map
-            // rather than inferring from the $newChapter since that variable may be null
-            // due to other reasons (Visibility).
-            $newParent = $sortMapItem->parentChapterId ? $newChapter : $newBook;
-            if (!$newParent) {
-                return false;
-            }
-
-            $hasPageEditPermission = userCan('page-update', $model);
-            $newParentInRightLocation = ($newParent instanceof Book || ($newParent instanceof Chapter && $newParent->book_id === $newBook->id));
-            $newParentPermission = ($newParent instanceof Chapter) ? 'chapter-update' : 'book-update';
-            $hasNewParentPermission = userCan($newParentPermission, $newParent);
-
-            $hasDeletePermissionIfMoving = (!$hasNewParent || userCan('page-delete', $model));
-            $hasCreatePermissionIfMoving = (!$hasNewParent || userCan('page-create', $newParent));
-
-            $hasPermission = $hasCurrentParentPermission
-                && $newParentInRightLocation
-                && $hasNewParentPermission
-                && $hasPageEditPermission
-                && $hasDeletePermissionIfMoving
-                && $hasCreatePermissionIfMoving;
-
-            if (!$hasPermission) {
-                return false;
-            }
-        }
-
-        return true;
-    }
-
-    /**
-     * Load models from the database into the given sort map.
-     *
-     * @return array<string, Entity>
-     */
-    protected function loadModelsFromSortMap(BookSortMap $sortMap): array
-    {
-        $modelMap = [];
-        $ids = [
-            'chapter' => [],
-            'page'    => [],
-            'book'    => [],
-        ];
-
-        foreach ($sortMap->all() as $sortMapItem) {
-            $ids[$sortMapItem->type][] = $sortMapItem->id;
-            $ids['book'][] = $sortMapItem->parentBookId;
-            if ($sortMapItem->parentChapterId) {
-                $ids['chapter'][] = $sortMapItem->parentChapterId;
-            }
-        }
-
-        $pages = $this->queries->pages->visibleForList()->whereIn('id', array_unique($ids['page']))->get();
-        /** @var Page $page */
-        foreach ($pages as $page) {
-            $modelMap['page:' . $page->id] = $page;
-            $ids['book'][] = $page->book_id;
-            if ($page->chapter_id) {
-                $ids['chapter'][] = $page->chapter_id;
-            }
-        }
-
-        $chapters = $this->queries->chapters->visibleForList()->whereIn('id', array_unique($ids['chapter']))->get();
-        /** @var Chapter $chapter */
-        foreach ($chapters as $chapter) {
-            $modelMap['chapter:' . $chapter->id] = $chapter;
-            $ids['book'][] = $chapter->book_id;
-        }
-
-        $books = $this->queries->books->visibleForList()->whereIn('id', array_unique($ids['book']))->get();
-        /** @var Book $book */
-        foreach ($books as $book) {
-            $modelMap['book:' . $book->id] = $book;
-        }
-
-        return $modelMap;
-    }
 }

app/Entities/Tools/HierarchyTransformer.php

@@ -13,17 +13,12 @@ use BookStack\Facades\Activity;
 
 class HierarchyTransformer
 {
-    protected BookRepo $bookRepo;
-    protected BookshelfRepo $shelfRepo;
-    protected Cloner $cloner;
-    protected TrashCan $trashCan;
-
-    public function __construct(BookRepo $bookRepo, BookshelfRepo $shelfRepo, Cloner $cloner, TrashCan $trashCan)
-    {
-        $this->bookRepo = $bookRepo;
-        $this->shelfRepo = $shelfRepo;
-        $this->cloner = $cloner;
-        $this->trashCan = $trashCan;
+    public function __construct(
+        protected BookRepo $bookRepo,
+        protected BookshelfRepo $shelfRepo,
+        protected Cloner $cloner,
+        protected TrashCan $trashCan
+    ) {
     }
 
     /**

app/Entities/Tools/TrashCan.php

@@ -15,6 +15,7 @@ use BookStack\Exceptions\NotifyException;
 use BookStack\Facades\Activity;
 use BookStack\Uploads\AttachmentService;
 use BookStack\Uploads\ImageService;
+use BookStack\Util\DatabaseTransaction;
 use Exception;
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Support\Carbon;
@@ -357,25 +358,26 @@ class TrashCan
 
     /**
      * Destroy the given entity.
+     * Returns the number of total entities destroyed in the operation.
      *
      * @throws Exception
      */
     public function destroyEntity(Entity $entity): int
     {
-        if ($entity instanceof Page) {
-            return $this->destroyPage($entity);
-        }
-        if ($entity instanceof Chapter) {
-            return $this->destroyChapter($entity);
-        }
-        if ($entity instanceof Book) {
-            return $this->destroyBook($entity);
-        }
-        if ($entity instanceof Bookshelf) {
-            return $this->destroyShelf($entity);
-        }
+        $result = (new DatabaseTransaction(function () use ($entity) {
+            if ($entity instanceof Page) {
+                return $this->destroyPage($entity);
+            } else if ($entity instanceof Chapter) {
+                return $this->destroyChapter($entity);
+            } else if ($entity instanceof Book) {
+                return $this->destroyBook($entity);
+            } else if ($entity instanceof Bookshelf) {
+                return $this->destroyShelf($entity);
+            }
+            return null;
+        }))->run();
 
-        return 0;
+        return $result ?? 0;
     }
 
     /**

app/Exceptions/BookStackExceptionHandlerPage.php

@@ -2,6 +2,7 @@
 
 namespace BookStack\Exceptions;
 
+use BookStack\App\AppVersion;
 use Illuminate\Contracts\Foundation\ExceptionRenderer;
 
 class BookStackExceptionHandlerPage implements ExceptionRenderer
@@ -30,9 +31,7 @@ class BookStackExceptionHandlerPage implements ExceptionRenderer
         return [
             'PHP Version'       => phpversion(),
             'BookStack Version' => $this->safeReturn(function () {
-                $versionFile = base_path('version');
-
-                return trim(file_get_contents($versionFile));
+                return AppVersion::get();
             }, 'unknown'),
             'Theme Configured' => $this->safeReturn(function () {
                 return config('view.theme');

app/Exports/Controllers/BookExportApiController.php

@@ -4,6 +4,7 @@ namespace BookStack\Exports\Controllers;
 
 use BookStack\Entities\Queries\BookQueries;
 use BookStack\Exports\ExportFormatter;
+use BookStack\Exports\ZipExports\ZipExportBuilder;
 use BookStack\Http\ApiController;
 use Throwable;
 
@@ -63,4 +64,15 @@ class BookExportApiController extends ApiController
 
         return $this->download()->directly($markdown, $book->slug . '.md');
     }
+
+    /**
+     * Export a book as a contained ZIP export file.
+     */
+    public function exportZip(int $id, ZipExportBuilder $builder)
+    {
+        $book = $this->queries->findVisibleByIdOrFail($id);
+        $zip = $builder->buildForBook($book);
+
+        return $this->download()->streamedFileDirectly($zip, $book->slug . '.zip', true);
+    }
 }

app/Exports/Controllers/BookExportController.php

@@ -16,6 +16,7 @@ class BookExportController extends Controller
         protected ExportFormatter $exportFormatter,
     ) {
         $this->middleware('can:content-export');
+        $this->middleware('throttle:exports');
     }
 
     /**
@@ -75,6 +76,6 @@ class BookExportController extends Controller
         $book = $this->queries->findVisibleBySlugOrFail($bookSlug);
         $zip = $builder->buildForBook($book);
 
-        return $this->download()->streamedDirectly(fopen($zip, 'r'), $bookSlug . '.zip', filesize($zip));
+        return $this->download()->streamedFileDirectly($zip, $bookSlug . '.zip', true);
     }
 }

app/Exports/Controllers/ChapterExportApiController.php

@@ -4,6 +4,7 @@ namespace BookStack\Exports\Controllers;
 
 use BookStack\Entities\Queries\ChapterQueries;
 use BookStack\Exports\ExportFormatter;
+use BookStack\Exports\ZipExports\ZipExportBuilder;
 use BookStack\Http\ApiController;
 use Throwable;
 
@@ -63,4 +64,15 @@ class ChapterExportApiController extends ApiController
 
         return $this->download()->directly($markdown, $chapter->slug . '.md');
     }
+
+    /**
+     * Export a chapter as a contained ZIP file.
+     */
+    public function exportZip(int $id, ZipExportBuilder $builder)
+    {
+        $chapter = $this->queries->findVisibleByIdOrFail($id);
+        $zip = $builder->buildForChapter($chapter);
+
+        return $this->download()->streamedFileDirectly($zip, $chapter->slug . '.zip', true);
+    }
 }

app/Exports/Controllers/ChapterExportController.php

@@ -16,6 +16,7 @@ class ChapterExportController extends Controller
         protected ExportFormatter $exportFormatter,
     ) {
         $this->middleware('can:content-export');
+        $this->middleware('throttle:exports');
     }
 
     /**
@@ -81,6 +82,6 @@ class ChapterExportController extends Controller
         $chapter = $this->queries->findVisibleBySlugsOrFail($bookSlug, $chapterSlug);
         $zip = $builder->buildForChapter($chapter);
 
-        return $this->download()->streamedDirectly(fopen($zip, 'r'), $chapterSlug . '.zip', filesize($zip));
+        return $this->download()->streamedFileDirectly($zip, $chapterSlug . '.zip', true);
     }
 }

app/Exports/Controllers/ImportApiController.php

@@ -0,0 +1,144 @@
+<?php
+
+declare(strict_types=1);
+
+namespace BookStack\Exports\Controllers;
+
+use BookStack\Exceptions\ZipImportException;
+use BookStack\Exceptions\ZipValidationException;
+use BookStack\Exports\ImportRepo;
+use BookStack\Http\ApiController;
+use BookStack\Uploads\AttachmentService;
+use Illuminate\Http\Request;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Response;
+
+class ImportApiController extends ApiController
+{
+    public function __construct(
+        protected ImportRepo $imports,
+    ) {
+        $this->middleware('can:content-import');
+    }
+
+    /**
+     * List existing ZIP imports visible to the user.
+     * Requires permission to import content.
+     */
+    public function list(): JsonResponse
+    {
+        $query = $this->imports->queryVisible();
+
+        return $this->apiListingResponse($query, [
+            'id', 'name', 'size', 'type', 'created_by', 'created_at', 'updated_at'
+        ]);
+    }
+
+    /**
+     * Start a new import from a ZIP file.
+     * This does not actually run the import since that is performed via the "run" endpoint.
+     * This uploads, validates and stores the ZIP file so it's ready to be imported.
+     *
+     * This "file" parameter must be a BookStack-compatible ZIP file, and this must be
+     * sent via a 'multipart/form-data' type request.
+     *
+     * Requires permission to import content.
+     */
+    public function create(Request $request): JsonResponse
+    {
+        $this->validate($request, $this->rules()['create']);
+
+        $file = $request->file('file');
+
+        try {
+            $import = $this->imports->storeFromUpload($file);
+        } catch (ZipValidationException $exception) {
+            $message = "ZIP upload failed with the following validation errors: \n" . $this->formatErrors($exception->errors);
+            return $this->jsonError($message, 422);
+        }
+
+        return response()->json($import);
+    }
+
+    /**
+     * Read details of a pending ZIP import.
+     * The "details" property contains high-level metadata regarding the ZIP import content,
+     * and the structure of this will change depending on import "type".
+     * Requires permission to import content.
+     */
+    public function read(int $id): JsonResponse
+    {
+        $import = $this->imports->findVisible($id);
+
+        $import->setAttribute('details', $import->decodeMetadata());
+
+        return response()->json($import);
+    }
+
+    /**
+     * Run the import process for an uploaded ZIP import.
+     * The "parent_id" and "parent_type" parameters are required when the import type is "chapter" or "page".
+     * On success, this endpoint returns the imported item.
+     * Requires permission to import content.
+     */
+    public function run(int $id, Request $request): JsonResponse
+    {
+        $import = $this->imports->findVisible($id);
+        $parent = null;
+        $rules = $this->rules()['run'];
+
+        if ($import->type === 'page' || $import->type === 'chapter') {
+            $rules['parent_type'][] = 'required';
+            $rules['parent_id'][] = 'required';
+            $data = $this->validate($request, $rules);
+            $parent = "{$data['parent_type']}:{$data['parent_id']}";
+        }
+
+        try {
+            $entity = $this->imports->runImport($import, $parent);
+        } catch (ZipImportException $exception) {
+            $message = "ZIP import failed with the following errors: \n" . $this->formatErrors($exception->errors);
+            return $this->jsonError($message);
+        }
+
+        return response()->json($entity->withoutRelations());
+    }
+
+    /**
+     * Delete a pending ZIP import from the system.
+     * Requires permission to import content.
+     */
+    public function delete(int $id): Response
+    {
+        $import = $this->imports->findVisible($id);
+        $this->imports->deleteImport($import);
+
+        return response('', 204);
+    }
+
+    protected function rules(): array
+    {
+        return [
+            'create' => [
+                'file' => ['required', ...AttachmentService::getFileValidationRules()],
+            ],
+            'run' => [
+                'parent_type' => ['string', 'in:book,chapter'],
+                'parent_id' => ['int'],
+            ],
+        ];
+    }
+
+    protected function formatErrors(array $errors): string
+    {
+        $parts = [];
+        foreach ($errors as $key => $error) {
+            if (is_string($key)) {
+                $parts[] = "[{$key}] {$error}";
+            } else {
+                $parts[] = $error;
+            }
+        }
+        return implode("\n", $parts);
+    }
+}

app/Exports/Controllers/PageExportApiController.php

@@ -4,6 +4,7 @@ namespace BookStack\Exports\Controllers;
 
 use BookStack\Entities\Queries\PageQueries;
 use BookStack\Exports\ExportFormatter;
+use BookStack\Exports\ZipExports\ZipExportBuilder;
 use BookStack\Http\ApiController;
 use Throwable;
 
@@ -63,4 +64,15 @@ class PageExportApiController extends ApiController
 
         return $this->download()->directly($markdown, $page->slug . '.md');
     }
+
+    /**
+     * Export a page as a contained ZIP file.
+     */
+    public function exportZip(int $id, ZipExportBuilder $builder)
+    {
+        $page = $this->queries->findVisibleByIdOrFail($id);
+        $zip = $builder->buildForPage($page);
+
+        return $this->download()->streamedFileDirectly($zip, $page->slug . '.zip', true);
+    }
 }

app/Exports/Controllers/PageExportController.php

@@ -17,6 +17,7 @@ class PageExportController extends Controller
         protected ExportFormatter $exportFormatter,
     ) {
         $this->middleware('can:content-export');
+        $this->middleware('throttle:exports');
     }
 
     /**
@@ -85,6 +86,6 @@ class PageExportController extends Controller
         $page = $this->queries->findVisibleBySlugsOrFail($bookSlug, $pageSlug);
         $zip = $builder->buildForPage($page);
 
-        return $this->download()->streamedDirectly(fopen($zip, 'r'), $pageSlug . '.zip', filesize($zip));
+        return $this->download()->streamedFileDirectly($zip, $pageSlug . '.zip', true);
     }
 }

app/Exports/Import.php

@@ -28,6 +28,8 @@ class Import extends Model implements Loggable
 {
     use HasFactory;
 
+    protected $hidden = ['metadata'];
+
     public function getSizeString(): string
     {
         $mb = round($this->size / 1000000, 2);

app/Exports/ImportRepo.php

@@ -17,6 +17,7 @@ use BookStack\Exports\ZipExports\ZipExportValidator;
 use BookStack\Exports\ZipExports\ZipImportRunner;
 use BookStack\Facades\Activity;
 use BookStack\Uploads\FileStorage;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Collection;
 use Illuminate\Support\Facades\DB;
 use Symfony\Component\HttpFoundation\File\UploadedFile;
@@ -34,6 +35,11 @@ class ImportRepo
      * @return Collection<Import>
      */
     public function getVisibleImports(): Collection
+    {
+        return $this->queryVisible()->get();
+    }
+
+    public function queryVisible(): Builder
     {
         $query = Import::query();
 
@@ -41,7 +47,7 @@ class ImportRepo
             $query->where('created_by', user()->id);
         }
 
-        return $query->get();
+        return $query;
     }
 
     public function findVisible(int $id): Import

app/Exports/PdfGenerator.php

@@ -90,18 +90,28 @@ class PdfGenerator
         $process = Process::fromShellCommandline($command);
         $process->setTimeout($timeout);
 
+        $cleanup = function () use ($inputHtml, $outputPdf) {
+            foreach ([$inputHtml, $outputPdf] as $file) {
+                if (file_exists($file)) {
+                    unlink($file);
+                }
+            }
+        };
+
         try {
             $process->run();
         } catch (ProcessTimedOutException $e) {
+            $cleanup();
             throw new PdfExportException("PDF Export via command failed due to timeout at {$timeout} second(s)");
         }
 
         if (!$process->isSuccessful()) {
+            $cleanup();
             throw new PdfExportException("PDF Export via command failed with exit code {$process->getExitCode()}, stdout: {$process->getOutput()}, stderr: {$process->getErrorOutput()}");
         }
 
         $pdfContents = file_get_contents($outputPdf);
-        unlink($outputPdf);
+        $cleanup();
 
         if ($pdfContents === false) {
             throw new PdfExportException("PDF Export via command failed, unable to read PDF output file");

app/Exports/ZipExports/ZipExportBuilder.php

@@ -2,6 +2,7 @@
 
 namespace BookStack\Exports\ZipExports;
 
+use BookStack\App\AppVersion;
 use BookStack\Entities\Models\Book;
 use BookStack\Entities\Models\Chapter;
 use BookStack\Entities\Models\Page;
@@ -70,7 +71,7 @@ class ZipExportBuilder
         $this->data['exported_at'] = date(DATE_ATOM);
         $this->data['instance'] = [
             'id'      => setting('instance-id', ''),
-            'version' => trim(file_get_contents(base_path('version'))),
+            'version' => AppVersion::get(),
         ];
 
         $zipFile = tempnam(sys_get_temp_dir(), 'bszip-');
@@ -84,10 +85,27 @@ class ZipExportBuilder
         $zip->addEmptyDir('files');
 
         $toRemove = [];
-        $this->files->extractEach(function ($filePath, $fileRef) use ($zip, &$toRemove) {
-            $zip->addFile($filePath, "files/$fileRef");
-            $toRemove[] = $filePath;
-        });
+        $addedNames = [];
+
+        try {
+            $this->files->extractEach(function ($filePath, $fileRef) use ($zip, &$toRemove, &$addedNames) {
+                $entryName = "files/$fileRef";
+                $zip->addFile($filePath, $entryName);
+                $toRemove[] = $filePath;
+                $addedNames[] = $entryName;
+            });
+        } catch (\Exception $exception) {
+            // Cleanup the files we've processed so far and respond back with error
+            foreach ($toRemove as $file) {
+                unlink($file);
+            }
+            foreach ($addedNames as $name) {
+                $zip->deleteName($name);
+            }
+            $zip->close();
+            unlink($zipFile);
+            throw new ZipExportException("Failed to add files for ZIP export, received error: " . $exception->getMessage());
+        }
 
         $zip->close();
 

app/Http/ApiController.php

@@ -8,7 +8,7 @@ use Illuminate\Http\JsonResponse;
 
 abstract class ApiController extends Controller
 {
-    protected $rules = [];
+    protected array $rules = [];
 
     /**
      * Provide a paginated listing JSON response in a standard format

app/Http/Controller.php

@@ -49,13 +49,13 @@ abstract class Controller extends BaseController
      * On a permission error redirect to home and display.
      * the error as a notification.
      *
-     * @return never
+     * @throws NotifyException
      */
-    protected function showPermissionError()
+    protected function showPermissionError(string $redirectLocation = '/'): never
     {
         $message = request()->wantsJson() ? trans('errors.permissionJson') : trans('errors.permission');
 
-        throw new NotifyException($message, '/', 403);
+        throw new NotifyException($message, $redirectLocation, 403);
     }
 
     /**
@@ -81,10 +81,10 @@ abstract class Controller extends BaseController
     /**
      * Check the current user's permissions against an ownable item otherwise throw an exception.
      */
-    protected function checkOwnablePermission(string $permission, Model $ownable): void
+    protected function checkOwnablePermission(string $permission, Model $ownable, string $redirectLocation = '/'): void
     {
         if (!userCan($permission, $ownable)) {
-            $this->showPermissionError();
+            $this->showPermissionError($redirectLocation);
         }
     }
 
@@ -163,7 +163,7 @@ abstract class Controller extends BaseController
      */
     protected function getImageValidationRules(): array
     {
-        return ['image_extension', 'mimes:jpeg,png,gif,webp', 'max:' . (config('app.upload_limit') * 1000)];
+        return ['image_extension', 'mimes:jpeg,png,gif,webp,avif', 'max:' . (config('app.upload_limit') * 1000)];
     }
 
     /**

app/Http/DownloadResponseFactory.php

@@ -9,7 +9,7 @@ use Symfony\Component\HttpFoundation\StreamedResponse;
 class DownloadResponseFactory
 {
     public function __construct(
-        protected Request $request
+        protected Request $request,
     ) {
     }
 
@@ -35,6 +35,33 @@ class DownloadResponseFactory
         );
     }
 
+    /**
+     * Create a response that downloads the given file via a stream.
+     * Has the option to delete the provided file once the stream is closed.
+     */
+    public function streamedFileDirectly(string $filePath, string $fileName, bool $deleteAfter = false): StreamedResponse
+    {
+        $fileSize = filesize($filePath);
+        $stream = fopen($filePath, 'r');
+
+        if ($deleteAfter) {
+            // Delete the given file if it still exists after the app terminates
+            $callback = function () use ($filePath) {
+                if (file_exists($filePath)) {
+                    unlink($filePath);
+                }
+            };
+
+            // We watch both app terminate and php shutdown to cover both normal app termination
+            // as well as other potential scenarios (connection termination).
+            app()->terminating($callback);
+            register_shutdown_function($callback);
+        }
+
+        return $this->streamedDirectly($stream, $fileName, $fileSize);
+    }
+
+
     /**
      * Create a file download response that provides the file with a content-type
      * correct for the file, in a way so the browser can show the content in browser,
@@ -43,7 +70,7 @@ class DownloadResponseFactory
     public function streamedInline($stream, string $fileName, int $fileSize): StreamedResponse
     {
         $rangeStream = new RangeSupportedStream($stream, $fileSize, $this->request);
-        $mime = $rangeStream->sniffMime();
+        $mime = $rangeStream->sniffMime(pathinfo($fileName, PATHINFO_EXTENSION));
         $headers = array_merge($this->getHeaders($fileName, $fileSize, $mime), $rangeStream->getResponseHeaders());
 
         return response()->stream(
@@ -53,6 +80,22 @@ class DownloadResponseFactory
         );
     }
 
+    /**
+     * Create a response that provides the given file via a stream with detected content-type.
+     * Has the option to delete the provided file once the stream is closed.
+     */
+    public function streamedFileInline(string $filePath, ?string $fileName = null): StreamedResponse
+    {
+        $fileSize = filesize($filePath);
+        $stream = fopen($filePath, 'r');
+
+        if ($fileName === null) {
+            $fileName = basename($filePath);
+        }
+
+        return $this->streamedInline($stream, $fileName, $fileSize);
+    }
+
     /**
      * Get the common headers to provide for a download response.
      */

app/Http/Middleware/PreventResponseCaching.php

@@ -7,6 +7,13 @@ use Symfony\Component\HttpFoundation\Response;
 
 class PreventResponseCaching
 {
+    /**
+     * Paths to ignore when preventing response caching.
+     */
+    protected array $ignoredPathPrefixes = [
+        'theme/',
+    ];
+
     /**
      * Handle an incoming request.
      *
@@ -20,6 +27,13 @@ class PreventResponseCaching
         /** @var Response $response */
         $response = $next($request);
 
+        $path = $request->path();
+        foreach ($this->ignoredPathPrefixes as $ignoredPath) {
+            if (str_starts_with($path, $ignoredPath)) {
+                return $response;
+            }
+        }
+
         $response->headers->set('Cache-Control', 'no-cache, no-store, private');
         $response->headers->set('Expires', 'Sun, 12 Jul 2015 19:01:00 GMT');
 

app/Http/RangeSupportedStream.php

@@ -32,12 +32,12 @@ class RangeSupportedStream
     /**
      * Sniff a mime type from the stream.
      */
-    public function sniffMime(): string
+    public function sniffMime(string $extension = ''): string
     {
         $offset = min(2000, $this->fileSize);
         $this->sniffContent = fread($this->stream, $offset);
 
-        return (new WebSafeMimeSniffer())->sniff($this->sniffContent);
+        return (new WebSafeMimeSniffer())->sniff($this->sniffContent, $extension);
     }
 
     /**

app/Permissions/ContentPermissionApiController.php

@@ -16,7 +16,7 @@ class ContentPermissionApiController extends ApiController
     ) {
     }
 
-    protected $rules = [
+    protected array $rules = [
         'update' => [
             'owner_id'  => ['int'],
 

app/Permissions/JointPermissionBuilder.php

@@ -29,7 +29,7 @@ class JointPermissionBuilder
     /**
      * Re-generate all entity permission from scratch.
      */
-    public function rebuildForAll()
+    public function rebuildForAll(): void
     {
         JointPermission::query()->truncate();
 
@@ -51,7 +51,7 @@ class JointPermissionBuilder
     /**
      * Rebuild the entity jointPermissions for a particular entity.
      */
-    public function rebuildForEntity(Entity $entity)
+    public function rebuildForEntity(Entity $entity): void
     {
         $entities = [$entity];
         if ($entity instanceof Book) {
@@ -119,7 +119,7 @@ class JointPermissionBuilder
     /**
      * Build joint permissions for the given book and role combinations.
      */
-    protected function buildJointPermissionsForBooks(EloquentCollection $books, array $roles, bool $deleteOld = false)
+    protected function buildJointPermissionsForBooks(EloquentCollection $books, array $roles, bool $deleteOld = false): void
     {
         $entities = clone $books;
 
@@ -143,7 +143,7 @@ class JointPermissionBuilder
     /**
      * Rebuild the entity jointPermissions for a collection of entities.
      */
-    protected function buildJointPermissionsForEntities(array $entities)
+    protected function buildJointPermissionsForEntities(array $entities): void
     {
         $roles = Role::query()->get()->values()->all();
         $this->deleteManyJointPermissionsForEntities($entities);
@@ -155,21 +155,19 @@ class JointPermissionBuilder
      *
      * @param Entity[] $entities
      */
-    protected function deleteManyJointPermissionsForEntities(array $entities)
+    protected function deleteManyJointPermissionsForEntities(array $entities): void
     {
         $simpleEntities = $this->entitiesToSimpleEntities($entities);
         $idsByType = $this->entitiesToTypeIdMap($simpleEntities);
 
-        DB::transaction(function () use ($idsByType) {
-            foreach ($idsByType as $type => $ids) {
-                foreach (array_chunk($ids, 1000) as $idChunk) {
-                    DB::table('joint_permissions')
-                        ->where('entity_type', '=', $type)
-                        ->whereIn('entity_id', $idChunk)
-                        ->delete();
-                }
+        foreach ($idsByType as $type => $ids) {
+            foreach (array_chunk($ids, 1000) as $idChunk) {
+                DB::table('joint_permissions')
+                    ->where('entity_type', '=', $type)
+                    ->whereIn('entity_id', $idChunk)
+                    ->delete();
             }
-        });
+        }
     }
 
     /**
@@ -195,7 +193,7 @@ class JointPermissionBuilder
      * @param Entity[] $originalEntities
      * @param Role[]   $roles
      */
-    protected function createManyJointPermissions(array $originalEntities, array $roles)
+    protected function createManyJointPermissions(array $originalEntities, array $roles): void
     {
         $entities = $this->entitiesToSimpleEntities($originalEntities);
         $jointPermissions = [];
@@ -225,11 +223,9 @@ class JointPermissionBuilder
             }
         }
 
-        DB::transaction(function () use ($jointPermissions) {
-            foreach (array_chunk($jointPermissions, 1000) as $jointPermissionChunk) {
-                DB::table('joint_permissions')->insert($jointPermissionChunk);
-            }
-        });
+        foreach (array_chunk($jointPermissions, 1000) as $jointPermissionChunk) {
+            DB::table('joint_permissions')->insert($jointPermissionChunk);
+        }
     }
 
     /**

app/Permissions/PermissionsController.php

@@ -7,6 +7,7 @@ use BookStack\Entities\Tools\PermissionsUpdater;
 use BookStack\Http\Controller;
 use BookStack\Permissions\Models\EntityPermission;
 use BookStack\Users\Models\Role;
+use BookStack\Util\DatabaseTransaction;
 use Illuminate\Http\Request;
 
 class PermissionsController extends Controller
@@ -40,7 +41,9 @@ class PermissionsController extends Controller
         $page = $this->queries->pages->findVisibleBySlugsOrFail($bookSlug, $pageSlug);
         $this->checkOwnablePermission('restrictions-manage', $page);
 
-        $this->permissionsUpdater->updateFromPermissionsForm($page, $request);
+        (new DatabaseTransaction(function () use ($page, $request) {
+            $this->permissionsUpdater->updateFromPermissionsForm($page, $request);
+        }))->run();
 
         $this->showSuccessNotification(trans('entities.pages_permissions_success'));
 
@@ -70,7 +73,9 @@ class PermissionsController extends Controller
         $chapter = $this->queries->chapters->findVisibleBySlugsOrFail($bookSlug, $chapterSlug);
         $this->checkOwnablePermission('restrictions-manage', $chapter);
 
-        $this->permissionsUpdater->updateFromPermissionsForm($chapter, $request);
+        (new DatabaseTransaction(function () use ($chapter, $request) {
+            $this->permissionsUpdater->updateFromPermissionsForm($chapter, $request);
+        }))->run();
 
         $this->showSuccessNotification(trans('entities.chapters_permissions_success'));
 
@@ -100,7 +105,9 @@ class PermissionsController extends Controller
         $book = $this->queries->books->findVisibleBySlugOrFail($slug);
         $this->checkOwnablePermission('restrictions-manage', $book);
 
-        $this->permissionsUpdater->updateFromPermissionsForm($book, $request);
+        (new DatabaseTransaction(function () use ($book, $request) {
+            $this->permissionsUpdater->updateFromPermissionsForm($book, $request);
+        }))->run();
 
         $this->showSuccessNotification(trans('entities.books_permissions_updated'));
 
@@ -130,7 +137,9 @@ class PermissionsController extends Controller
         $shelf = $this->queries->shelves->findVisibleBySlugOrFail($slug);
         $this->checkOwnablePermission('restrictions-manage', $shelf);
 
-        $this->permissionsUpdater->updateFromPermissionsForm($shelf, $request);
+        (new DatabaseTransaction(function () use ($shelf, $request) {
+            $this->permissionsUpdater->updateFromPermissionsForm($shelf, $request);
+        }))->run();
 
         $this->showSuccessNotification(trans('entities.shelves_permissions_updated'));
 
@@ -145,7 +154,10 @@ class PermissionsController extends Controller
         $shelf = $this->queries->shelves->findVisibleBySlugOrFail($slug);
         $this->checkOwnablePermission('restrictions-manage', $shelf);
 
-        $updateCount = $this->permissionsUpdater->updateBookPermissionsFromShelf($shelf);
+        $updateCount = (new DatabaseTransaction(function () use ($shelf) {
+            return $this->permissionsUpdater->updateBookPermissionsFromShelf($shelf);
+        }))->run();
+
         $this->showSuccessNotification(trans('entities.shelves_copy_permission_success', ['count' => $updateCount]));
 
         return redirect($shelf->getUrl());

app/Permissions/PermissionsRepo.php

@@ -7,6 +7,7 @@ use BookStack\Exceptions\PermissionsException;
 use BookStack\Facades\Activity;
 use BookStack\Permissions\Models\RolePermission;
 use BookStack\Users\Models\Role;
+use BookStack\Util\DatabaseTransaction;
 use Exception;
 use Illuminate\Database\Eloquent\Collection;
 
@@ -48,38 +49,42 @@ class PermissionsRepo
      */
     public function saveNewRole(array $roleData): Role
     {
-        $role = new Role($roleData);
-        $role->mfa_enforced = boolval($roleData['mfa_enforced'] ?? false);
-        $role->save();
+        return (new DatabaseTransaction(function () use ($roleData) {
+            $role = new Role($roleData);
+            $role->mfa_enforced = boolval($roleData['mfa_enforced'] ?? false);
+            $role->save();
 
-        $permissions = $roleData['permissions'] ?? [];
-        $this->assignRolePermissions($role, $permissions);
-        $this->permissionBuilder->rebuildForRole($role);
+            $permissions = $roleData['permissions'] ?? [];
+            $this->assignRolePermissions($role, $permissions);
+            $this->permissionBuilder->rebuildForRole($role);
 
-        Activity::add(ActivityType::ROLE_CREATE, $role);
+            Activity::add(ActivityType::ROLE_CREATE, $role);
 
-        return $role;
+            return $role;
+        }))->run();
     }
 
     /**
      * Updates an existing role.
-     * Ensures Admin system role always have core permissions.
+     * Ensures the Admin system role always has core permissions.
      */
     public function updateRole($roleId, array $roleData): Role
     {
         $role = $this->getRoleById($roleId);
 
-        if (isset($roleData['permissions'])) {
-            $this->assignRolePermissions($role, $roleData['permissions']);
-        }
+        return (new DatabaseTransaction(function () use ($role, $roleData) {
+            if (isset($roleData['permissions'])) {
+                $this->assignRolePermissions($role, $roleData['permissions']);
+            }
 
-        $role->fill($roleData);
-        $role->save();
-        $this->permissionBuilder->rebuildForRole($role);
+            $role->fill($roleData);
+            $role->save();
+            $this->permissionBuilder->rebuildForRole($role);
 
-        Activity::add(ActivityType::ROLE_UPDATE, $role);
+            Activity::add(ActivityType::ROLE_UPDATE, $role);
 
-        return $role;
+            return $role;
+        }))->run();
     }
 
     /**
@@ -114,7 +119,7 @@ class PermissionsRepo
     /**
      * Delete a role from the system.
      * Check it's not an admin role or set as default before deleting.
-     * If a migration Role ID is specified the users assign to the current role
+     * If a migration Role ID is specified, the users assigned to the current role
      * will be added to the role of the specified id.
      *
      * @throws PermissionsException
@@ -131,17 +136,19 @@ class PermissionsRepo
             throw new PermissionsException(trans('errors.role_registration_default_cannot_delete'));
         }
 
-        if ($migrateRoleId !== 0) {
-            $newRole = Role::query()->find($migrateRoleId);
-            if ($newRole) {
-                $users = $role->users()->pluck('id')->toArray();
-                $newRole->users()->sync($users);
+        (new DatabaseTransaction(function () use ($migrateRoleId, $role) {
+            if ($migrateRoleId !== 0) {
+                $newRole = Role::query()->find($migrateRoleId);
+                if ($newRole) {
+                    $users = $role->users()->pluck('id')->toArray();
+                    $newRole->users()->sync($users);
+                }
             }
-        }
 
-        $role->entityPermissions()->delete();
-        $role->jointPermissions()->delete();
-        Activity::add(ActivityType::ROLE_DELETE, $role);
-        $role->delete();
+            $role->entityPermissions()->delete();
+            $role->jointPermissions()->delete();
+            Activity::add(ActivityType::ROLE_DELETE, $role);
+            $role->delete();
+        }))->run();
     }
 }

app/Search/SearchApiController.php

@@ -9,7 +9,7 @@ use Illuminate\Http\Request;
 
 class SearchApiController extends ApiController
 {
-    protected $rules = [
+    protected array $rules = [
         'all' => [
             'query' => ['required'],
             'page'  => ['integer', 'min:1'],

app/Search/SearchIndex.php

@@ -16,7 +16,13 @@ class SearchIndex
     /**
      * A list of delimiter characters used to break-up parsed content into terms for indexing.
      */
-    public static string $delimiters = " \n\t.,!?:;()[]{}<>`'\"";
+    public static string $delimiters = " \n\t.-,!?:;()[]{}<>`'\"«»";
+
+    /**
+     * A list of delimiter which could be commonly used within a single term and also indicate a break between terms.
+     * The indexer will index the full term with these delimiters, plus the terms split via these delimiters.
+     */
+    public static string $softDelimiters = ".-";
 
     public function __construct(
         protected EntityProvider $entityProvider
@@ -154,7 +160,9 @@ class SearchIndex
         /** @var DOMNode $child */
         foreach ($doc->getBodyChildren() as $child) {
             $nodeName = $child->nodeName;
-            $termCounts = $this->textToTermCountMap(trim($child->textContent));
+            $text = trim($child->textContent);
+            $text = str_replace("\u{00A0}", ' ', $text);
+            $termCounts = $this->textToTermCountMap($text);
             foreach ($termCounts as $term => $count) {
                 $scoreChange = $count * ($elementScoreAdjustmentMap[$nodeName] ?? 1);
                 $scoresByTerm[$term] = ($scoresByTerm[$term] ?? 0) + $scoreChange;
@@ -196,15 +204,36 @@ class SearchIndex
     protected function textToTermCountMap(string $text): array
     {
         $tokenMap = []; // {TextToken => OccurrenceCount}
-        $splitChars = static::$delimiters;
-        $token = strtok($text, $splitChars);
+        $softDelims = static::$softDelimiters;
+        $tokenizer = new SearchTextTokenizer($text, static::$delimiters);
+        $extendedToken = '';
+        $extendedLen = 0;
+
+        $token = $tokenizer->next();
 
         while ($token !== false) {
-            if (!isset($tokenMap[$token])) {
-                $tokenMap[$token] = 0;
+            $delim = $tokenizer->previousDelimiter();
+
+            if ($delim && str_contains($softDelims, $delim) && $token !== '') {
+                $extendedToken .= $delim . $token;
+                $extendedLen++;
+            } else {
+                if ($extendedLen > 1) {
+                    $tokenMap[$extendedToken] = ($tokenMap[$extendedToken] ?? 0) + 1;
+                }
+                $extendedToken = $token;
+                $extendedLen = 1;
             }
-            $tokenMap[$token]++;
-            $token = strtok($splitChars);
+
+            if ($token) {
+                $tokenMap[$token] = ($tokenMap[$token] ?? 0) + 1;
+            }
+
+            $token = $tokenizer->next();
+        }
+
+        if ($extendedLen > 1) {
+            $tokenMap[$extendedToken] = ($tokenMap[$extendedToken] ?? 0) + 1;
         }
 
         return $tokenMap;

app/Search/SearchOptions.php

@@ -181,7 +181,7 @@ class SearchOptions
     protected static function parseStandardTermString(string $termString): array
     {
         $terms = explode(' ', $termString);
-        $indexDelimiters = SearchIndex::$delimiters;
+        $indexDelimiters = implode('', array_diff(str_split(SearchIndex::$delimiters), str_split(SearchIndex::$softDelimiters)));
         $parsed = [
             'terms'  => [],
             'exacts' => [],

app/Search/SearchTextTokenizer.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace BookStack\Search;
+
+/**
+ * A custom text tokenizer which records & provides insight needed for our search indexing.
+ * We used to use basic strtok() but this class does the following which that lacked:
+ * - Tracks and provides the current/previous delimiter that we've stopped at.
+ * - Returns empty tokens upon parsing a delimiter.
+ */
+class SearchTextTokenizer
+{
+    protected int $currentIndex = 0;
+    protected int $length;
+    protected string $currentDelimiter = '';
+    protected string $previousDelimiter = '';
+
+    public function __construct(
+        protected string $text,
+        protected string $delimiters = ' '
+    ) {
+        $this->length = strlen($this->text);
+    }
+
+    /**
+     * Get the current delimiter to be found.
+     */
+    public function currentDelimiter(): string
+    {
+        return $this->currentDelimiter;
+    }
+
+    /**
+     * Get the previous delimiter found.
+     */
+    public function previousDelimiter(): string
+    {
+        return $this->previousDelimiter;
+    }
+
+    /**
+     * Get the next token between delimiters.
+     * Returns false if there's no further tokens.
+     */
+    public function next(): string|false
+    {
+        $token = '';
+
+        for ($i = $this->currentIndex; $i < $this->length; $i++) {
+            $char = $this->text[$i];
+            if (str_contains($this->delimiters, $char)) {
+                $this->previousDelimiter = $this->currentDelimiter;
+                $this->currentDelimiter = $char;
+                $this->currentIndex = $i + 1;
+                return $token;
+            }
+
+            $token .= $char;
+        }
+
+        if ($token) {
+            $this->currentIndex = $this->length;
+            $this->previousDelimiter = $this->currentDelimiter;
+            $this->currentDelimiter = '';
+            return $token;
+        }
+
+        return false;
+    }
+}

app/Settings/MaintenanceController.php

@@ -3,6 +3,7 @@
 namespace BookStack\Settings;
 
 use BookStack\Activity\ActivityType;
+use BookStack\App\AppVersion;
 use BookStack\Entities\Tools\TrashCan;
 use BookStack\Http\Controller;
 use BookStack\References\ReferenceStore;
@@ -19,14 +20,11 @@ class MaintenanceController extends Controller
         $this->checkPermission('settings-manage');
         $this->setPageTitle(trans('settings.maint'));
 
-        // Get application version
-        $version = trim(file_get_contents(base_path('version')));
-
         // Recycle bin details
         $recycleStats = $trashCan->getTrashedCounts();
 
         return view('settings.maintenance', [
-            'version'      => $version,
+            'version'      => AppVersion::get(),
             'recycleStats' => $recycleStats,
         ]);
     }

app/Settings/SettingController.php

@@ -3,6 +3,7 @@
 namespace BookStack\Settings;
 
 use BookStack\Activity\ActivityType;
+use BookStack\App\AppVersion;
 use BookStack\Http\Controller;
 use BookStack\Users\Models\User;
 use Illuminate\Http\Request;
@@ -26,12 +27,9 @@ class SettingController extends Controller
         $this->checkPermission('settings-manage');
         $this->setPageTitle(trans('settings.settings'));
 
-        // Get application version
-        $version = trim(file_get_contents(base_path('version')));
-
         return view('settings.categories.' . $category, [
             'category'  => $category,
-            'version'   => $version,
+            'version'   => AppVersion::get(),
             'guestUser' => User::getGuest(),
         ]);
     }

app/Sorting/BookSortController.php

@@ -1,13 +1,13 @@
 <?php
 
-namespace BookStack\Entities\Controllers;
+namespace BookStack\Sorting;
 
 use BookStack\Activity\ActivityType;
 use BookStack\Entities\Queries\BookQueries;
 use BookStack\Entities\Tools\BookContents;
-use BookStack\Entities\Tools\BookSortMap;
 use BookStack\Facades\Activity;
 use BookStack\Http\Controller;
+use BookStack\Util\DatabaseTransaction;
 use Illuminate\Http\Request;
 
 class BookSortController extends Controller
@@ -45,25 +45,42 @@ class BookSortController extends Controller
     }
 
     /**
-     * Sorts a book using a given mapping array.
+     * Update the sort options of a book, setting the auto-sort and/or updating
+     * child order via mapping.
      */
-    public function update(Request $request, string $bookSlug)
+    public function update(Request $request, BookSorter $sorter, string $bookSlug)
     {
         $book = $this->queries->findVisibleBySlugOrFail($bookSlug);
         $this->checkOwnablePermission('book-update', $book);
+        $loggedActivityForBook = false;
 
-        // Return if no map sent
-        if (!$request->filled('sort-tree')) {
-            return redirect($book->getUrl());
+        // Sort via map
+        if ($request->filled('sort-tree')) {
+            (new DatabaseTransaction(function () use ($book, $request, $sorter, &$loggedActivityForBook) {
+                $sortMap = BookSortMap::fromJson($request->get('sort-tree'));
+                $booksInvolved = $sorter->sortUsingMap($sortMap);
+
+                // Add activity for involved books.
+                foreach ($booksInvolved as $bookInvolved) {
+                    Activity::add(ActivityType::BOOK_SORT, $bookInvolved);
+                    if ($bookInvolved->id === $book->id) {
+                        $loggedActivityForBook = true;
+                    }
+                }
+            }))->run();
         }
 
-        $sortMap = BookSortMap::fromJson($request->get('sort-tree'));
-        $bookContents = new BookContents($book);
-        $booksInvolved = $bookContents->sortUsingMap($sortMap);
-
-        // Rebuild permissions and add activity for involved books.
-        foreach ($booksInvolved as $bookInvolved) {
-            Activity::add(ActivityType::BOOK_SORT, $bookInvolved);
+        if ($request->filled('auto-sort')) {
+            $sortSetId = intval($request->get('auto-sort')) ?: null;
+            if ($sortSetId && SortRule::query()->find($sortSetId) === null) {
+                $sortSetId = null;
+            }
+            $book->sort_rule_id = $sortSetId;
+            $book->save();
+            $sorter->runBookAutoSort($book);
+            if (!$loggedActivityForBook) {
+                Activity::add(ActivityType::BOOK_SORT, $book);
+            }
         }
 
         return redirect($book->getUrl());

app/Sorting/BookSortMap.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace BookStack\Entities\Tools;
+namespace BookStack\Sorting;
 
 class BookSortMap
 {

app/Sorting/BookSortMapItem.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace BookStack\Entities\Tools;
+namespace BookStack\Sorting;
 
 class BookSortMapItem
 {

app/Sorting/BookSorter.php

@@ -0,0 +1,283 @@
+<?php
+
+namespace BookStack\Sorting;
+
+use BookStack\Entities\Models\Book;
+use BookStack\Entities\Models\BookChild;
+use BookStack\Entities\Models\Chapter;
+use BookStack\Entities\Models\Entity;
+use BookStack\Entities\Models\Page;
+use BookStack\Entities\Queries\EntityQueries;
+
+class BookSorter
+{
+    public function __construct(
+        protected EntityQueries $queries,
+    ) {
+    }
+
+    public function runBookAutoSortForAllWithSet(SortRule $set): void
+    {
+        $set->books()->chunk(50, function ($books) {
+            foreach ($books as $book) {
+                $this->runBookAutoSort($book);
+            }
+        });
+    }
+
+    /**
+     * Runs the auto-sort for a book if the book has a sort set applied to it.
+     * This does not consider permissions since the sort operations are centrally
+     * managed by admins so considered permitted if existing and assigned.
+     */
+    public function runBookAutoSort(Book $book): void
+    {
+        $set = $book->sortRule;
+        if (!$set) {
+            return;
+        }
+
+        $sortFunctions = array_map(function (SortRuleOperation $op) {
+            return $op->getSortFunction();
+        }, $set->getOperations());
+
+        $chapters = $book->chapters()
+            ->with('pages:id,name,priority,created_at,updated_at,chapter_id')
+            ->get(['id', 'name', 'priority', 'created_at', 'updated_at']);
+
+        /** @var (Chapter|Book)[] $topItems */
+        $topItems = [
+            ...$book->directPages()->get(['id', 'name', 'priority', 'created_at', 'updated_at']),
+            ...$chapters,
+        ];
+
+        foreach ($sortFunctions as $sortFunction) {
+            usort($topItems, $sortFunction);
+        }
+
+        foreach ($topItems as $index => $topItem) {
+            $topItem->priority = $index + 1;
+            $topItem::withoutTimestamps(fn () => $topItem->save());
+        }
+
+        foreach ($chapters as $chapter) {
+            $pages = $chapter->pages->all();
+            foreach ($sortFunctions as $sortFunction) {
+                usort($pages, $sortFunction);
+            }
+
+            foreach ($pages as $index => $page) {
+                $page->priority = $index + 1;
+                $page::withoutTimestamps(fn () => $page->save());
+            }
+        }
+    }
+
+
+    /**
+     * Sort the books content using the given sort map.
+     * Returns a list of books that were involved in the operation.
+     *
+     * @returns Book[]
+     */
+    public function sortUsingMap(BookSortMap $sortMap): array
+    {
+        // Load models into map
+        $modelMap = $this->loadModelsFromSortMap($sortMap);
+
+        // Sort our changes from our map to be chapters first
+        // Since they need to be process to ensure book alignment for child page changes.
+        $sortMapItems = $sortMap->all();
+        usort($sortMapItems, function (BookSortMapItem $itemA, BookSortMapItem $itemB) {
+            $aScore = $itemA->type === 'page' ? 2 : 1;
+            $bScore = $itemB->type === 'page' ? 2 : 1;
+
+            return $aScore - $bScore;
+        });
+
+        // Perform the sort
+        foreach ($sortMapItems as $item) {
+            $this->applySortUpdates($item, $modelMap);
+        }
+
+        /** @var Book[] $booksInvolved */
+        $booksInvolved = array_values(array_filter($modelMap, function (string $key) {
+            return str_starts_with($key, 'book:');
+        }, ARRAY_FILTER_USE_KEY));
+
+        // Update permissions of books involved
+        foreach ($booksInvolved as $book) {
+            $book->rebuildPermissions();
+        }
+
+        return $booksInvolved;
+    }
+
+    /**
+     * Using the given sort map item, detect changes for the related model
+     * and update it if required. Changes where permissions are lacking will
+     * be skipped and not throw an error.
+     *
+     * @param array<string, Entity> $modelMap
+     */
+    protected function applySortUpdates(BookSortMapItem $sortMapItem, array $modelMap): void
+    {
+        /** @var BookChild $model */
+        $model = $modelMap[$sortMapItem->type . ':' . $sortMapItem->id] ?? null;
+        if (!$model) {
+            return;
+        }
+
+        $priorityChanged = $model->priority !== $sortMapItem->sort;
+        $bookChanged = $model->book_id !== $sortMapItem->parentBookId;
+        $chapterChanged = ($model instanceof Page) && $model->chapter_id !== $sortMapItem->parentChapterId;
+
+        // Stop if there's no change
+        if (!$priorityChanged && !$bookChanged && !$chapterChanged) {
+            return;
+        }
+
+        $currentParentKey = 'book:' . $model->book_id;
+        if ($model instanceof Page && $model->chapter_id) {
+            $currentParentKey = 'chapter:' . $model->chapter_id;
+        }
+
+        $currentParent = $modelMap[$currentParentKey] ?? null;
+        /** @var Book $newBook */
+        $newBook = $modelMap['book:' . $sortMapItem->parentBookId] ?? null;
+        /** @var ?Chapter $newChapter */
+        $newChapter = $sortMapItem->parentChapterId ? ($modelMap['chapter:' . $sortMapItem->parentChapterId] ?? null) : null;
+
+        if (!$this->isSortChangePermissible($sortMapItem, $model, $currentParent, $newBook, $newChapter)) {
+            return;
+        }
+
+        // Action the required changes
+        if ($bookChanged) {
+            $model->changeBook($newBook->id);
+        }
+
+        if ($model instanceof Page && $chapterChanged) {
+            $model->chapter_id = $newChapter->id ?? 0;
+        }
+
+        if ($priorityChanged) {
+            $model->priority = $sortMapItem->sort;
+        }
+
+        if ($chapterChanged || $priorityChanged) {
+            $model::withoutTimestamps(fn () => $model->save());
+        }
+    }
+
+    /**
+     * Check if the current user has permissions to apply the given sorting change.
+     * Is quite complex since items can gain a different parent change. Acts as a:
+     * - Update of old parent element (Change of content/order).
+     * - Update of sorted/moved element.
+     * - Deletion of element (Relative to parent upon move).
+     * - Creation of element within parent (Upon move to new parent).
+     */
+    protected function isSortChangePermissible(BookSortMapItem $sortMapItem, BookChild $model, ?Entity $currentParent, ?Entity $newBook, ?Entity $newChapter): bool
+    {
+        // Stop if we can't see the current parent or new book.
+        if (!$currentParent || !$newBook) {
+            return false;
+        }
+
+        $hasNewParent = $newBook->id !== $model->book_id || ($model instanceof Page && $model->chapter_id !== ($sortMapItem->parentChapterId ?? 0));
+        if ($model instanceof Chapter) {
+            $hasPermission = userCan('book-update', $currentParent)
+                && userCan('book-update', $newBook)
+                && userCan('chapter-update', $model)
+                && (!$hasNewParent || userCan('chapter-create', $newBook))
+                && (!$hasNewParent || userCan('chapter-delete', $model));
+
+            if (!$hasPermission) {
+                return false;
+            }
+        }
+
+        if ($model instanceof Page) {
+            $parentPermission = ($currentParent instanceof Chapter) ? 'chapter-update' : 'book-update';
+            $hasCurrentParentPermission = userCan($parentPermission, $currentParent);
+
+            // This needs to check if there was an intended chapter location in the original sort map
+            // rather than inferring from the $newChapter since that variable may be null
+            // due to other reasons (Visibility).
+            $newParent = $sortMapItem->parentChapterId ? $newChapter : $newBook;
+            if (!$newParent) {
+                return false;
+            }
+
+            $hasPageEditPermission = userCan('page-update', $model);
+            $newParentInRightLocation = ($newParent instanceof Book || ($newParent instanceof Chapter && $newParent->book_id === $newBook->id));
+            $newParentPermission = ($newParent instanceof Chapter) ? 'chapter-update' : 'book-update';
+            $hasNewParentPermission = userCan($newParentPermission, $newParent);
+
+            $hasDeletePermissionIfMoving = (!$hasNewParent || userCan('page-delete', $model));
+            $hasCreatePermissionIfMoving = (!$hasNewParent || userCan('page-create', $newParent));
+
+            $hasPermission = $hasCurrentParentPermission
+                && $newParentInRightLocation
+                && $hasNewParentPermission
+                && $hasPageEditPermission
+                && $hasDeletePermissionIfMoving
+                && $hasCreatePermissionIfMoving;
+
+            if (!$hasPermission) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Load models from the database into the given sort map.
+     *
+     * @return array<string, Entity>
+     */
+    protected function loadModelsFromSortMap(BookSortMap $sortMap): array
+    {
+        $modelMap = [];
+        $ids = [
+            'chapter' => [],
+            'page'    => [],
+            'book'    => [],
+        ];
+
+        foreach ($sortMap->all() as $sortMapItem) {
+            $ids[$sortMapItem->type][] = $sortMapItem->id;
+            $ids['book'][] = $sortMapItem->parentBookId;
+            if ($sortMapItem->parentChapterId) {
+                $ids['chapter'][] = $sortMapItem->parentChapterId;
+            }
+        }
+
+        $pages = $this->queries->pages->visibleForList()->whereIn('id', array_unique($ids['page']))->get();
+        /** @var Page $page */
+        foreach ($pages as $page) {
+            $modelMap['page:' . $page->id] = $page;
+            $ids['book'][] = $page->book_id;
+            if ($page->chapter_id) {
+                $ids['chapter'][] = $page->chapter_id;
+            }
+        }
+
+        $chapters = $this->queries->chapters->visibleForList()->whereIn('id', array_unique($ids['chapter']))->get();
+        /** @var Chapter $chapter */
+        foreach ($chapters as $chapter) {
+            $modelMap['chapter:' . $chapter->id] = $chapter;
+            $ids['book'][] = $chapter->book_id;
+        }
+
+        $books = $this->queries->books->visibleForList()->whereIn('id', array_unique($ids['book']))->get();
+        /** @var Book $book */
+        foreach ($books as $book) {
+            $modelMap['book:' . $book->id] = $book;
+        }
+
+        return $modelMap;
+    }
+}

app/Sorting/SortRule.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace BookStack\Sorting;
+
+use BookStack\Activity\Models\Loggable;
+use BookStack\Entities\Models\Book;
+use Carbon\Carbon;
+use Illuminate\Database\Eloquent\Collection;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+
+/**
+ * @property int $id
+ * @property string $name
+ * @property string $sequence
+ * @property Carbon $created_at
+ * @property Carbon $updated_at
+ */
+class SortRule extends Model implements Loggable
+{
+    use HasFactory;
+
+    /**
+     * @return SortRuleOperation[]
+     */
+    public function getOperations(): array
+    {
+        return SortRuleOperation::fromSequence($this->sequence);
+    }
+
+    /**
+     * @param SortRuleOperation[] $options
+     */
+    public function setOperations(array $options): void
+    {
+        $values = array_map(fn (SortRuleOperation $opt) => $opt->value, $options);
+        $this->sequence = implode(',', $values);
+    }
+
+    public function logDescriptor(): string
+    {
+        return "({$this->id}) {$this->name}";
+    }
+
+    public function getUrl(): string
+    {
+        return url("/settings/sorting/rules/{$this->id}");
+    }
+
+    public function books(): HasMany
+    {
+        return $this->hasMany(Book::class);
+    }
+
+    public static function allByName(): Collection
+    {
+        return static::query()
+            ->withCount('books')
+            ->orderBy('name', 'asc')
+            ->get();
+    }
+}

app/Sorting/SortRuleController.php

@@ -0,0 +1,114 @@
+<?php
+
+namespace BookStack\Sorting;
+
+use BookStack\Activity\ActivityType;
+use BookStack\Http\Controller;
+use Illuminate\Http\Request;
+
+class SortRuleController extends Controller
+{
+    public function __construct()
+    {
+        $this->middleware('can:settings-manage');
+    }
+
+    public function create()
+    {
+        $this->setPageTitle(trans('settings.sort_rule_create'));
+
+        return view('settings.sort-rules.create');
+    }
+
+    public function store(Request $request)
+    {
+        $this->validate($request, [
+            'name' => ['required', 'string', 'min:1', 'max:200'],
+            'sequence' => ['required', 'string', 'min:1'],
+        ]);
+
+        $operations = SortRuleOperation::fromSequence($request->input('sequence'));
+        if (count($operations) === 0) {
+            return redirect()->withInput()->withErrors(['sequence' => 'No operations set.']);
+        }
+
+        $rule = new SortRule();
+        $rule->name = $request->input('name');
+        $rule->setOperations($operations);
+        $rule->save();
+
+        $this->logActivity(ActivityType::SORT_RULE_CREATE, $rule);
+
+        return redirect('/settings/sorting');
+    }
+
+    public function edit(string $id)
+    {
+        $rule = SortRule::query()->findOrFail($id);
+
+        $this->setPageTitle(trans('settings.sort_rule_edit'));
+
+        return view('settings.sort-rules.edit', ['rule' => $rule]);
+    }
+
+    public function update(string $id, Request $request, BookSorter $bookSorter)
+    {
+        $this->validate($request, [
+            'name' => ['required', 'string', 'min:1', 'max:200'],
+            'sequence' => ['required', 'string', 'min:1'],
+        ]);
+
+        $rule = SortRule::query()->findOrFail($id);
+        $operations = SortRuleOperation::fromSequence($request->input('sequence'));
+        if (count($operations) === 0) {
+            return redirect($rule->getUrl())->withInput()->withErrors(['sequence' => 'No operations set.']);
+        }
+
+        $rule->name = $request->input('name');
+        $rule->setOperations($operations);
+        $changedSequence = $rule->isDirty('sequence');
+        $rule->save();
+
+        $this->logActivity(ActivityType::SORT_RULE_UPDATE, $rule);
+
+        if ($changedSequence) {
+            $bookSorter->runBookAutoSortForAllWithSet($rule);
+        }
+
+        return redirect('/settings/sorting');
+    }
+
+    public function destroy(string $id, Request $request)
+    {
+        $rule = SortRule::query()->findOrFail($id);
+        $confirmed = $request->input('confirm') === 'true';
+        $booksAssigned = $rule->books()->count();
+        $warnings = [];
+
+        if ($booksAssigned > 0) {
+            if ($confirmed) {
+                $rule->books()->update(['sort_rule_id' => null]);
+            } else {
+                $warnings[] = trans('settings.sort_rule_delete_warn_books', ['count' => $booksAssigned]);
+            }
+        }
+
+        $defaultBookSortSetting = intval(setting('sorting-book-default', '0'));
+        if ($defaultBookSortSetting === intval($id)) {
+            if ($confirmed) {
+                setting()->remove('sorting-book-default');
+            } else {
+                $warnings[] = trans('settings.sort_rule_delete_warn_default');
+            }
+        }
+
+        if (count($warnings) > 0) {
+            return redirect($rule->getUrl() . '#delete')->withErrors(['delete' => $warnings]);
+        }
+
+        $rule->delete();
+        $this->logActivity(ActivityType::SORT_RULE_DELETE, $rule);
+
+        return redirect('/settings/sorting');
+    }
+}

app/Sorting/SortRuleOperation.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace BookStack\Sorting;
+
+use Closure;
+use Illuminate\Support\Str;
+
+enum SortRuleOperation: string
+{
+    case NameAsc = 'name_asc';
+    case NameDesc = 'name_desc';
+    case NameNumericAsc = 'name_numeric_asc';
+    case NameNumericDesc = 'name_numeric_desc';
+    case CreatedDateAsc = 'created_date_asc';
+    case CreatedDateDesc = 'created_date_desc';
+    case UpdateDateAsc = 'updated_date_asc';
+    case UpdateDateDesc = 'updated_date_desc';
+    case ChaptersFirst = 'chapters_first';
+    case ChaptersLast = 'chapters_last';
+
+    /**
+     * Provide a translated label string for this option.
+     */
+    public function getLabel(): string
+    {
+        $key = $this->value;
+        $label = '';
+        if (str_ends_with($key, '_asc')) {
+            $key = substr($key, 0, -4);
+            $label = trans('settings.sort_rule_op_asc');
+        } elseif (str_ends_with($key, '_desc')) {
+            $key = substr($key, 0, -5);
+            $label = trans('settings.sort_rule_op_desc');
+        }
+
+        $label = trans('settings.sort_rule_op_' . $key) . ' ' . $label;
+        return trim($label);
+    }
+
+    public function getSortFunction(): callable
+    {
+        $camelValue = Str::camel($this->value);
+        return SortSetOperationComparisons::$camelValue(...);
+    }
+
+    /**
+     * @return SortRuleOperation[]
+     */
+    public static function allExcluding(array $operations): array
+    {
+        $all = SortRuleOperation::cases();
+        $filtered = array_filter($all, function (SortRuleOperation $operation) use ($operations) {
+            return !in_array($operation, $operations);
+        });
+        return array_values($filtered);
+    }
+
+    /**
+     * Create a set of operations from a string sequence representation.
+     * (values seperated by commas).
+     * @return SortRuleOperation[]
+     */
+    public static function fromSequence(string $sequence): array
+    {
+        $strOptions = explode(',', $sequence);
+        $options = array_map(fn ($val) => SortRuleOperation::tryFrom($val), $strOptions);
+        return array_filter($options);
+    }
+}

app/Sorting/SortSetOperationComparisons.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace BookStack\Sorting;
+
+use voku\helper\ASCII;
+use BookStack\Entities\Models\Chapter;
+use BookStack\Entities\Models\Entity;
+
+/**
+ * Sort comparison function for each of the possible SortSetOperation values.
+ * Method names should be camelCase names for the SortSetOperation enum value.
+ */
+class SortSetOperationComparisons
+{
+    public static function nameAsc(Entity $a, Entity $b): int
+    {
+        return strtolower(ASCII::to_transliterate($a->name, null)) <=> strtolower(ASCII::to_transliterate($b->name, null));
+    }
+
+    public static function nameDesc(Entity $a, Entity $b): int
+    {
+        return strtolower(ASCII::to_transliterate($b->name, null)) <=> strtolower(ASCII::to_transliterate($a->name, null));
+    }
+
+    public static function nameNumericAsc(Entity $a, Entity $b): int
+    {
+        $numRegex = '/^\d+(\.\d+)?/';
+        $aMatches = [];
+        $bMatches = [];
+        preg_match($numRegex, $a->name, $aMatches);
+        preg_match($numRegex, $b->name, $bMatches);
+        $aVal = floatval(($aMatches[0] ?? 0));
+        $bVal = floatval(($bMatches[0] ?? 0));
+
+        return $aVal <=> $bVal;
+    }
+
+    public static function nameNumericDesc(Entity $a, Entity $b): int
+    {
+        return -(static::nameNumericAsc($a, $b));
+    }
+
+    public static function createdDateAsc(Entity $a, Entity $b): int
+    {
+        return $a->created_at->unix() <=> $b->created_at->unix();
+    }
+
+    public static function createdDateDesc(Entity $a, Entity $b): int
+    {
+        return $b->created_at->unix() <=> $a->created_at->unix();
+    }
+
+    public static function updatedDateAsc(Entity $a, Entity $b): int
+    {
+        return $a->updated_at->unix() <=> $b->updated_at->unix();
+    }
+
+    public static function updatedDateDesc(Entity $a, Entity $b): int
+    {
+        return $b->updated_at->unix() <=> $a->updated_at->unix();
+    }
+
+    public static function chaptersFirst(Entity $a, Entity $b): int
+    {
+        return ($b instanceof Chapter ? 1 : 0) - (($a instanceof Chapter) ? 1 : 0);
+    }
+
+    public static function chaptersLast(Entity $a, Entity $b): int
+    {
+        return ($a instanceof Chapter ? 1 : 0) - (($b instanceof Chapter) ? 1 : 0);
+    }
+}

app/Sorting/SortUrl.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace BookStack\Sorting;
+
+/**
+ * Generate a URL with multiple parameters for sorting purposes.
+ * Works out the logic to set the correct sorting direction
+ * Discards empty parameters and allows overriding.
+ */
+class SortUrl
+{
+    public function __construct(
+        protected string $path,
+        protected array $data,
+        protected array $overrideData = []
+    ) {
+    }
+
+    public function withOverrideData(array $overrideData = []): self
+    {
+        return new self($this->path, $this->data, $overrideData);
+    }
+
+    public function build(): string
+    {
+        $queryStringSections = [];
+        $queryData = array_merge($this->data, $this->overrideData);
+
+        // Change sorting direction if already sorted on current attribute
+        if (isset($this->overrideData['sort']) && $this->overrideData['sort'] === $this->data['sort']) {
+            $queryData['order'] = ($this->data['order'] === 'asc') ? 'desc' : 'asc';
+        } elseif (isset($this->overrideData['sort'])) {
+            $queryData['order'] = 'asc';
+        }
+
+        foreach ($queryData as $name => $value) {
+            $trimmedVal = trim($value);
+            if ($trimmedVal !== '') {
+                $queryStringSections[] = urlencode($name) . '=' . urlencode($trimmedVal);
+            }
+        }
+
+        if (count($queryStringSections) === 0) {
+            return url($this->path);
+        }
+
+        return url($this->path . '?' . implode('&', $queryStringSections));
+    }
+}

app/Theming/ThemeController.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace BookStack\Theming;
+
+use BookStack\Facades\Theme;
+use BookStack\Http\Controller;
+use BookStack\Util\FilePathNormalizer;
+
+class ThemeController extends Controller
+{
+    /**
+     * Serve a public file from the configured theme.
+     */
+    public function publicFile(string $theme, string $path)
+    {
+        $cleanPath = FilePathNormalizer::normalize($path);
+        if ($theme !== Theme::getTheme() || !$cleanPath) {
+            abort(404);
+        }
+
+        $filePath = theme_path("public/{$cleanPath}");
+        if (!file_exists($filePath)) {
+            abort(404);
+        }
+
+        $response = $this->download()->streamedFileInline($filePath);
+        $response->setMaxAge(86400);
+
+        return $response;
+    }
+}

app/Theming/ThemeService.php

@@ -15,6 +15,15 @@ class ThemeService
      */
     protected array $listeners = [];
 
+    /**
+     * Get the currently configured theme.
+     * Returns an empty string if not configured.
+     */
+    public function getTheme(): string
+    {
+        return config('view.theme') ?? '';
+    }
+
     /**
      * Listen to a given custom theme event,
      * setting up the action to be ran when the event occurs.
@@ -84,7 +93,7 @@ class ThemeService
     /**
      * @see SocialDriverManager::addSocialDriver
      */
-    public function addSocialDriver(string $driverName, array $config, string $socialiteHandler, callable $configureForRedirect = null): void
+    public function addSocialDriver(string $driverName, array $config, string $socialiteHandler, ?callable $configureForRedirect = null): void
     {
         $driverManager = app()->make(SocialDriverManager::class);
         $driverManager->addSocialDriver($driverName, $config, $socialiteHandler, $configureForRedirect);

app/Translation/LocaleManager.php

@@ -47,8 +47,10 @@ class LocaleManager
         'ja'          => 'ja',
         'ka'          => 'ka_GE',
         'ko'          => 'ko_KR',
+        'ku'          => 'ku_TR',
         'lt'          => 'lt_LT',
         'lv'          => 'lv_LV',
+        'ne'          => 'ne_NP',
         'nb'          => 'nb_NO',
         'nl'          => 'nl_NL',
         'nn'          => 'nn_NO',

app/Uploads/FileStorage.php

@@ -3,13 +3,12 @@
 namespace BookStack\Uploads;
 
 use BookStack\Exceptions\FileUploadException;
+use BookStack\Util\FilePathNormalizer;
 use Exception;
 use Illuminate\Contracts\Filesystem\Filesystem as Storage;
-use Illuminate\Filesystem\FilesystemAdapter;
 use Illuminate\Filesystem\FilesystemManager;
 use Illuminate\Support\Facades\Log;
 use Illuminate\Support\Str;
-use League\Flysystem\WhitespacePathNormalizer;
 use Symfony\Component\HttpFoundation\File\UploadedFile;
 
 class FileStorage
@@ -121,12 +120,13 @@ class FileStorage
      */
     protected function adjustPathForStorageDisk(string $path): string
     {
-        $path = (new WhitespacePathNormalizer())->normalizePath(str_replace('uploads/files/', '', $path));
+        $trimmed = str_replace('uploads/files/', '', $path);
+        $normalized = FilePathNormalizer::normalize($trimmed);
 
         if ($this->getStorageDiskName() === 'local_secure_attachments') {
-            return $path;
+            return $normalized;
         }
 
-        return 'uploads/files/' . $path;
+        return 'uploads/files/' . $normalized;
     }
 }

app/Uploads/ImageRepo.php

@@ -49,9 +49,9 @@ class ImageRepo
         string $type,
         int $page = 0,
         int $pageSize = 24,
-        int $uploadedTo = null,
-        string $search = null,
-        callable $whereClause = null
+        ?int $uploadedTo = null,
+        ?string $search = null,
+        ?callable $whereClause = null
     ): array {
         $imageQuery = Image::query()->where('type', '=', strtolower($type));
 
@@ -91,7 +91,7 @@ class ImageRepo
             $parentFilter = function (Builder $query) use ($filterType, $contextPage) {
                 if ($filterType === 'page') {
                     $query->where('uploaded_to', '=', $contextPage->id);
-                } elseif ($filterType === 'book') {
+                } else if ($filterType === 'book') {
                     $validPageIds = $contextPage->book->pages()
                         ->scopes('visible')
                         ->pluck('id')
@@ -109,8 +109,14 @@ class ImageRepo
      *
      * @throws ImageUploadException
      */
-    public function saveNew(UploadedFile $uploadFile, string $type, int $uploadedTo = 0, int $resizeWidth = null, int $resizeHeight = null, bool $keepRatio = true): Image
-    {
+    public function saveNew(
+        UploadedFile $uploadFile,
+        string $type,
+        int $uploadedTo = 0,
+        ?int $resizeWidth = null,
+        ?int $resizeHeight = null,
+        bool $keepRatio = true
+    ): Image {
         $image = $this->imageService->saveNewFromUpload($uploadFile, $type, $uploadedTo, $resizeWidth, $resizeHeight, $keepRatio);
 
         if ($type !== 'system') {
@@ -184,7 +190,7 @@ class ImageRepo
      *
      * @throws Exception
      */
-    public function destroyImage(Image $image = null): void
+    public function destroyImage(?Image $image = null): void
     {
         if ($image) {
             $this->imageService->destroy($image);

app/Uploads/ImageResizer.php

@@ -6,6 +6,7 @@ use BookStack\Exceptions\ImageUploadException;
 use Exception;
 use GuzzleHttp\Psr7\Utils;
 use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\Log;
 use Intervention\Image\Decoders\BinaryImageDecoder;
 use Intervention\Image\Drivers\Gd\Decoders\NativeObjectDecoder;
 use Intervention\Image\Drivers\Gd\Driver;
@@ -93,8 +94,8 @@ class ImageResizer
 
         $imageData = $disk->get($imagePath);
 
-        // Do not resize apng images where we're not cropping
-        if ($keepRatio && $this->isApngData($image, $imageData)) {
+        // Do not resize animated images where we're not cropping
+        if ($keepRatio && $this->isAnimated($image, $imageData)) {
             Cache::put($thumbCacheKey, $image->path, static::THUMBNAIL_CACHE_TIME);
 
             return $this->storage->getPublicUrl($image->path);
@@ -158,7 +159,10 @@ class ImageResizer
      */
     protected function interventionFromImageData(string $imageData, ?string $fileType): InterventionImage
     {
-        $manager = new ImageManager(new Driver());
+        $manager = new ImageManager(
+            new Driver(),
+            autoOrientation: false,
+        );
 
         // Ensure gif images are decoded natively instead of deferring to intervention GIF
         // handling since we don't need the added animation support.
@@ -237,15 +241,50 @@ class ImageResizer
     /**
      * Check if the given image and image data is apng.
      */
-    protected function isApngData(Image $image, string &$imageData): bool
+    protected function isApngData(string &$imageData): bool
     {
-        $isPng = strtolower(pathinfo($image->path, PATHINFO_EXTENSION)) === 'png';
-        if (!$isPng) {
-            return false;
-        }
-
         $initialHeader = substr($imageData, 0, strpos($imageData, 'IDAT'));
 
         return str_contains($initialHeader, 'acTL');
     }
+
+    /**
+     * Check if the given avif image data represents an animated image.
+     * This is based up the answer here: https://stackoverflow.com/a/79457313
+     */
+    protected function isAnimatedAvifData(string &$imageData): bool
+    {
+        $stszPos = strpos($imageData, 'stsz');
+        if ($stszPos === false) {
+            return false;
+        }
+
+        // Look 12 bytes after the start of 'stsz'
+        $start = $stszPos + 12;
+        $end = $start + 4;
+        if ($end > strlen($imageData) - 1) {
+            return false;
+        }
+
+        $data = substr($imageData, $start, 4);
+        $count = unpack('Nvalue', $data)['value'];
+        return $count > 1;
+    }
+
+    /**
+     * Check if the given image is animated.
+     */
+    protected function isAnimated(Image $image, string &$imageData): bool
+    {
+        $extension = strtolower(pathinfo($image->path, PATHINFO_EXTENSION));
+        if ($extension === 'png') {
+            return $this->isApngData($imageData);
+        }
+
+        if ($extension === 'avif') {
+            return $this->isAnimatedAvifData($imageData);
+        }
+
+        return false;
+    }
 }

app/Uploads/ImageService.php

@@ -13,7 +13,7 @@ use Symfony\Component\HttpFoundation\StreamedResponse;
 
 class ImageService
 {
-    protected static array $supportedExtensions = ['jpg', 'jpeg', 'png', 'gif', 'webp'];
+    protected static array $supportedExtensions = ['jpg', 'jpeg', 'png', 'gif', 'webp', 'avif'];
 
     public function __construct(
         protected ImageStorage $storage,
@@ -31,8 +31,8 @@ class ImageService
         UploadedFile $uploadedFile,
         string $type,
         int $uploadedTo = 0,
-        int $resizeWidth = null,
-        int $resizeHeight = null,
+        ?int $resizeWidth = null,
+        ?int $resizeHeight = null,
         bool $keepRatio = true,
         string $imageName = '',
     ): Image {

app/Uploads/ImageStorageDisk.php

@@ -2,9 +2,12 @@
 
 namespace BookStack\Uploads;
 
+use BookStack\Util\FilePathNormalizer;
 use Illuminate\Contracts\Filesystem\Filesystem;
 use Illuminate\Filesystem\FilesystemAdapter;
-use League\Flysystem\WhitespacePathNormalizer;
+use Illuminate\Support\Facades\Log;
+use League\Flysystem\UnableToSetVisibility;
+use League\Flysystem\Visibility;
 use Symfony\Component\HttpFoundation\StreamedResponse;
 
 class ImageStorageDisk
@@ -30,13 +33,14 @@ class ImageStorageDisk
      */
     protected function adjustPathForDisk(string $path): string
     {
-        $path = (new WhitespacePathNormalizer())->normalizePath(str_replace('uploads/images/', '', $path));
+        $trimmed = str_replace('uploads/images/', '', $path);
+        $normalized = FilePathNormalizer::normalize($trimmed);
 
         if ($this->usingSecureImages()) {
-            return $path;
+            return $normalized;
         }
 
-        return 'uploads/images/' . $path;
+        return 'uploads/images/' . $normalized;
     }
 
     /**
@@ -73,12 +77,19 @@ class ImageStorageDisk
         $path = $this->adjustPathForDisk($path);
         $this->filesystem->put($path, $data);
 
-        // Set visibility when a non-AWS-s3, s3-like storage option is in use.
-        // Done since this call can break s3-like services but desired for other image stores.
-        // Attempting to set ACL during above put request requires different permissions
-        // hence would technically be a breaking change for actual s3 usage.
+        // Set public visibility to ensure public access on S3, or that the file is accessible
+        // to other processes (like web-servers) for local file storage options.
+        // We avoid attempting this for (non-AWS) s3-like systems (even in a try-catch) as
+        // we've always avoided setting permissions for s3-like due to potential issues,
+        // with docs advising setting pre-configured permissions instead.
+        // We also don't do this as the default filesystem/driver level as that can technically
+        // require different ACLs for S3, and this provides us more logical control.
         if ($makePublic && !$this->isS3Like()) {
-            $this->filesystem->setVisibility($path, 'public');
+            try {
+                $this->filesystem->setVisibility($path, Visibility::PUBLIC);
+            } catch (UnableToSetVisibility $e) {
+                Log::warning("Unable to set visibility for image upload with relative path: {$path}");
+            }
         }
     }
 

app/Uploads/UserAvatars.php

@@ -5,6 +5,7 @@ namespace BookStack\Uploads;
 use BookStack\Exceptions\HttpFetchException;
 use BookStack\Http\HttpRequestService;
 use BookStack\Users\Models\User;
+use BookStack\Util\WebSafeMimeSniffer;
 use Exception;
 use GuzzleHttp\Psr7\Request;
 use Illuminate\Support\Facades\Log;
@@ -53,6 +54,33 @@ class UserAvatars
         }
     }
 
+    /**
+     * Assign a new avatar image to the given user by fetching from a remote URL.
+     */
+    public function assignToUserFromUrl(User $user, string $avatarUrl): void
+    {
+        try {
+            $this->destroyAllForUser($user);
+            $imageData = $this->getAvatarImageData($avatarUrl);
+
+            $mime = (new WebSafeMimeSniffer())->sniff($imageData);
+            [$format, $type] = explode('/', $mime, 2);
+            if ($format !== 'image' || !ImageService::isExtensionSupported($type)) {
+                return;
+            }
+
+            $avatar = $this->createAvatarImageFromData($user, $imageData, $type);
+            $user->avatar()->associate($avatar);
+            $user->save();
+        } catch (Exception $e) {
+            Log::error('Failed to save user avatar image from URL', [
+                'exception' => $e->getMessage(),
+                'url'       => $avatarUrl,
+                'user_id'   => $user->id,
+            ]);
+        }
+    }
+
     /**
      * Destroy all user avatars uploaded to the given user.
      */
@@ -105,7 +133,7 @@ class UserAvatars
     }
 
     /**
-     * Gets an image from url and returns it as a string of image data.
+     * Get an image from a URL and return it as a string of image data.
      *
      * @throws HttpFetchException
      */
@@ -113,7 +141,19 @@ class UserAvatars
     {
         try {
             $client = $this->http->buildClient(5);
-            $response = $client->sendRequest(new Request('GET', $url));
+            $responseCount = 0;
+
+            do {
+                $response = $client->sendRequest(new Request('GET', $url));
+                $responseCount++;
+                $isRedirect = ($response->getStatusCode() === 301 || $response->getStatusCode() === 302);
+                $url = $response->getHeader('Location')[0] ?? '';
+            } while ($responseCount < 3 && $isRedirect && is_string($url) && str_starts_with($url, 'http'));
+
+            if ($responseCount === 3) {
+                throw new HttpFetchException("Failed to fetch image, max redirect limit of 3 tries reached. Last fetched URL: {$url}");
+            }
+
             if ($response->getStatusCode() !== 200) {
                 throw new HttpFetchException(trans('errors.cannot_get_image_from_url', ['url' => $url]));
             }