Merge pull request #2986 from BookStackApp/attachments_api

Attachments API
This commit is contained in:
Dan Brown 2021-10-20 10:46:35 +01:00 committed by GitHub
commit 7bbcaa7cbc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 644 additions and 23 deletions

View File

@ -0,0 +1,162 @@
<?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' => 'file',
'link' => '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.
*
* If you're uploading a file the POST data should be provided via
* a multipart/form-data type request instead of JSON.
*
* @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()
->with(['createdBy', 'updatedBy'])
->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.
* As per the create endpoint, if a file is being provided as the attachment content
* the request should be formatted as a multipart/form-data request instead of JSON.
*
* @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, $attachment);
}
$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);
}
}

View File

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

View File

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

View File

@ -78,18 +78,18 @@ class AttachmentService
* *
* @throws FileUploadException * @throws FileUploadException
*/ */
public function saveNewUpload(UploadedFile $uploadedFile, int $page_id): Attachment public function saveNewUpload(UploadedFile $uploadedFile, int $pageId): Attachment
{ {
$attachmentName = $uploadedFile->getClientOriginalName(); $attachmentName = $uploadedFile->getClientOriginalName();
$attachmentPath = $this->putFileInStorage($uploadedFile); $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 */ /** @var Attachment $attachment */
$attachment = Attachment::query()->forceCreate([ $attachment = Attachment::query()->forceCreate([
'name' => $attachmentName, 'name' => $attachmentName,
'path' => $attachmentPath, 'path' => $attachmentPath,
'extension' => $uploadedFile->getClientOriginalExtension(), 'extension' => $uploadedFile->getClientOriginalExtension(),
'uploaded_to' => $page_id, 'uploaded_to' => $pageId,
'created_by' => user()->id, 'created_by' => user()->id,
'updated_by' => user()->id, 'updated_by' => user()->id,
'order' => $largestExistingOrder + 1, 'order' => $largestExistingOrder + 1,
@ -159,18 +159,19 @@ class AttachmentService
public function updateFile(Attachment $attachment, array $requestData): Attachment public function updateFile(Attachment $attachment, array $requestData): Attachment
{ {
$attachment->name = $requestData['name']; $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) { if (!$attachment->external) {
$this->deleteFileInStorage($attachment); $this->deleteFileInStorage($attachment);
$attachment->external = true; $attachment->external = true;
$attachment->extension = '';
} }
$attachment->path = $requestData['link'];
} }
$attachment->save(); $attachment->save();
return $attachment->refresh();
return $attachment;
} }
/** /**
@ -180,13 +181,10 @@ class AttachmentService
*/ */
public function deleteFile(Attachment $attachment) public function deleteFile(Attachment $attachment)
{ {
if ($attachment->external) { if (!$attachment->external) {
$attachment->delete(); $this->deleteFileInStorage($attachment);
return;
} }
$this->deleteFileInStorage($attachment);
$attachment->delete(); $attachment->delete();
} }

View File

@ -0,0 +1,5 @@
{
"name": "My uploaded attachment",
"uploaded_to": 8,
"link": "https://link.example.com"
}

View File

@ -0,0 +1,5 @@
{
"name": "My updated attachment",
"uploaded_to": 4,
"link": "https://link.example.com/updated"
}

View File

@ -0,0 +1,12 @@
{
"id": 5,
"name": "My uploaded attachment",
"extension": "",
"uploaded_to": 8,
"external": true,
"order": 2,
"created_by": 1,
"updated_by": 1,
"created_at": "2021-10-20 06:35:46",
"updated_at": "2021-10-20 06:35:46"
}

View File

@ -0,0 +1,29 @@
{
"data": [
{
"id": 3,
"name": "datasheet.pdf",
"extension": "pdf",
"uploaded_to": 8,
"external": false,
"order": 1,
"created_at": "2021-10-11 06:18:49",
"updated_at": "2021-10-20 06:31:10",
"created_by": 1,
"updated_by": 1
},
{
"id": 4,
"name": "Cat reference",
"extension": "",
"uploaded_to": 9,
"external": true,
"order": 1,
"created_at": "2021-10-20 06:30:11",
"updated_at": "2021-10-20 06:30:11",
"created_by": 1,
"updated_by": 1
}
],
"total": 2
}

View File

@ -0,0 +1,25 @@
{
"id": 5,
"name": "My link attachment",
"extension": "",
"uploaded_to": 4,
"external": true,
"order": 2,
"created_by": {
"id": 1,
"name": "Admin",
"slug": "admin"
},
"updated_by": {
"id": 1,
"name": "Admin",
"slug": "admin"
},
"created_at": "2021-10-20 06:35:46",
"updated_at": "2021-10-20 06:37:11",
"links": {
"html": "<a target=\"_blank\" href=\"https://bookstack.local/attachments/5\">My updated attachment</a>",
"markdown": "[My updated attachment](https://bookstack.local/attachments/5)"
},
"content": "https://link.example.com/updated"
}

View File

@ -0,0 +1,12 @@
{
"id": 5,
"name": "My updated attachment",
"extension": "",
"uploaded_to": 4,
"external": true,
"order": 2,
"created_by": 1,
"updated_by": 1,
"created_at": "2021-10-20 06:35:46",
"updated_at": "2021-10-20 06:37:11"
}

View File

@ -44,7 +44,7 @@
</p> </p>
<table class="table"> <table class="table">
<tr> <tr>
<th>Parameter</th> <th width="110">Parameter</th>
<th>Details</th> <th>Details</th>
<th width="30%">Examples</th> <th width="30%">Examples</th>
</tr> </tr>

View File

@ -7,6 +7,12 @@
*/ */
Route::get('docs.json', 'ApiDocsController@json'); 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::get('books', 'BookApiController@list');
Route::post('books', 'BookApiController@create'); Route::post('books', 'BookApiController@create');
Route::get('books/{id}', 'BookApiController@read'); Route::get('books/{id}', 'BookApiController@read');

View File

@ -0,0 +1,330 @@
<?php
namespace Tests\Api;
use BookStack\Entities\Models\Page;
use BookStack\Uploads\Attachment;
use Illuminate\Http\UploadedFile;
use Tests\TestCase;
class AttachmentsApiTest extends TestCase
{
use TestsApi;
protected $baseEndpoint = '/api/attachments';
public function test_index_endpoint_returns_expected_book()
{
$this->actingAsApiEditor();
$page = Page::query()->first();
$attachment = $this->createAttachmentForPage($page, [
'name' => 'My test attachment',
'external' => true,
]);
$resp = $this->getJson($this->baseEndpoint . '?count=1&sort=+id');
$resp->assertJson(['data' => [
[
'id' => $attachment->id,
'name' => 'My test attachment',
'uploaded_to' => $page->id,
'external' => true,
],
]]);
}
public function test_attachments_listing_based_upon_page_visibility()
{
$this->actingAsApiEditor();
/** @var Page $page */
$page = Page::query()->first();
$attachment = $this->createAttachmentForPage($page, [
'name' => 'My test attachment',
'external' => true,
]);
$resp = $this->getJson($this->baseEndpoint . '?count=1&sort=+id');
$resp->assertJson(['data' => [
[
'id' => $attachment->id,
],
]]);
$page->restricted = true;
$page->save();
$this->regenEntityPermissions($page);
$resp = $this->getJson($this->baseEndpoint . '?count=1&sort=+id');
$resp->assertJsonMissing(['data' => [
[
'id' => $attachment->id,
],
]]);
}
public function test_create_endpoint_for_link_attachment()
{
$this->actingAsApiAdmin();
/** @var Page $page */
$page = Page::query()->first();
$details = [
'name' => 'My attachment',
'uploaded_to' => $page->id,
'link' => 'https://cats.example.com',
];
$resp = $this->postJson($this->baseEndpoint, $details);
$resp->assertStatus(200);
/** @var Attachment $newItem */
$newItem = Attachment::query()->orderByDesc('id')->where('name', '=', $details['name'])->first();
$resp->assertJson(['id' => $newItem->id, 'external' => true, 'name' => $details['name'], 'uploaded_to' => $page->id]);
}
public function test_create_endpoint_for_upload_attachment()
{
$this->actingAsApiAdmin();
/** @var Page $page */
$page = Page::query()->first();
$file = $this->getTestFile('textfile.txt');
$details = [
'name' => 'My attachment',
'uploaded_to' => $page->id,
];
$resp = $this->call('POST', $this->baseEndpoint, $details, [], ['file' => $file]);
$resp->assertStatus(200);
/** @var Attachment $newItem */
$newItem = Attachment::query()->orderByDesc('id')->where('name', '=', $details['name'])->first();
$resp->assertJson(['id' => $newItem->id, 'external' => false, 'extension' => 'txt', 'name' => $details['name'], 'uploaded_to' => $page->id]);
$this->assertTrue(file_exists(storage_path($newItem->path)));
unlink(storage_path($newItem->path));
}
public function test_name_needed_to_create()
{
$this->actingAsApiAdmin();
/** @var Page $page */
$page = Page::query()->first();
$details = [
'uploaded_to' => $page->id,
'link' => 'https://example.com',
];
$resp = $this->postJson($this->baseEndpoint, $details);
$resp->assertStatus(422);
$resp->assertJson([
'error' => [
'message' => 'The given data was invalid.',
'validation' => [
'name' => ['The name field is required.'],
],
'code' => 422,
],
]);
}
public function test_link_or_file_needed_to_create()
{
$this->actingAsApiAdmin();
/** @var Page $page */
$page = Page::query()->first();
$details = [
'name' => 'my attachment',
'uploaded_to' => $page->id,
];
$resp = $this->postJson($this->baseEndpoint, $details);
$resp->assertStatus(422);
$resp->assertJson([
'error' => [
'message' => 'The given data was invalid.',
'validation' => [
"file" => ["The file field is required when link is not present."],
"link" => ["The link field is required when file is not present."],
],
'code' => 422,
],
]);
}
public function test_read_endpoint_for_link_attachment()
{
$this->actingAsApiAdmin();
/** @var Page $page */
$page = Page::query()->first();
$attachment = $this->createAttachmentForPage($page, [
'name' => 'my attachment',
'path' => 'https://example.com',
'order' => 1,
]);
$resp = $this->getJson("{$this->baseEndpoint}/{$attachment->id}");
$resp->assertStatus(200);
$resp->assertJson([
'id' => $attachment->id,
'content' => 'https://example.com',
'external' => true,
'uploaded_to' => $page->id,
'order' => 1,
'created_by' => [
'name' => $attachment->createdBy->name,
],
'updated_by' => [
'name' => $attachment->createdBy->name,
],
'links' => [
"html" => "<a target=\"_blank\" href=\"http://localhost/attachments/{$attachment->id}\">my attachment</a>",
"markdown" => "[my attachment](http://localhost/attachments/{$attachment->id})"
],
]);
}
public function test_read_endpoint_for_file_attachment()
{
$this->actingAsApiAdmin();
/** @var Page $page */
$page = Page::query()->first();
$file = $this->getTestFile('textfile.txt');
$details = [
'name' => 'My file attachment',
'uploaded_to' => $page->id,
];
$this->call('POST', $this->baseEndpoint, $details, [], ['file' => $file]);
/** @var Attachment $attachment */
$attachment = Attachment::query()->orderByDesc('id')->where('name', '=', $details['name'])->firstOrFail();
$resp = $this->getJson("{$this->baseEndpoint}/{$attachment->id}");
$resp->assertStatus(200);
$resp->assertJson([
'id' => $attachment->id,
'content' => base64_encode(file_get_contents(storage_path($attachment->path))),
'external' => false,
'uploaded_to' => $page->id,
'order' => 1,
'created_by' => [
'name' => $attachment->createdBy->name,
],
'updated_by' => [
'name' => $attachment->updatedBy->name,
],
'links' => [
"html" => "<a target=\"_blank\" href=\"http://localhost/attachments/{$attachment->id}\">My file attachment</a>",
"markdown" => "[My file attachment](http://localhost/attachments/{$attachment->id})"
],
]);
unlink(storage_path($attachment->path));
}
public function test_update_endpoint()
{
$this->actingAsApiAdmin();
/** @var Page $page */
$page = Page::query()->first();
$attachment = $this->createAttachmentForPage($page);
$details = [
'name' => 'My updated API attachment',
];
$resp = $this->putJson("{$this->baseEndpoint}/{$attachment->id}", $details);
$attachment->refresh();
$resp->assertStatus(200);
$resp->assertJson(['id' => $attachment->id, 'name' => 'My updated API attachment']);
}
public function test_update_link_attachment_to_file()
{
$this->actingAsApiAdmin();
/** @var Page $page */
$page = Page::query()->first();
$attachment = $this->createAttachmentForPage($page);
$file = $this->getTestFile('textfile.txt');
$resp = $this->call('PUT', "{$this->baseEndpoint}/{$attachment->id}", ['name' => 'My updated file'], [], ['file' => $file]);
$resp->assertStatus(200);
$attachment->refresh();
$this->assertFalse($attachment->external);
$this->assertEquals('txt', $attachment->extension);
$this->assertStringStartsWith('uploads/files/', $attachment->path);
$this->assertFileExists(storage_path($attachment->path));
unlink(storage_path($attachment->path));
}
public function test_update_file_attachment_to_link()
{
$this->actingAsApiAdmin();
/** @var Page $page */
$page = Page::query()->first();
$file = $this->getTestFile('textfile.txt');
$this->call('POST', $this->baseEndpoint, ['name' => 'My file attachment', 'uploaded_to' => $page->id], [], ['file' => $file]);
/** @var Attachment $attachment */
$attachment = Attachment::query()->where('name', '=', 'My file attachment')->firstOrFail();
$filePath = storage_path($attachment->path);
$this->assertFileExists($filePath);
$details = [
'name' => 'My updated API attachment',
'link' => 'https://cats.example.com'
];
$resp = $this->putJson("{$this->baseEndpoint}/{$attachment->id}", $details);
$resp->assertStatus(200);
$attachment->refresh();
$this->assertFileDoesNotExist($filePath);
$this->assertTrue($attachment->external);
$this->assertEquals('https://cats.example.com', $attachment->path);
$this->assertEquals('', $attachment->extension);
}
public function test_delete_endpoint()
{
$this->actingAsApiAdmin();
/** @var Page $page */
$page = Page::query()->first();
$attachment = $this->createAttachmentForPage($page);
$resp = $this->deleteJson("{$this->baseEndpoint}/{$attachment->id}");
$resp->assertStatus(204);
$this->assertDatabaseMissing('attachments', ['id' => $attachment->id]);
}
protected function createAttachmentForPage(Page $page, $attributes = []): Attachment
{
$admin = $this->getAdmin();
/** @var Attachment $attachment */
$attachment = $page->attachments()->forceCreate(array_merge([
'uploaded_to' => $page->id,
'name' => 'test attachment',
'external' => true,
'order' => 1,
'created_by' => $admin->id,
'updated_by' => $admin->id,
'path' => 'https://attachment.example.com'
], $attributes));
return $attachment;
}
/**
* Get a test file that can be uploaded.
*/
protected function getTestFile(string $fileName): UploadedFile
{
return new UploadedFile(base_path('tests/test-data/test-file.txt'), $fileName, 'text/plain', 55, null, true);
}
}

View File

@ -17,6 +17,16 @@ trait TestsApi
return $this; return $this;
} }
/**
* Set the API admin role as the current user via the API driver.
*/
protected function actingAsApiAdmin()
{
$this->actingAs($this->getAdmin(), 'api');
return $this;
}
/** /**
* Format the given items into a standardised error format. * Format the given items into a standardised error format.
*/ */

View File

@ -76,9 +76,9 @@ class AttachmentTest extends TestCase
$upload->assertStatus(200); $upload->assertStatus(200);
$attachment = Attachment::query()->orderBy('id', 'desc')->first(); $attachment = Attachment::query()->orderBy('id', 'desc')->first();
$expectedResp['path'] = $attachment->path;
$upload->assertJson($expectedResp); $upload->assertJson($expectedResp);
$expectedResp['path'] = $attachment->path;
$this->assertDatabaseHas('attachments', $expectedResp); $this->assertDatabaseHas('attachments', $expectedResp);
$this->deleteUploads(); $this->deleteUploads();