- Added pagination docs

Author: dash8x

docs/basic-usage/pagination.md

@@ -0,0 +1,51 @@
+---
+title: Pagination
+sidebar_position: 3
+---
+
+By default, the `index` endpoint of API controllers are paginated to `10` results per page.
+Users can use the `?per_page=` query parameter to specify how many items to return per page.
+
+## Modifying the default results per page
+
+You can modify the default `per_page` amount of `10` by overriding the `getDefaultPerPage` method.
+
+```php
+public function getDefaultPerPage(): int
+{
+    return 20;
+}
+```
+
+## Modifying the max results allowed per page
+
+By default the max `per_page` value allowed is `50`.
+You can modify this by overriding the `getMaxPerPage` method.
+
+```php
+public function getMaxPerPage(): int
+{
+    return 100;
+}
+```
+
+## Allowing unlimited results
+
+:::danger
+
+Allowing this option can expose all of your records to the user in a single request.
+This can hit your performance if there are a lot of records for the model.
+
+:::
+
+If you want the user to be able to return all results, without any pagination, override `allowUnlimitedResultsPerPage` method. 
+
+```php
+public function allowUnlimitedResultsPerPage(): bool
+{
+    return true;
+}
+```
+
+Now, if the user sets `?per_page=-1`, then all results will be returned without any pagination.
+

src/Concerns/IsApiController.php

@@ -49,7 +49,7 @@ public function allowUnlimitedResultsPerPage(): bool
      */
     protected function wantsAllResults(Request $request): bool
     {
-        return $request->input('per_page') == -1;
+        return $request->input('per_page', $this->getDefaultPerPage()) == -1;
     }
 
     /**
@@ -64,6 +64,16 @@ protected function getPerPage(Request $request, int $default = 0)
         return abs($request->input('per_page', $default));
     }
 
+    public function getDefaultPerPage(): int
+    {
+        return 10;
+    }
+
+    public function getMaxPerPage(): int
+    {
+        return 50;
+    }
+
     protected function getQueryBuilder(): QueryBuilder
     {
         return QueryBuilder::for($this->getBaseQuery());
@@ -100,7 +110,7 @@ protected function indexEndpoint(Request $request)
             return $query->get();
         }
 
-        return $query->paginate($this->getPerPage($request, 10))
+        return $query->paginate($this->getPerPage($request, $this->getDefaultPerPage()))
             ->appends($request->except(['page']));
     }
 
@@ -169,7 +179,7 @@ protected function authorizeView(Model $model): void
     protected function getIndexValidation(): array
     {
         return [
-            'per_page' => "integer|" . ($this->allowUnlimitedResultsPerPage() ? 'min:-1' : 'between:1,50'),
+            'per_page' => "integer|" . ($this->allowUnlimitedResultsPerPage() ? 'min:-1' : 'between:1,' . $this->getMaxPerPage()),
             'page' => 'integer|min:1',
         ];
     }