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