Merge pull request #58 from one2tek/2.x

2.x

docs/appends.md → docs/1.x/appends.md

@@ -8,4 +8,12 @@ The following example appends `isAdmin` attribute:
 
 ```url
 {base_url}/users?append[]=isAdmin
+```
+
+# Append multiple
+
+You can append multiple attributes separating them with a comma:
+
+```url
+{base_url}/users?append[]=isAdmin,isDriver
 ```

docs/scopes.md → docs/1.x/scopes.md

@@ -19,4 +19,12 @@ The following query parameter will remove the `delivered` global scope:
 
 ```url
 {base_url}/books?excludeGlobalScopes[]=delivered
+```
+
+# Select multiple
+
+You can select multiple scopes separating them with a comma:
+
+```url
+{base_url}/users?scope[]=popular,famous
 ```

docs/2.x/README.md

@@ -0,0 +1,26 @@
+## Larapi
+
+> Build fast API-s in Laravel.
+
+## What it is
+
+Larapi is a package thats offers you to do modern API development in Laravel with support for new versions of Laravel.
+
+## Features
+
+- Exception handler for APIs.
+- A Controller class that gives response, parse data for your endpoints.
+- A Repository class for requesting entities from your database.
+- Sorting.
+- Filtering.
+- Eager loading.
+- Pagination.
+- Selecting columns dynamically.
+- Selecting scopes dynamically.
+- Appends.
+- A class for making internal API requests.
+
+## Authors
+
+- Gentrit Abazi (https://github.com/gentritabazi01)
+- Veton Muhaxhiri (https://github.com/VetonMuhaxhiri)

docs/2.x/_coverpage.md

@@ -0,0 +1,7 @@
+
+# Larapi
+
+> Build fast API-s in Laravel.
+
+[GitHub](https://github.com/one2tek/larapi)
+[Get Started](README.md)

docs/2.x/_sidebar.md

@@ -0,0 +1,58 @@
+- Getting started
+  - [Quick start](README.md)
+  - [Installation](installation.md)
+  - [Configuration](configuration.md)
+
+- Selecting fields
+  - [Quick start](selecting_fields.md?id=selecting-fields)
+  - [Basic usage](selecting_fields.md?id=basic-usage)
+  - [Selecting fields for included relations](selecting_fields.md?id=selecting-fields-for-included-relations)
+
+- Scopes
+  - [Quick start](scopes.md?id=scopes)
+  - [Usage](scopes.md?id=usage)
+  - [Remove Global Scopes](scopes.md?id=remove-global-scopes)
+
+- Appends
+  - [Quick start](appends.md?id=appends)
+  - [Usage](appends.md?id=usage)
+
+- Including relationships
+  - [Quick start](including_relationships.md?id=including-relationships)
+  - [Basic usage](including_relationships.md?id=basic-usage)
+  - [Load multiple](including_relationships.md?id=load-multiple)
+  - [Load nested](including_relationships.md?id=load-nested)
+  - [Counting related relations](including_relationships.md?id=counting-related-relations)
+  - [Querying Relationship Existence](including_relationships.md?id=querying-relationship-existence)
+  - [Querying Relationship Absence](including_relationships.md?id=querying-relationship-absence)
+
+- Pagination
+  - [Quick start](pagination.md?id=pagination)
+  - [Usage](pagination.md?id=usage)
+
+- Sorting
+  - [Quick start](sorting.md?id=sorting)
+  - [Usage](sorting.md?id=usage)
+  - [Sort multiple columns](sorting.md?id=sort-multiple-columns)
+
+- Filtering
+  - [Quick start](filtering.md?id=filtering)
+  - [Operators](filtering.md?id=operators)
+  - [Build filter](filtering.md?id=build-filter)
+  - [Example filters](filtering.md?id=example-filters)
+
+- Repository
+  - [Quick start](repository.md?id=repository)
+  - [Create repository](repository.md?id=create-repository)
+  - [Default sort](repository.md?id=default-sort)
+  - [Functions](repository.md?id=functions)
+
+- Exception Handler
+  - [Quick start](exception_handler.md?id=exception-handler)
+  - [Configure](exception_handler.md?id=configure)
+  - [Formatters](exception_handler.md?id=formatters)
+
+- Advanced Usage
+  - [Quick start](advanced_usage.md?id=avanced_usage)
+  - [Custom Sort](advanced_usage.md?id=custom-sort)
+  - [Custom Filter](advanced_usage.md?id=custom-filter)

docs/2.x/advanced_usage.md

@@ -0,0 +1,25 @@
+# Advanced Usage
+
+Learn how to use `Larapi` in Advanced usage.
+
+# Custom Sort
+
+You can create custom sort in your repository like this:
+
+```php
+public function sortMyName($queryBuilder, $direction)
+{
+    // 
+}
+```
+
+# Custom Filter
+
+You can create custom filter in your repository like this:
+
+```php
+public function filterName($queryBuilder, $method, $operator, $value, $clauseOperator, $or)
+{
+    // 
+}
+```

docs/2.x/appends.md

@@ -0,0 +1,19 @@
+# Appends
+
+With Laravel you can add attributes that do not have a corresponding column in your database.
+
+# Usage
+
+The following example appends `isAdmin` attribute:
+
+```url
+{base_url}/users?append=isAdmin
+```
+
+# Append multiple
+
+You can append multiple attributes separating them with a comma:
+
+```url
+{base_url}/users?append=isAdmin,isDriver
+```

docs/2.x/configuration.md

@@ -0,0 +1,64 @@
+## Configuration
+
+> [Check how to use in real application.](https://github.com/gentritabazi01/Clean-Laravel-Api)
+
+1. Extends `one2tek\larapi\Controllers\LaravelController` in your base controller. 
+
+```php
+<?php
+use one2tek\larapi\Controllers\LaravelController; 
+
+class Controller extends LaravelController {
+    // ...
+}
+```
+
+2. Extends `one2tek\larapi\Database\Repository` in your base repository.
+
+```php
+<?php
+use one2tek\larapi\Database\Repository as BaseRepository; 
+
+abstract class Repository extends BaseRepository {
+    // ...
+} 
+```
+
+3. Example Controller or Service for Users.
+
+```php
+<?php
+use App\Http\Repositories\UserRepository; 
+
+class UsersController extends Controller
+{ 
+    private $userRepository; 
+
+    public function __construct(UserRepository $userRepository)
+    {
+        $this—>userRepository = $userRepository; 
+    }
+
+    public function getAll()
+    {
+        $resourceOptions = $this—>parseResourceOptions();
+
+        $users = $this—>userRepository—>get($resourceOptions);
+
+        return $this—>response($users);
+    }
+}
+```
+
+4. Example Repository for Users.
+
+```php
+<?php
+class UserRepository extends Repository
+{
+    public function getModel()
+    {
+        return new User();
+    }
+}
+```

docs/2.x/exception_handler.md

@@ -0,0 +1,57 @@
+# Exception Handler
+
+`Larapi` included a Laravel exception handler build specifically for APIs.
+When building APIs there are specific formatting do's and dont's on how to send errors back to the user. Frameworks like Laravel are not build specifically for API builders. `Larapi` bridges that gap. For instance, specifications like [JSON API](https://jsonapi.org/) have [guidelines for how errors should be formatted](https://jsonapi.org/format/#error-objects).
+
+# Configure
+
+Open `Handler.php` and modify function `render` like below:
+
+```php
+use one2tek\larapi\Exceptions\ApiException;
+
+public function render($request, Throwable $e)
+{
+    $apiException = new ApiException($request, $e);
+
+    return $apiException->generateExceptionResponse();
+}
+```
+
+# Formatters
+
+`Larapi` already comes with sensible formatters out of the box. In `config/larapi.php` is a section where the formatter priority is defined.
+
+```php
+'exceptions_formatters' => [
+    Symfony\Component\HttpKernel\Exception\UnprocessableEntityHttpException::class => one2tek\larapi\ExceptionsFormatters\UnprocessableEntityHttpExceptionFormatter::class,
+    Throwable::class => one2tek\larapi\ExceptionsFormatters\ExceptionFormatter::class
+]
+```
+
+You can write custom formatters easily:
+
+```php
+<?php
+
+namespace Infrastructure\ExceptionsFormatters;
+
+class NotFoundHttpExceptionFormatter
+{
+    const STATUS_CODE = 404;
+    const MESSAGE = 'Page Not Found.';
+
+    public function format($request, $e)
+    {
+        $data = [
+            'success' => false,
+            'status' => self::STATUS_CODE,
+            'message' => self::MESSAGE
+        ];
+
+        return response()->json($data, self::STATUS_CODE);
+    }
+}
+```
+
+Now you just need to add it to `config/larapi.php` and all `NotFoundHttpExceptions` will be formatted using our custom formatter.

docs/2.x/filtering.md

@@ -0,0 +1,58 @@
+# Filtering
+
+Data filtering is very easy with at `Larapi` see the examples below.
+
+By default, all filters have to be explicitly allowed using `$whiteListFilter` property in specified Model. 
+
+For more advanced use cases, [custom filter](advanced_usage?id=custom-filter) can be used.
+
+#### Operators
+
+Type | Description
+---- | -----------
+ct | String contains
+sw | Starts with
+ew | Ends with
+eq | Equals
+gt | Greater than
+gte| Greater than or equalTo
+lt | Lesser than
+lte | Lesser than or equalTo
+in | In array
+bt | Between
+
+#### Build filter
+
+The way a filter should be formed is:
+
+```url
+{base_url}/users?filter[columnName][operator][not]=value
+```
+
+Another available parameter is `filterByOr`, `search` and `searchByOr`. 
+
+* **columnName** -  (Required) - Name of column you want to filter, for relationships use `dots`.
+* **operator** - (Optional | Default: `eq`) Type of operator you want to use.
+* **not** - (Optional | Default: `false`) Negate the filter (Accepted values: yes|true|1).
+
+#### Example filters
+
+Filter all users whose id start with `1000`.
+
+```url
+{base_url}/users?filter[name][sw]=1000
+```
+
+Filter all books whose author is `Gentrit`.
+
+```url
+{base_url}/users?filter[name]=author.name
+```
+
+Filter all users whose name start with `Gentrit` or ends with `Abazi`.
+
+```url
+{base_url}/users?filterByOr[name][sw]=Gentrit&filterByOr[name][ew]=Abazi
+```
+
+[See other ways for filtering](filters_old.md)