BookStack Code Mirror - bookstack/blob - app/Entities/Controllers/BookApiController.php

   1 <?php
   2
   3 namespace BookStack\Entities\Controllers;
   4
   5 use BookStack\Api\ApiEntityListFormatter;
   6 use BookStack\Entities\Models\Book;
   7 use BookStack\Entities\Models\Chapter;
   8 use BookStack\Entities\Models\Entity;
   9 use BookStack\Entities\Queries\BookQueries;
  10 use BookStack\Entities\Repos\BookRepo;
  11 use BookStack\Entities\Tools\BookContents;
  12 use BookStack\Http\ApiController;
  13 use Illuminate\Http\Request;
  14 use Illuminate\Validation\ValidationException;
  15
  16 class BookApiController extends ApiController
  17 {
  18     public function __construct(
  19         protected BookRepo $bookRepo,
  20         protected BookQueries $queries,
  21     ) {
  22     }
  23
  24     /**
  25      * Get a listing of books visible to the user.
  26      */
  27     public function list()
  28     {
  29         $books = $this->queries->visibleForList();
  30
  31         return $this->apiListingResponse($books, [
  32             'id', 'name', 'slug', 'description', 'created_at', 'updated_at', 'created_by', 'updated_by', 'owned_by',
  33         ]);
  34     }
  35
  36     /**
  37      * Create a new book in the system.
  38      * The cover image of a book can be set by sending a file via an 'image' property within a 'multipart/form-data' request.
  39      * If the 'image' property is null then the book cover image will be removed.
  40      *
  41      * @throws ValidationException
  42      */
  43     public function create(Request $request)
  44     {
  45         $this->checkPermission('book-create-all');
  46         $requestData = $this->validate($request, $this->rules()['create']);
  47
  48         $book = $this->bookRepo->create($requestData);
  49
  50         return response()->json($this->forJsonDisplay($book));
  51     }
  52
  53     /**
  54      * View the details of a single book.
  55      * The response data will contain 'content' property listing the chapter and pages directly within, in
  56      * the same structure as you'd see within the BookStack interface when viewing a book. Top-level
  57      * contents will have a 'type' property to distinguish between pages & chapters.
  58      */
  59     public function read(string $id)
  60     {
  61         $book = $this->queries->findVisibleByIdOrFail(intval($id));
  62         $book = $this->forJsonDisplay($book);
  63         $book->load(['createdBy', 'updatedBy', 'ownedBy']);
  64
  65         $contents = (new BookContents($book))->getTree(true, false)->all();
  66         $contentsApiData = (new ApiEntityListFormatter($contents))
  67             ->withType()
  68             ->withField('pages', function (Entity $entity) {
  69                 if ($entity instanceof Chapter) {
  70                     return (new ApiEntityListFormatter($entity->pages->all()))->format();
  71                 }
  72                 return null;
  73             })->format();
  74         $book->setAttribute('contents', $contentsApiData);
  75
  76         return response()->json($book);
  77     }
  78
  79     /**
  80      * Update the details of a single book.
  81      * The cover image of a book can be set by sending a file via an 'image' property within a 'multipart/form-data' request.
  82      * If the 'image' property is null then the book cover image will be removed.
  83      *
  84      * @throws ValidationException
  85      */
  86     public function update(Request $request, string $id)
  87     {
  88         $book = $this->queries->findVisibleByIdOrFail(intval($id));
  89         $this->checkOwnablePermission('book-update', $book);
  90
  91         $requestData = $this->validate($request, $this->rules()['update']);
  92         $book = $this->bookRepo->update($book, $requestData);
  93
  94         return response()->json($this->forJsonDisplay($book));
  95     }
  96
  97     /**
  98      * Delete a single book.
  99      * This will typically send the book to the recycle bin.
 100      *
 101      * @throws \Exception
 102      */
 103     public function delete(string $id)
 104     {
 105         $book = $this->queries->findVisibleByIdOrFail(intval($id));
 106         $this->checkOwnablePermission('book-delete', $book);
 107
 108         $this->bookRepo->destroy($book);
 109
 110         return response('', 204);
 111     }
 112
 113     protected function forJsonDisplay(Book $book): Book
 114     {
 115         $book = clone $book;
 116         $book->unsetRelations()->refresh();
 117
 118         $book->load(['tags', 'cover']);
 119         $book->makeVisible('description_html')
 120             ->setAttribute('description_html', $book->descriptionHtml());
 121
 122         return $book;
 123     }
 124
 125     protected function rules(): array
 126     {
 127         return [
 128             'create' => [
 129                 'name'                => ['required', 'string', 'max:255'],
 130                 'description'         => ['string', 'max:1900'],
 131                 'description_html'    => ['string', 'max:2000'],
 132                 'tags'                => ['array'],
 133                 'image'               => array_merge(['nullable'], $this->getImageValidationRules()),
 134                 'default_template_id' => ['nullable', 'integer'],
 135             ],
 136             'update' => [
 137                 'name'                => ['string', 'min:1', 'max:255'],
 138                 'description'         => ['string', 'max:1900'],
 139                 'description_html'    => ['string', 'max:2000'],
 140                 'tags'                => ['array'],
 141                 'image'               => array_merge(['nullable'], $this->getImageValidationRules()),
 142                 'default_template_id' => ['nullable', 'integer'],
 143             ],
 144         ];
 145     }
 146 }