Merge branch 'recycle_bin_api_endpoints' into development

app/Entities/Models/Deletion.php

@@ -10,10 +10,16 @@ use Illuminate\Database\Eloquent\Relations\BelongsTo;
 use Illuminate\Database\Eloquent\Relations\MorphTo;
 
 /**
+ * @property int $id
+ * @property int $deleted_by
+ * @property string $deletable_type
+ * @property int $deletable_id
  * @property Deletable $deletable
  */
 class Deletion extends Model implements Loggable
 {
+    protected $hidden = [];
+
     /**
      * Get the related deletable record.
      */

app/Entities/Repos/DeletionRepo.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace BookStack\Entities\Repos;
+
+use BookStack\Actions\ActivityType;
+use BookStack\Entities\Models\Deletion;
+use BookStack\Entities\Tools\TrashCan;
+use BookStack\Facades\Activity;
+
+class DeletionRepo
+{
+    private TrashCan $trashCan;
+
+    public function __construct(TrashCan $trashCan)
+    {
+        $this->trashCan = $trashCan;
+    }
+
+    public function restore(int $id): int
+    {
+        /** @var Deletion $deletion */
+        $deletion = Deletion::query()->findOrFail($id);
+        Activity::add(ActivityType::RECYCLE_BIN_RESTORE, $deletion);
+
+        return $this->trashCan->restoreFromDeletion($deletion);
+    }
+
+    public function destroy(int $id): int
+    {
+        /** @var Deletion $deletion */
+        $deletion = Deletion::query()->findOrFail($id);
+        Activity::add(ActivityType::RECYCLE_BIN_DESTROY, $deletion);
+
+        return $this->trashCan->destroyFromDeletion($deletion);
+    }
+}

app/Http/Controllers/Api/RecycleBinApiController.php

@@ -0,0 +1,90 @@
+<?php
+
+namespace BookStack\Http\Controllers\Api;
+
+use BookStack\Entities\Models\Book;
+use BookStack\Entities\Models\BookChild;
+use BookStack\Entities\Models\Chapter;
+use BookStack\Entities\Models\Deletion;
+use BookStack\Entities\Repos\DeletionRepo;
+use Closure;
+use Illuminate\Database\Eloquent\Builder;
+
+class RecycleBinApiController extends ApiController
+{
+    public function __construct()
+    {
+        $this->middleware(function ($request, $next) {
+            $this->checkPermission('settings-manage');
+            $this->checkPermission('restrictions-manage-all');
+
+            return $next($request);
+        });
+    }
+
+    /**
+     * Get a top-level listing of the items in the recycle bin.
+     * The "deletable" property will reflect the main item deleted.
+     * For books and chapters, counts of child pages/chapters will
+     * be loaded within this "deletable" data.
+     * For chapters & pages, the parent item will be loaded within this "deletable" data.
+     * Requires permission to manage both system settings and permissions.
+     */
+    public function list()
+    {
+        return $this->apiListingResponse(Deletion::query()->with('deletable'), [
+            'id',
+            'deleted_by',
+            'created_at',
+            'updated_at',
+            'deletable_type',
+            'deletable_id',
+        ], [Closure::fromCallable([$this, 'listFormatter'])]);
+    }
+
+    /**
+     * Restore a single deletion from the recycle bin.
+     * Requires permission to manage both system settings and permissions.
+     */
+    public function restore(DeletionRepo $deletionRepo, string $deletionId)
+    {
+        $restoreCount = $deletionRepo->restore(intval($deletionId));
+
+        return response()->json(['restore_count' => $restoreCount]);
+    }
+
+    /**
+     * Remove a single deletion from the recycle bin.
+     * Use this endpoint carefully as it will entirely remove the underlying deleted items from the system.
+     * Requires permission to manage both system settings and permissions.
+     */
+    public function destroy(DeletionRepo $deletionRepo, string $deletionId)
+    {
+        $deleteCount = $deletionRepo->destroy(intval($deletionId));
+
+        return response()->json(['delete_count' => $deleteCount]);
+    }
+
+    /**
+     * Load some related details for the deletion listing.
+     */
+    protected function listFormatter(Deletion $deletion)
+    {
+        $deletable = $deletion->deletable;
+        $withTrashedQuery = fn(Builder $query) => $query->withTrashed();
+
+        if ($deletable instanceof BookChild) {
+            $parent = $deletable->getParent();
+            $parent->setAttribute('type', $parent->getType());
+            $deletable->setRelation('parent', $parent);
+        }
+
+        if ($deletable instanceof Book || $deletable instanceof Chapter) {
+            $countsToLoad = ['pages' => $withTrashedQuery];
+            if ($deletable instanceof Book) {
+                $countsToLoad['chapters'] = $withTrashedQuery;
+            }
+            $deletable->loadCount($countsToLoad);
+        }
+    }
+}

app/Http/Controllers/RecycleBinController.php

@@ -5,6 +5,7 @@ namespace BookStack\Http\Controllers;
 use BookStack\Actions\ActivityType;
 use BookStack\Entities\Models\Deletion;
 use BookStack\Entities\Models\Entity;
+use BookStack\Entities\Repos\DeletionRepo;
 use BookStack\Entities\Tools\TrashCan;
 
 class RecycleBinController extends Controller
@@ -73,12 +74,9 @@ class RecycleBinController extends Controller
      *
      * @throws \Exception
      */
-    public function restore(string $id)
+    public function restore(DeletionRepo $deletionRepo, string $id)
     {
-        /** @var Deletion $deletion */
-        $deletion = Deletion::query()->findOrFail($id);
-        $this->logActivity(ActivityType::RECYCLE_BIN_RESTORE, $deletion);
-        $restoreCount = (new TrashCan())->restoreFromDeletion($deletion);
+        $restoreCount = $deletionRepo->restore((int) $id);
 
         $this->showSuccessNotification(trans('settings.recycle_bin_restore_notification', ['count' => $restoreCount]));
 
@@ -103,12 +101,9 @@ class RecycleBinController extends Controller
      *
      * @throws \Exception
      */
-    public function destroy(string $id)
+    public function destroy(DeletionRepo $deletionRepo, string $id)
     {
-        /** @var Deletion $deletion */
-        $deletion = Deletion::query()->findOrFail($id);
-        $this->logActivity(ActivityType::RECYCLE_BIN_DESTROY, $deletion);
-        $deleteCount = (new TrashCan())->destroyFromDeletion($deletion);
+        $deleteCount = $deletionRepo->destroy((int) $id);
 
         $this->showSuccessNotification(trans('settings.recycle_bin_destroy_notification', ['count' => $deleteCount]));
 

app/Providers/AppServiceProvider.php

@@ -51,12 +51,12 @@ class AppServiceProvider extends ServiceProvider
         // Allow longer string lengths after upgrade to utf8mb4
         Schema::defaultStringLength(191);
 
-        // Set morph-map due to namespace changes
-        Relation::morphMap([
-            'BookStack\\Bookshelf' => Bookshelf::class,
-            'BookStack\\Book'      => Book::class,
-            'BookStack\\Chapter'   => Chapter::class,
-            'BookStack\\Page'      => Page::class,
+        // Set morph-map for our relations to friendlier aliases
+        Relation::enforceMorphMap([
+            'bookshelf' => Bookshelf::class,
+            'book'      => Book::class,
+            'chapter'   => Chapter::class,
+            'page'      => Page::class,
         ]);
 
         // View Composers