Build out core attachments API controller

Related to #2942

app/Http/Controllers/Api/AttachmentApiController.php

@@ -0,0 +1,155 @@
+<?php
+
+namespace BookStack\Http\Controllers\Api;
+
+use BookStack\Entities\Models\Page;
+use BookStack\Exceptions\FileUploadException;
+use BookStack\Uploads\Attachment;
+use BookStack\Uploads\AttachmentService;
+use Exception;
+use Illuminate\Contracts\Filesystem\FileNotFoundException;
+use Illuminate\Http\Request;
+use Illuminate\Validation\ValidationException;
+
+class AttachmentApiController extends ApiController
+{
+    protected $attachmentService;
+
+    protected $rules = [
+        'create' => [
+            'name' => 'required|min:1|max:255|string',
+            'uploaded_to' => 'required|integer|exists:pages,id',
+            'file' => 'required_without:link|file',
+            'link' => 'required_without:file|min:1|max:255|safe_url'
+        ],
+        'update' => [
+            'name' => 'min:1|max:255|string',
+            'uploaded_to' => 'integer|exists:pages,id',
+            'file' => 'link|file',
+            'link' => 'file|min:1|max:255|safe_url'
+        ],
+    ];
+
+    public function __construct(AttachmentService $attachmentService)
+    {
+        $this->attachmentService = $attachmentService;
+    }
+
+    /**
+     * Get a listing of attachments visible to the user.
+     * The external property indicates whether the attachment is simple a link.
+     * A false value for the external property would indicate a file upload.
+     */
+    public function list()
+    {
+        return $this->apiListingResponse(Attachment::visible(), [
+            'id', 'name', 'extension', 'uploaded_to', 'external', 'order', 'created_at', 'updated_at', 'created_by', 'updated_by',
+        ]);
+    }
+
+    /**
+     * Create a new attachment in the system.
+     * An uploaded_to value must be provided containing an ID of the page
+     * that this upload will be related to.
+     *
+     * @throws ValidationException
+     * @throws FileUploadException
+     */
+    public function create(Request $request)
+    {
+        $this->checkPermission('attachment-create-all');
+        $requestData = $this->validate($request, $this->rules['create']);
+
+        $pageId = $request->get('uploaded_to');
+        $page = Page::visible()->findOrFail($pageId);
+        $this->checkOwnablePermission('page-update', $page);
+
+        if ($request->hasFile('file')) {
+            $uploadedFile = $request->file('file');
+            $attachment = $this->attachmentService->saveNewUpload($uploadedFile, $page->id);
+        } else {
+            $attachment = $this->attachmentService->saveNewFromLink(
+                $requestData['name'], $requestData['link'], $page->id
+            );
+        }
+
+        $this->attachmentService->updateFile($attachment, $requestData);
+        return response()->json($attachment);
+    }
+
+    /**
+     * Get the details & content of a single attachment of the given ID.
+     * The attachment link or file content is provided via a 'content' property.
+     * For files the content will be base64 encoded.
+     *
+     * @throws FileNotFoundException
+     */
+    public function read(string $id)
+    {
+        /** @var Attachment $attachment */
+        $attachment = Attachment::visible()->findOrFail($id);
+
+        $attachment->setAttribute('links', [
+            'html'     => $attachment->htmlLink(),
+            'markdown' => $attachment->markdownLink(),
+        ]);
+
+        if (!$attachment->external) {
+            $attachmentContents = $this->attachmentService->getAttachmentFromStorage($attachment);
+            $attachment->setAttribute('content', base64_encode($attachmentContents));
+        } else {
+            $attachment->setAttribute('content', $attachment->path);
+        }
+
+        return response()->json($attachment);
+    }
+
+    /**
+     * Update the details of a single attachment.
+     *
+     * @throws ValidationException
+     * @throws FileUploadException
+     */
+    public function update(Request $request, string $id)
+    {
+        $requestData = $this->validate($request, $this->rules['update']);
+        /** @var Attachment $attachment */
+        $attachment = Attachment::visible()->findOrFail($id);
+
+        $page = $attachment->page;
+        if ($requestData['uploaded_to'] ?? false) {
+            $pageId = $request->get('uploaded_to');
+            $page = Page::visible()->findOrFail($pageId);
+            $attachment->uploaded_to = $requestData['uploaded_to'];
+        }
+
+        $this->checkOwnablePermission('page-view', $page);
+        $this->checkOwnablePermission('page-update', $page);
+        $this->checkOwnablePermission('attachment-update', $attachment);
+
+        if ($request->hasFile('file')) {
+            $uploadedFile = $request->file('file');
+            $attachment = $this->attachmentService->saveUpdatedUpload($uploadedFile, $page->id);
+        }
+
+        $this->attachmentService->updateFile($attachment, $requestData);
+        return response()->json($attachment);
+    }
+
+    /**
+     * Delete an attachment of the given ID.
+     *
+     * @throws Exception
+     */
+    public function delete(string $id)
+    {
+        /** @var Attachment $attachment */
+        $attachment = Attachment::visible()->findOrFail($id);
+        $this->checkOwnablePermission('attachment-delete', $attachment);
+
+        $this->attachmentService->deleteFile($attachment);
+
+        return response('', 204);
+    }
+
+}

app/Http/Controllers/AttachmentController.php

@@ -121,9 +121,9 @@ class AttachmentController extends Controller
             ]), 422);
         }
 
-        $this->checkOwnablePermission('view', $attachment->page);
+        $this->checkOwnablePermission('page-view', $attachment->page);
         $this->checkOwnablePermission('page-update', $attachment->page);
-        $this->checkOwnablePermission('attachment-create', $attachment);
+        $this->checkOwnablePermission('attachment-update', $attachment);
 
         $attachment = $this->attachmentService->updateFile($attachment, [
             'name' => $request->get('attachment_edit_name'),

app/Uploads/Attachment.php

@@ -2,18 +2,24 @@
 
 namespace BookStack\Uploads;
 
+use BookStack\Auth\Permissions\PermissionService;
+use BookStack\Entities\Models\Entity;
 use BookStack\Entities\Models\Page;
 use BookStack\Model;
 use BookStack\Traits\HasCreatorAndUpdater;
+use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
 
 /**
- * @property int id
- * @property string name
- * @property string path
- * @property string extension
- * @property ?Page page
- * @property bool external
+ * @property int $id
+ * @property string $name
+ * @property string $path
+ * @property string $extension
+ * @property ?Page $page
+ * @property bool $external
+ * @property int $uploaded_to
+ *
+ * @method static Entity|Builder visible()
  */
 class Attachment extends Model
 {
@@ -70,4 +76,18 @@ class Attachment extends Model
     {
         return '[' . $this->name . '](' . $this->getUrl() . ')';
     }
+
+    /**
+     * Scope the query to those attachments that are visible based upon related page permissions.
+     */
+    public function scopeVisible(): string
+    {
+        $permissionService = app()->make(PermissionService::class);
+        return $permissionService->filterRelatedEntity(
+            Page::class,
+            Attachment::query(),
+            'attachments',
+            'uploaded_to'
+        );
+    }
 }

app/Uploads/AttachmentService.php

@@ -78,18 +78,18 @@ class AttachmentService
      *
      * @throws FileUploadException
      */
-    public function saveNewUpload(UploadedFile $uploadedFile, int $page_id): Attachment
+    public function saveNewUpload(UploadedFile $uploadedFile, int $pageId): Attachment
     {
         $attachmentName = $uploadedFile->getClientOriginalName();
         $attachmentPath = $this->putFileInStorage($uploadedFile);
-        $largestExistingOrder = Attachment::query()->where('uploaded_to', '=', $page_id)->max('order');
+        $largestExistingOrder = Attachment::query()->where('uploaded_to', '=', $pageId)->max('order');
 
         /** @var Attachment $attachment */
         $attachment = Attachment::query()->forceCreate([
             'name'        => $attachmentName,
             'path'        => $attachmentPath,
             'extension'   => $uploadedFile->getClientOriginalExtension(),
-            'uploaded_to' => $page_id,
+            'uploaded_to' => $pageId,
             'created_by'  => user()->id,
             'updated_by'  => user()->id,
             'order'       => $largestExistingOrder + 1,
@@ -159,8 +159,9 @@ class AttachmentService
     public function updateFile(Attachment $attachment, array $requestData): Attachment
     {
         $attachment->name = $requestData['name'];
+        $link = trim($requestData['link'] ?? '');
 
-        if (isset($requestData['link']) && trim($requestData['link']) !== '') {
+        if (!empty($link)) {
             $attachment->path = $requestData['link'];
             if (!$attachment->external) {
                 $this->deleteFileInStorage($attachment);
@@ -180,13 +181,10 @@ class AttachmentService
      */
     public function deleteFile(Attachment $attachment)
     {
-        if ($attachment->external) {
-            $attachment->delete();
-
-            return;
+        if (!$attachment->external) {
+            $this->deleteFileInStorage($attachment);
         }
 
-        $this->deleteFileInStorage($attachment);
         $attachment->delete();
     }
 

routes/api.php

@@ -7,6 +7,12 @@
  */
 Route::get('docs.json', 'ApiDocsController@json');
 
+Route::get('attachments', 'AttachmentApiController@list');
+Route::post('attachments', 'AttachmentApiController@create');
+Route::get('attachments/{id}', 'AttachmentApiController@read');
+Route::put('attachments/{id}', 'AttachmentApiController@update');
+Route::delete('attachments/{id}', 'AttachmentApiController@delete');
+
 Route::get('books', 'BookApiController@list');
 Route::post('books', 'BookApiController@create');
 Route::get('books/{id}', 'BookApiController@read');