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