- Added basic resource controller docs

Author: dash8x

README.md

@@ -2,7 +2,6 @@
 
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/javaabu/query-builder.svg?style=flat-square)](https://packagist.org/packages/javaabu/query-builder)
 [![Test Status](../../actions/workflows/run-tests.yml/badge.svg)](../../actions/workflows/run-tests.yml)
-[![Quality Score](https://img.shields.io/scrutinizer/g/javaabu/query-builder.svg?style=flat-square)](https://scrutinizer-ci.com/g/javaabu/query-builder)
 [![Total Downloads](https://img.shields.io/packagist/dt/javaabu/query-builder.svg?style=flat-square)](https://packagist.org/packages/javaabu/query-builder)
 
 Modifications on top of spatie/query-builder

docs/about-us.md

@@ -1,6 +1,6 @@
 ---
 title: About Us
-sidebar_position: 1.6
+sidebar_position: 1.7
 ---
 
 [Javaabu](https://javaabu.com) is a web design agency based in the Maldives.

docs/basic-usage/_category_.json

@@ -1,5 +1,5 @@
 {
-    "position": 1.3,
+    "position": 1.4,
     "label": "Basic Usage",
     "collapsible": true,
     "collapsed": false,

docs/basic-usage/basic-resource-controller.md

@@ -0,0 +1,251 @@
+---
+title: Basic resource controller
+sidebar_position: 1
+---
+
+To create a basic API resource controller using this package, create a controller that extends the `Javaabu\QueryBuilder\Http\Controllers\ApiController` class.
+
+```php
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use Javaabu\QueryBuilder\Http\Controllers\ApiController;
+use App\Models\Product;
+use Illuminate\Database\Eloquent\Builder;
+use Spatie\QueryBuilder\AllowedFilter;
+
+class ProductsController extends ApiController
+{
+    /**
+     * Get the base query
+     *
+     * @return Builder
+     */
+    public function getBaseQuery(): Builder
+    {
+        return Product::query();
+    }
+
+    /**
+     * Get the allowed fields
+     *
+     * @return array
+     */
+    public function getAllowedFields(): array
+    {
+        return array_diff(\Schema::getColumnListing('products'), (new Product)->getHidden());
+    }
+
+    /**
+     * Get the allowed includes
+     *
+     * @return array
+     */
+    public function getAllowedIncludes(): array
+    {
+        return [
+            'category'
+        ];
+    }
+
+    /**
+     * Get the allowed appends
+     *
+     * @return array
+     */
+    public function getAllowedAppends(): array
+    {
+        return [
+            'formatted_name' => [
+                'name',
+                'price'
+            ],
+            
+            'formatted_price'
+        ];
+    }
+
+    /**
+     * Get the allowed sorts
+     *
+     * @return array
+     */
+    public function getAllowedSorts(): array
+    {
+        return [
+            'id',
+            'created_at',
+            'updated_at',
+            'slug',
+            'name',
+        ];
+    }
+
+    /**
+     * Get the default sort
+     *
+     * @return string
+     */
+    public function getDefaultSort(): string
+    {
+        return '-created_at';
+    }
+
+    /**
+     * Get the allowed filters
+     *
+     * @return array
+     */
+    public function getAllowedFilters(): array
+    {
+        return [
+            'id',
+            'slug',
+            'name',            
+            AllowedFilter::scope('search'),
+        ];
+    }
+}
+```
+
+The controller will have an `index` and `show` method which you can use to define your routes in your `api.php` route file.
+
+```php
+// in api.php route file
+
+/**
+ * Products
+ */
+Route::get('products', [\App\Controllers\Api\ProductsController::class, 'index'])->name('products.index');
+Route::get('products/{id}', [\App\Controllers\Api\ProductsController::class, 'show'])->name('products.show');
+```
+
+The following methods will have to be implemented in your controller:
+
+## getBaseQuery()
+ 
+This method used to define your base query. It should return a `Illuminate\Database\Eloquent\Builder` instance.
+This builder instance will be passed to the `Javaabu\QueryBuilder\QueryBuilder\QueryBuilder::for()` method. 
+
+```php
+public function getBaseQuery(): Builder
+{
+    return Product::query();
+}
+```
+
+## getAllowedFields()
+
+Used to define which fields that users will be allowed to request through the `?fields=` query parameter. 
+If the user doesn't include the `fields` parameter, then all fields defined here will be included by default.
+
+```php
+public function getAllowedFields(): array
+{
+    return array_diff(\Schema::getColumnListing('products'), (new Product)->getHidden());
+}
+```
+
+## getAllowedIncludes()
+
+Used to define which relations that users will be allowed to request through the `?include=` query parameter.
+If the user doesn't include the `include` parameter, then all relations defined here will be included by default.
+To not include any relation in a request, the user should submit a blank `?include=` parameter.
+
+```php
+public function getAllowedIncludes(): array
+{
+    return [
+        'category'
+    ];
+}
+```
+
+## getAllowedAppends()
+
+Used to define which accessor attibutes that users will be allowed to request through the `?append=` query parameter.
+If the user doesn't include the `append` parameter, then all appends defined here will be included by default.
+To not include any append in a request, the user should submit a blank `?append=` parameter.
+
+Note that append fields can also be requested through the `fields` query parameter as well.
+
+```php
+public function getAllowedAppends(): array
+{
+    return [             
+        'formatted_price'
+    ];
+}
+```
+
+If an append depends on other database columns, then you can specify those fields as an array.
+For example, `formatted_name` of the product might be `':name (:price)`. In this case, both `name` and `price` columns are required to generate the `formatted_name`.
+If you do not include these columns, the user will get a blank value for `formatted_name` if they don't specifically include `name` and `price` in the fields, when doing a request like `?fields=id,formatted_name`.
+
+```php
+public function getAllowedAppends(): array
+{
+    return [             
+        'formatted_name' => [
+            'name',
+            'price'
+        ],
+    ];
+}
+```
+
+## getAllowedSorts()
+
+Defines which fields that the user can sort the records by using the `?sort=` query param. Applies only to the `index` method.
+To sort in descending order, users can append a `-` to the field name, e.g. `?sort=-created_at` in the query parameter.
+To sort by multiple fields, users can provide a comma-separated list, e.g. `?sort=id,-created_at`
+
+```php
+public function getAllowedSorts(): array
+{
+    return [
+        'id',
+        'created_at',
+        'updated_at',
+        'slug',
+        'name',
+    ];
+}
+```
+
+## getDefaultSort()
+
+Defines the default sort to apply if the user doesn't provide any `sort` parameter.
+
+```php
+public function getDefaultSort(): string
+{
+    return '-created_at';
+}
+```
+
+Return an empty string if you don't want any default sort applied.
+
+```php
+public function getDefaultSort(): string
+{
+    return '';
+}
+```
+
+## getAllowedFilters()
+
+Defines the filters that users can apply using the `?filter[]` query parameter.
+
+```php
+public function getAllowedFilters(): array
+{
+    return [
+        'id',
+        'slug',
+        'name',            
+        AllowedFilter::scope('search'),
+    ];
+}
+```

docs/basic-usage/how-to-use-feature.md

@@ -1,6 +1,6 @@
 ---
 title: Changelog
-sidebar_position: 1.5
+sidebar_position: 1.6
 ---
 
 All notable changes to this package are documented on [GitHub](https://github.com/Javaabu/query-builder/blob/main/CHANGELOG.md)

docs/changelog.md

@@ -8,17 +8,3 @@ You can install the package via composer:
 ```bash
 composer require javaabu/query-builder
 ```
-
-# Publishing the config file
-
-Publishing the config file is optional:
-
-```bash
-php artisan vendor:publish --provider="Javaabu\QueryBuilder\QueryBuilderServiceProvider" --tag="query-builder-config"
-```
-
-This is the default content of the config file:
-
-```php
-// TODO
-```

docs/installation-and-setup.md

@@ -5,8 +5,9 @@ sidebar_position: 1.0
 
 # Query Builder
 
+First, refer to the [spatie/query-builder](https://github.com/spatie/laravel-query-builder) docs for full usage on the Query Builder package.
 
-[Query Builder](https://github.com/Javaabu/query-builder) Modifications on top of spatie/query-builder.
+[Query Builder](https://github.com/Javaabu/query-builder) Modifications on top of [spatie/query-builder](https://github.com/spatie/laravel-query-builder).
 Provides helper classes for creating API controllers and supports [Scribe](https://github.com/knuckleswtf/scribe/) for automatically generating API docs.
 
 For example, if you have a `Product` model, you can create an API controller like so:

docs/intro.md

@@ -1,6 +1,6 @@
 ---
 title: Questions and Security
-sidebar_position: 1.4
+sidebar_position: 1.5
 ---
 
 Find yourself stuck using the package? Found a bug? Do you have general questions or suggestions for improving this package? Feel free to create an [issue](../../issues) on GitHub, we'll try to address it as soon as possible.

docs/questions-and-security.md

@@ -1,6 +1,6 @@
 ---
 title: Upgrade Guide
-sidebar_position: 1.2
+sidebar_position: 1.3
 ---
 
 ## Migration from v2 to v3