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'],
class PageApiController extends ApiController
{
- protected $rules = [
+ protected array $rules = [
'create' => [
'book_id' => ['required_without:chapter_id', 'integer'],
'chapter_id' => ['required_without:book_id', 'integer'],
use BookStack\Entities\Queries\BookQueries;
use BookStack\Exports\ExportFormatter;
+use BookStack\Exports\ZipExports\ZipExportBuilder;
use BookStack\Http\ApiController;
use Throwable;
return $this->download()->directly($markdown, $book->slug . '.md');
}
+
+ /**
+ * Export a book to 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);
+ }
}
use BookStack\Entities\Queries\ChapterQueries;
use BookStack\Exports\ExportFormatter;
+use BookStack\Exports\ZipExports\ZipExportBuilder;
use BookStack\Http\ApiController;
use Throwable;
return $this->download()->directly($markdown, $chapter->slug . '.md');
}
+
+ 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);
+ }
}
--- /dev/null
+<?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);
+ }
+}
use BookStack\Entities\Queries\PageQueries;
use BookStack\Exports\ExportFormatter;
+use BookStack\Exports\ZipExports\ZipExportBuilder;
use BookStack\Http\ApiController;
use Throwable;
return $this->download()->directly($markdown, $page->slug . '.md');
}
+
+ 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);
+ }
}
{
use HasFactory;
+ protected $hidden = ['metadata'];
+
public function getSizeString(): string
{
$mb = round($this->size / 1000000, 2);
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;
* @return Collection<Import>
*/
public function getVisibleImports(): Collection
+ {
+ return $this->queryVisible()->get();
+ }
+
+ public function queryVisible(): Builder
{
$query = Import::query();
$query->where('created_by', user()->id);
}
- return $query->get();
+ return $query;
}
public function findVisible(int $id): Import
abstract class ApiController extends Controller
{
- protected $rules = [];
+ protected array $rules = [];
/**
* Provide a paginated listing JSON response in a standard format
) {
}
- protected $rules = [
+ protected array $rules = [
'update' => [
'owner_id' => ['int'],
class SearchApiController extends ApiController
{
- protected $rules = [
+ protected array $rules = [
'all' => [
'query' => ['required'],
'page' => ['integer', 'min:1'],
'display_name', 'description', 'mfa_enforced', 'external_auth_id', 'created_at', 'updated_at',
];
- protected $rules = [
+ protected array $rules = [
'create' => [
'display_name' => ['required', 'string', 'min:3', 'max:180'],
'description' => ['string', 'max:180'],
'path' => 'uploads/files/imports/' . Str::random(10) . '.zip',
'name' => $this->faker->words(3, true),
'type' => 'book',
+ 'size' => rand(1, 1001),
'metadata' => '{"name": "My book"}',
'created_at' => User::factory(),
];
--- /dev/null
+{
+ "parent_type": "book",
+ "parent_id": 28
+}
\ No newline at end of file
--- /dev/null
+{
+ "type": "chapter",
+ "name": "Pension Providers",
+ "created_by": 1,
+ "size": 2757,
+ "path": "uploads\/files\/imports\/ghnxmS3u9QxLWu82.zip",
+ "updated_at": "2025-07-18T14:50:27.000000Z",
+ "created_at": "2025-07-18T14:50:27.000000Z",
+ "id": 31
+}
\ No newline at end of file
--- /dev/null
+{
+ "data": [
+ {
+ "id": 25,
+ "name": "IT Department",
+ "size": 618462,
+ "type": "book",
+ "created_by": 1,
+ "created_at": "2024-12-20T18:40:38.000000Z",
+ "updated_at": "2024-12-20T18:40:38.000000Z"
+ },
+ {
+ "id": 27,
+ "name": "Clients",
+ "size": 15364,
+ "type": "chapter",
+ "created_by": 1,
+ "created_at": "2025-03-20T12:41:44.000000Z",
+ "updated_at": "2025-03-20T12:41:44.000000Z"
+ }
+ ],
+ "total": 2
+}
\ No newline at end of file
--- /dev/null
+{
+ "id": 25,
+ "name": "IT Department",
+ "path": "uploads\/files\/imports\/7YOpZ6sGIEbYdRFL.zip",
+ "size": 618462,
+ "type": "book",
+ "created_by": 1,
+ "created_at": "2024-12-20T18:40:38.000000Z",
+ "updated_at": "2024-12-20T18:40:38.000000Z",
+ "details": {
+ "id": 4,
+ "name": "IT Department",
+ "chapters": [
+ {
+ "id": 3,
+ "name": "Server Systems",
+ "priority": 1,
+ "pages": [
+ {
+ "id": 22,
+ "name": "prod-aws-stonehawk",
+ "priority": 0,
+ "attachments": [],
+ "images": [],
+ "tags": []
+ }
+ ],
+ "tags": []
+ }
+ ],
+ "pages": [
+ {
+ "id": 23,
+ "name": "Member Onboarding Guide",
+ "priority": 0,
+ "attachments": [],
+ "images": [],
+ "tags": []
+ },
+ {
+ "id": 25,
+ "name": "IT Holiday Party Event",
+ "priority": 2,
+ "attachments": [],
+ "images": [],
+ "tags": []
+ }
+ ],
+ "tags": []
+ }
+}
\ No newline at end of file
--- /dev/null
+{
+ "id": 1067,
+ "book_id": 28,
+ "slug": "pension-providers",
+ "name": "Pension Providers",
+ "description": "Details on the various pension providers that are available",
+ "priority": 7,
+ "created_at": "2025-07-18T14:53:35.000000Z",
+ "updated_at": "2025-07-18T14:53:36.000000Z",
+ "created_by": 1,
+ "updated_by": 1,
+ "owned_by": 1,
+ "default_template_id": null
+}
\ No newline at end of file
Route::get('books/{id}/export/pdf', [ExportControllers\BookExportApiController::class, 'exportPdf']);
Route::get('books/{id}/export/plaintext', [ExportControllers\BookExportApiController::class, 'exportPlainText']);
Route::get('books/{id}/export/markdown', [ExportControllers\BookExportApiController::class, 'exportMarkdown']);
+Route::get('books/{id}/export/zip', [ExportControllers\BookExportApiController::class, 'exportZip']);
Route::get('chapters', [EntityControllers\ChapterApiController::class, 'list']);
Route::post('chapters', [EntityControllers\ChapterApiController::class, 'create']);
Route::get('chapters/{id}/export/pdf', [ExportControllers\ChapterExportApiController::class, 'exportPdf']);
Route::get('chapters/{id}/export/plaintext', [ExportControllers\ChapterExportApiController::class, 'exportPlainText']);
Route::get('chapters/{id}/export/markdown', [ExportControllers\ChapterExportApiController::class, 'exportMarkdown']);
+Route::get('chapters/{id}/export/zip', [ExportControllers\ChapterExportApiController::class, 'exportZip']);
Route::get('pages', [EntityControllers\PageApiController::class, 'list']);
Route::post('pages', [EntityControllers\PageApiController::class, 'create']);
Route::get('pages/{id}/export/pdf', [ExportControllers\PageExportApiController::class, 'exportPdf']);
Route::get('pages/{id}/export/plaintext', [ExportControllers\PageExportApiController::class, 'exportPlainText']);
Route::get('pages/{id}/export/markdown', [ExportControllers\PageExportApiController::class, 'exportMarkdown']);
+Route::get('pages/{id}/export/zip', [ExportControllers\PageExportApiController::class, 'exportZip']);
Route::get('image-gallery', [ImageGalleryApiController::class, 'list']);
Route::post('image-gallery', [ImageGalleryApiController::class, 'create']);
Route::put('roles/{id}', [RoleApiController::class, 'update']);
Route::delete('roles/{id}', [RoleApiController::class, 'delete']);
+Route::get('imports', [ExportControllers\ImportApiController::class, 'list']);
+Route::post('imports', [ExportControllers\ImportApiController::class, 'create']);
+Route::get('imports/{id}', [ExportControllers\ImportApiController::class, 'read']);
+Route::post('imports/{id}', [ExportControllers\ImportApiController::class, 'run']);
+Route::delete('imports/{id}', [ExportControllers\ImportApiController::class, 'delete']);
+
Route::get('recycle-bin', [EntityControllers\RecycleBinApiController::class, 'list']);
Route::put('recycle-bin/{deletionId}', [EntityControllers\RecycleBinApiController::class, 'restore']);
Route::delete('recycle-bin/{deletionId}', [EntityControllers\RecycleBinApiController::class, 'destroy']);
$resp->assertStatus(204);
$this->assertActivityExists('book_delete');
}
-
- public function test_export_html_endpoint()
- {
- $this->actingAsApiEditor();
- $book = $this->entities->book();
-
- $resp = $this->get($this->baseEndpoint . "/{$book->id}/export/html");
- $resp->assertStatus(200);
- $resp->assertSee($book->name);
- $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $book->slug . '.html"');
- }
-
- public function test_export_plain_text_endpoint()
- {
- $this->actingAsApiEditor();
- $book = $this->entities->book();
-
- $resp = $this->get($this->baseEndpoint . "/{$book->id}/export/plaintext");
- $resp->assertStatus(200);
- $resp->assertSee($book->name);
- $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $book->slug . '.txt"');
- }
-
- public function test_export_pdf_endpoint()
- {
- $this->actingAsApiEditor();
- $book = $this->entities->book();
-
- $resp = $this->get($this->baseEndpoint . "/{$book->id}/export/pdf");
- $resp->assertStatus(200);
- $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $book->slug . '.pdf"');
- }
-
- public function test_export_markdown_endpoint()
- {
- $this->actingAsApiEditor();
- $book = Book::visible()->has('pages')->has('chapters')->first();
-
- $resp = $this->get($this->baseEndpoint . "/{$book->id}/export/markdown");
- $resp->assertStatus(200);
- $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $book->slug . '.md"');
- $resp->assertSee('# ' . $book->name);
- $resp->assertSee('# ' . $book->pages()->first()->name);
- $resp->assertSee('# ' . $book->chapters()->first()->name);
- }
-
- public function test_cant_export_when_not_have_permission()
- {
- $types = ['html', 'plaintext', 'pdf', 'markdown'];
- $this->actingAsApiEditor();
- $this->permissions->removeUserRolePermissions($this->users->editor(), ['content-export']);
-
- $book = $this->entities->book();
- foreach ($types as $type) {
- $resp = $this->get($this->baseEndpoint . "/{$book->id}/export/{$type}");
- $this->assertPermissionError($resp);
- }
- }
}
$resp->assertStatus(204);
$this->assertActivityExists('chapter_delete');
}
-
- public function test_export_html_endpoint()
- {
- $this->actingAsApiEditor();
- $chapter = $this->entities->chapter();
-
- $resp = $this->get($this->baseEndpoint . "/{$chapter->id}/export/html");
- $resp->assertStatus(200);
- $resp->assertSee($chapter->name);
- $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $chapter->slug . '.html"');
- }
-
- public function test_export_plain_text_endpoint()
- {
- $this->actingAsApiEditor();
- $chapter = $this->entities->chapter();
-
- $resp = $this->get($this->baseEndpoint . "/{$chapter->id}/export/plaintext");
- $resp->assertStatus(200);
- $resp->assertSee($chapter->name);
- $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $chapter->slug . '.txt"');
- }
-
- public function test_export_pdf_endpoint()
- {
- $this->actingAsApiEditor();
- $chapter = $this->entities->chapter();
-
- $resp = $this->get($this->baseEndpoint . "/{$chapter->id}/export/pdf");
- $resp->assertStatus(200);
- $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $chapter->slug . '.pdf"');
- }
-
- public function test_export_markdown_endpoint()
- {
- $this->actingAsApiEditor();
- $chapter = Chapter::visible()->has('pages')->first();
-
- $resp = $this->get($this->baseEndpoint . "/{$chapter->id}/export/markdown");
- $resp->assertStatus(200);
- $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $chapter->slug . '.md"');
- $resp->assertSee('# ' . $chapter->name);
- $resp->assertSee('# ' . $chapter->pages()->first()->name);
- }
-
- public function test_cant_export_when_not_have_permission()
- {
- $types = ['html', 'plaintext', 'pdf', 'markdown'];
- $this->actingAsApiEditor();
- $this->permissions->removeUserRolePermissions($this->users->editor(), ['content-export']);
-
- $chapter = Chapter::visible()->has('pages')->first();
- foreach ($types as $type) {
- $resp = $this->get($this->baseEndpoint . "/{$chapter->id}/export/{$type}");
- $this->assertPermissionError($resp);
- }
- }
}
--- /dev/null
+<?php
+
+namespace Api;
+
+use BookStack\Entities\Models\Book;
+use BookStack\Entities\Models\Chapter;
+use Tests\Api\TestsApi;
+use Tests\Exports\ZipTestHelper;
+use Tests\TestCase;
+
+class ExportsApiTest extends TestCase
+{
+ use TestsApi;
+
+ public function test_book_html_endpoint()
+ {
+ $this->actingAsApiEditor();
+ $book = $this->entities->book();
+
+ $resp = $this->get("/api/books/{$book->id}/export/html");
+ $resp->assertStatus(200);
+ $resp->assertSee($book->name);
+ $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $book->slug . '.html"');
+ }
+
+ public function test_book_plain_text_endpoint()
+ {
+ $this->actingAsApiEditor();
+ $book = $this->entities->book();
+
+ $resp = $this->get("/api/books/{$book->id}/export/plaintext");
+ $resp->assertStatus(200);
+ $resp->assertSee($book->name);
+ $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $book->slug . '.txt"');
+ }
+
+ public function test_book_pdf_endpoint()
+ {
+ $this->actingAsApiEditor();
+ $book = $this->entities->book();
+
+ $resp = $this->get("/api/books/{$book->id}/export/pdf");
+ $resp->assertStatus(200);
+ $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $book->slug . '.pdf"');
+ }
+
+ public function test_book_markdown_endpoint()
+ {
+ $this->actingAsApiEditor();
+ $book = Book::visible()->has('pages')->has('chapters')->first();
+
+ $resp = $this->get("/api/books/{$book->id}/export/markdown");
+ $resp->assertStatus(200);
+ $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $book->slug . '.md"');
+ $resp->assertSee('# ' . $book->name);
+ $resp->assertSee('# ' . $book->pages()->first()->name);
+ $resp->assertSee('# ' . $book->chapters()->first()->name);
+ }
+
+ public function test_book_zip_endpoint()
+ {
+ $this->actingAsApiEditor();
+ $book = Book::visible()->has('pages')->has('chapters')->first();
+
+ $resp = $this->get("/api/books/{$book->id}/export/zip");
+ $resp->assertStatus(200);
+ $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $book->slug . '.zip"');
+
+ $zip = ZipTestHelper::extractFromZipResponse($resp);
+ $this->assertArrayHasKey('book', $zip->data);
+ }
+
+ public function test_chapter_html_endpoint()
+ {
+ $this->actingAsApiEditor();
+ $chapter = $this->entities->chapter();
+
+ $resp = $this->get("/api/chapters/{$chapter->id}/export/html");
+ $resp->assertStatus(200);
+ $resp->assertSee($chapter->name);
+ $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $chapter->slug . '.html"');
+ }
+
+ public function test_chapter_plain_text_endpoint()
+ {
+ $this->actingAsApiEditor();
+ $chapter = $this->entities->chapter();
+
+ $resp = $this->get("/api/chapters/{$chapter->id}/export/plaintext");
+ $resp->assertStatus(200);
+ $resp->assertSee($chapter->name);
+ $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $chapter->slug . '.txt"');
+ }
+
+ public function test_chapter_pdf_endpoint()
+ {
+ $this->actingAsApiEditor();
+ $chapter = $this->entities->chapter();
+
+ $resp = $this->get("/api/chapters/{$chapter->id}/export/pdf");
+ $resp->assertStatus(200);
+ $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $chapter->slug . '.pdf"');
+ }
+
+ public function test_chapter_markdown_endpoint()
+ {
+ $this->actingAsApiEditor();
+ $chapter = Chapter::visible()->has('pages')->first();
+
+ $resp = $this->get("/api/chapters/{$chapter->id}/export/markdown");
+ $resp->assertStatus(200);
+ $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $chapter->slug . '.md"');
+ $resp->assertSee('# ' . $chapter->name);
+ $resp->assertSee('# ' . $chapter->pages()->first()->name);
+ }
+
+ public function test_chapter_zip_endpoint()
+ {
+ $this->actingAsApiEditor();
+ $chapter = Chapter::visible()->has('pages')->first();
+
+ $resp = $this->get("/api/chapters/{$chapter->id}/export/zip");
+ $resp->assertStatus(200);
+ $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $chapter->slug . '.zip"');
+
+ $zip = ZipTestHelper::extractFromZipResponse($resp);
+ $this->assertArrayHasKey('chapter', $zip->data);
+ }
+
+ public function test_page_html_endpoint()
+ {
+ $this->actingAsApiEditor();
+ $page = $this->entities->page();
+
+ $resp = $this->get("/api/pages/{$page->id}/export/html");
+ $resp->assertStatus(200);
+ $resp->assertSee($page->name);
+ $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $page->slug . '.html"');
+ }
+
+ public function test_page_plain_text_endpoint()
+ {
+ $this->actingAsApiEditor();
+ $page = $this->entities->page();
+
+ $resp = $this->get("/api/pages/{$page->id}/export/plaintext");
+ $resp->assertStatus(200);
+ $resp->assertSee($page->name);
+ $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $page->slug . '.txt"');
+ }
+
+ public function test_page_pdf_endpoint()
+ {
+ $this->actingAsApiEditor();
+ $page = $this->entities->page();
+
+ $resp = $this->get("/api/pages/{$page->id}/export/pdf");
+ $resp->assertStatus(200);
+ $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $page->slug . '.pdf"');
+ }
+
+ public function test_page_markdown_endpoint()
+ {
+ $this->actingAsApiEditor();
+ $page = $this->entities->page();
+
+ $resp = $this->get("/api/pages/{$page->id}/export/markdown");
+ $resp->assertStatus(200);
+ $resp->assertSee('# ' . $page->name);
+ $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $page->slug . '.md"');
+ }
+
+ public function test_page_zip_endpoint()
+ {
+ $this->actingAsApiEditor();
+ $page = $this->entities->page();
+
+ $resp = $this->get("/api/pages/{$page->id}/export/zip");
+ $resp->assertStatus(200);
+ $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $page->slug . '.zip"');
+
+ $zip = ZipTestHelper::extractFromZipResponse($resp);
+ $this->assertArrayHasKey('page', $zip->data);
+ }
+
+ public function test_cant_export_when_not_have_permission()
+ {
+ $types = ['html', 'plaintext', 'pdf', 'markdown', 'zip'];
+ $this->actingAsApiEditor();
+ $this->permissions->removeUserRolePermissions($this->users->editor(), ['content-export']);
+
+ $book = $this->entities->book();
+ foreach ($types as $type) {
+ $resp = $this->get("/api/books/{$book->id}/export/{$type}");
+ $this->assertPermissionError($resp);
+ }
+
+ $chapter = Chapter::visible()->has('pages')->first();
+ foreach ($types as $type) {
+ $resp = $this->get("/api/chapters/{$chapter->id}/export/{$type}");
+ $this->assertPermissionError($resp);
+ }
+
+ $page = $this->entities->page();
+ foreach ($types as $type) {
+ $resp = $this->get("/api/pages/{$page->id}/export/{$type}");
+ $this->assertPermissionError($resp);
+ }
+ }
+}
--- /dev/null
+<?php
+
+namespace Api;
+
+use BookStack\Entities\Models\Page;
+use BookStack\Exports\Import;
+use Tests\Api\TestsApi;
+use Tests\Exports\ZipTestHelper;
+use Tests\TestCase;
+
+class ImportsApiTest extends TestCase
+{
+ use TestsApi;
+
+ protected string $baseEndpoint = '/api/imports';
+
+ public function test_create_and_run(): void
+ {
+ $book = $this->entities->book();
+ $zip = ZipTestHelper::zipUploadFromData([
+ 'page' => [
+ 'name' => 'My API import page',
+ 'tags' => [
+ [
+ 'name' => 'My api tag',
+ 'value' => 'api test value'
+ ]
+ ],
+ ],
+ ]);
+
+ $resp = $this->actingAsApiAdmin()->call('POST', $this->baseEndpoint, [], [], ['file' => $zip]);
+ $resp->assertStatus(200);
+
+ $importId = $resp->json('id');
+ $import = Import::query()->findOrFail($importId);
+ $this->assertEquals('page', $import->type);
+
+ $resp = $this->post($this->baseEndpoint . "/{$import->id}", [
+ 'parent_type' => 'book',
+ 'parent_id' => $book->id,
+ ]);
+ $resp->assertJson([
+ 'name' => 'My API import page',
+ 'book_id' => $book->id,
+ ]);
+ $resp->assertJsonMissingPath('book');
+
+ $page = Page::query()->where('name', '=', 'My API import page')->first();
+ $this->assertEquals('My api tag', $page->tags()->first()->name);
+ }
+
+ public function test_create_validation_error(): void
+ {
+ $zip = ZipTestHelper::zipUploadFromData([
+ 'page' => [
+ 'tags' => [
+ [
+ 'name' => 'My api tag',
+ 'value' => 'api test value'
+ ]
+ ],
+ ],
+ ]);
+
+ $resp = $this->actingAsApiAdmin()->call('POST', $this->baseEndpoint, [], [], ['file' => $zip]);
+ $resp->assertStatus(422);
+ $message = $resp->json('message');
+
+ $this->assertStringContainsString('ZIP upload failed with the following validation errors:', $message);
+ $this->assertStringContainsString('[page.name] The name field is required.', $message);
+ }
+
+ public function test_list(): void
+ {
+ $imports = Import::factory()->count(10)->create();
+
+ $resp = $this->actingAsApiAdmin()->get($this->baseEndpoint);
+ $resp->assertJsonCount(10, 'data');
+ $resp->assertJsonPath('total', 10);
+
+ $firstImport = $imports->first();
+ $resp = $this->actingAsApiAdmin()->get($this->baseEndpoint . '?filter[id]=' . $firstImport->id);
+ $resp->assertJsonCount(1, 'data');
+ $resp->assertJsonPath('data.0.id', $firstImport->id);
+ $resp->assertJsonPath('data.0.name', $firstImport->name);
+ $resp->assertJsonPath('data.0.size', $firstImport->size);
+ $resp->assertJsonPath('data.0.type', $firstImport->type);
+ }
+
+ public function test_list_visibility_limited(): void
+ {
+ $user = $this->users->editor();
+ $admin = $this->users->admin();
+ $userImport = Import::factory()->create(['name' => 'MySuperUserImport', 'created_by' => $user->id]);
+ $adminImport = Import::factory()->create(['name' => 'MySuperAdminImport', 'created_by' => $admin->id]);
+ $this->permissions->grantUserRolePermissions($user, ['content-import']);
+
+ $resp = $this->actingAsForApi($user)->get($this->baseEndpoint);
+ $resp->assertJsonCount(1, 'data');
+ $resp->assertJsonPath('data.0.name', 'MySuperUserImport');
+
+ $this->permissions->grantUserRolePermissions($user, ['settings-manage']);
+
+ $resp = $this->actingAsForApi($user)->get($this->baseEndpoint);
+ $resp->assertJsonCount(2, 'data');
+ $resp->assertJsonPath('data.1.name', 'MySuperAdminImport');
+ }
+
+ public function test_read(): void
+ {
+ $zip = ZipTestHelper::zipUploadFromData([
+ 'book' => [
+ 'name' => 'My API import book',
+ 'pages' => [
+ [
+ 'name' => 'My import page',
+ 'tags' => [
+ [
+ 'name' => 'My api tag',
+ 'value' => 'api test value'
+ ]
+ ]
+ ]
+ ],
+ ],
+ ]);
+
+ $resp = $this->actingAsApiAdmin()->call('POST', $this->baseEndpoint, [], [], ['file' => $zip]);
+ $resp->assertStatus(200);
+
+ $resp = $this->get($this->baseEndpoint . "/{$resp->json('id')}");
+ $resp->assertStatus(200);
+
+ $resp->assertJsonPath('details.name', 'My API import book');
+ $resp->assertJsonPath('details.pages.0.name', 'My import page');
+ $resp->assertJsonPath('details.pages.0.tags.0.name', 'My api tag');
+ $resp->assertJsonMissingPath('metadata');
+ }
+
+ public function test_delete(): void
+ {
+ $import = Import::factory()->create();
+
+ $resp = $this->actingAsApiAdmin()->delete($this->baseEndpoint . "/{$import->id}");
+ $resp->assertStatus(204);
+ }
+
+ public function test_content_import_permissions_needed(): void
+ {
+ $user = $this->users->viewer();
+ $this->permissions->grantUserRolePermissions($user, ['access-api']);
+ $this->actingAsForApi($user);
+ $requests = [
+ ['GET', $this->baseEndpoint],
+ ['POST', $this->baseEndpoint],
+ ['GET', $this->baseEndpoint . "/1"],
+ ['POST', $this->baseEndpoint . "/1"],
+ ['DELETE', $this->baseEndpoint . "/1"],
+ ];
+
+ foreach ($requests as $request) {
+ [$method, $endpoint] = $request;
+ $resp = $this->json($method, $endpoint);
+ $resp->assertStatus(403);
+ }
+
+ $this->permissions->grantUserRolePermissions($user, ['content-import']);
+
+ foreach ($requests as $request) {
+ [$method, $endpoint] = $request;
+ $resp = $this->call($method, $endpoint);
+ $this->assertNotEquals(403, $resp->status(), "A {$method} request to {$endpoint} returned 403");
+ }
+ }
+}
$resp->assertStatus(204);
$this->assertActivityExists('page_delete', $page);
}
-
- public function test_export_html_endpoint()
- {
- $this->actingAsApiEditor();
- $page = $this->entities->page();
-
- $resp = $this->get($this->baseEndpoint . "/{$page->id}/export/html");
- $resp->assertStatus(200);
- $resp->assertSee($page->name);
- $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $page->slug . '.html"');
- }
-
- public function test_export_plain_text_endpoint()
- {
- $this->actingAsApiEditor();
- $page = $this->entities->page();
-
- $resp = $this->get($this->baseEndpoint . "/{$page->id}/export/plaintext");
- $resp->assertStatus(200);
- $resp->assertSee($page->name);
- $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $page->slug . '.txt"');
- }
-
- public function test_export_pdf_endpoint()
- {
- $this->actingAsApiEditor();
- $page = $this->entities->page();
-
- $resp = $this->get($this->baseEndpoint . "/{$page->id}/export/pdf");
- $resp->assertStatus(200);
- $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $page->slug . '.pdf"');
- }
-
- public function test_export_markdown_endpoint()
- {
- $this->actingAsApiEditor();
- $page = $this->entities->page();
-
- $resp = $this->get($this->baseEndpoint . "/{$page->id}/export/markdown");
- $resp->assertStatus(200);
- $resp->assertSee('# ' . $page->name);
- $resp->assertHeader('Content-Disposition', 'attachment; filename="' . $page->slug . '.md"');
- }
-
- public function test_cant_export_when_not_have_permission()
- {
- $types = ['html', 'plaintext', 'pdf', 'markdown'];
- $this->actingAsApiEditor();
- $this->permissions->removeUserRolePermissions($this->users->editor(), ['content-export']);
-
- $page = $this->entities->page();
- foreach ($types as $type) {
- $resp = $this->get($this->baseEndpoint . "/{$page->id}/export/{$type}");
- $this->assertPermissionError($resp);
- }
- }
}
{
$page = $this->entities->page();
$zipResp = $this->asEditor()->get($page->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$this->assertEquals($page->id, $zip->data['page']['id'] ?? null);
$this->assertArrayNotHasKey('book', $zip->data);
{
$page = $this->entities->page();
$zipResp = $this->asEditor()->get($page->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$pageData = $zip->data['page'];
$this->assertEquals([
$page->save();
$zipResp = $this->asEditor()->get($page->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$pageData = $zip->data['page'];
$this->assertEquals($markdown, $pageData['markdown']);
]);
$zipResp = $this->asEditor()->get($page->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$pageData = $zip->data['page'];
$this->assertEquals([
$image = Image::findOrFail($result['response']->id);
$zipResp = $this->asEditor()->get($page->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$pageData = $zip->data['page'];
$this->assertCount(1, $pageData['images']);
$attachment = $this->files->uploadAttachmentDataToPage($this, $page, 'PageAttachmentExport.txt', $contents, 'text/plain');
$zipResp = $this->get($page->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$pageData = $zip->data['page'];
$this->assertCount(1, $pageData['attachments']);
]);
$zipResp = $this->get($page->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$pageData = $zip->data['page'];
$this->assertCount(1, $pageData['attachments']);
$book->tags()->saveMany(Tag::factory()->count(2)->make());
$zipResp = $this->asEditor()->get($book->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$this->assertArrayHasKey('book', $zip->data);
$bookData = $zip->data['book'];
$coverImage = $book->cover()->first();
$zipResp = $this->asEditor()->get($book->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$this->assertArrayHasKey('cover', $zip->data['book']);
$coverRef = $zip->data['book']['cover'];
$chapter->tags()->saveMany(Tag::factory()->count(2)->make());
$zipResp = $this->asEditor()->get($chapter->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$this->assertArrayHasKey('chapter', $zip->data);
$chapterData = $zip->data['chapter'];
$page->save();
$zipResp = $this->actingAs($editor)->get($book->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$this->assertCount(0, $zip->data['book']['chapters'][0]['pages'] ?? ['cat']);
$zipResp = $this->actingAs($editor)->get($chapter->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$this->assertCount(0, $zip->data['chapter']['pages'] ?? ['cat']);
$page->chapter_id = 0;
$page->save();
$zipResp = $this->actingAs($editor)->get($book->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$this->assertCount(0, $zip->data['book']['pages'] ?? ['cat']);
}
$page->save();
$zipResp = $this->asEditor()->get($book->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$bookData = $zip->data['book'];
$chapterData = $bookData['chapters'][0];
$pageData = $chapterData['pages'][0];
$chapter->save();
$zipResp = $this->get($book->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$bookData = $zip->data['book'];
$chapterData = $bookData['chapters'][0];
$page->save();
$zipResp = $this->get($page->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$pageData = $zip->data['page'];
$ref = '[[bsexport:image:' . $image->id . ']]';
$page->save();
$zipResp = $this->asEditor()->get($page->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$pageData = $zip->data['page'];
$this->assertStringContainsString('href="' . $page->book->getUrl() . '"', $pageData['html']);
$page->save();
$zipResp = $this->asEditor()->get($page->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$pageData = $zip->data['page'];
$this->assertStringContainsString('href="[[bsexport:attachment:' . $attachment->id . ']]?open=true"', $pageData['html']);
$page->save();
$zipResp = $this->asEditor()->get($chapter->getUrl("/export/zip"));
- $zip = $this->extractZipResponse($zipResp);
+ $zip = ZipTestHelper::extractFromZipResponse($zipResp);
$pageData = $zip->data['chapter']['pages'][0];
$this->assertStringContainsString("[Link to chapter]([[bsexport:chapter:{$chapter->id}]])", $pageData['markdown']);
}
$this->get($page->getUrl("/export/zip"))->assertStatus(429);
}
-
- protected function extractZipResponse(TestResponse $response): ZipResultData
- {
- $zipData = $response->streamedContent();
- $zipFile = tempnam(sys_get_temp_dir(), 'bstest-');
-
- file_put_contents($zipFile, $zipData);
- $extractDir = tempnam(sys_get_temp_dir(), 'bstestextracted-');
- if (file_exists($extractDir)) {
- unlink($extractDir);
- }
- mkdir($extractDir);
-
- $zip = new ZipArchive();
- $zip->open($zipFile, ZipArchive::RDONLY);
- $zip->extractTo($extractDir);
-
- $dataJson = file_get_contents($extractDir . DIRECTORY_SEPARATOR . "data.json");
- $data = json_decode($dataJson, true);
-
- return new ZipResultData(
- $zipFile,
- $extractDir,
- $data,
- );
- }
}
use BookStack\Exports\Import;
use Illuminate\Http\UploadedFile;
+use Illuminate\Testing\TestResponse;
use ZipArchive;
class ZipTestHelper
return new UploadedFile($zipFile, 'upload.zip', 'application/zip', null, true);
}
+
+ public static function extractFromZipResponse(TestResponse $response): ZipResultData
+ {
+ $zipData = $response->streamedContent();
+ $zipFile = tempnam(sys_get_temp_dir(), 'bstest-');
+
+ file_put_contents($zipFile, $zipData);
+ $extractDir = tempnam(sys_get_temp_dir(), 'bstestextracted-');
+ if (file_exists($extractDir)) {
+ unlink($extractDir);
+ }
+ mkdir($extractDir);
+
+ $zip = new ZipArchive();
+ $zip->open($zipFile, ZipArchive::RDONLY);
+ $zip->extractTo($extractDir);
+
+ $dataJson = file_get_contents($extractDir . DIRECTORY_SEPARATOR . "data.json");
+ $data = json_decode($dataJson, true);
+
+ return new ZipResultData(
+ $zipFile,
+ $extractDir,
+ $data,
+ );
+ }
}
projects / bookstack / commitdiff