Merge branch 'release/1.2.0'

Author: lindyhopchris

CHANGELOG.md

@@ -2,6 +2,28 @@
 All notable changes to this project will be documented in this file. This project adheres to
 [Semantic Versioning](http://semver.org/) and [this changelog format](http://keepachangelog.com/).
 
+## [1.2.0] - 2019-06-20
+
+### Added
+- [#360](https://github.com/cloudcreativity/laravel-json-api/issues/360)
+Allow soft delete attribute path to use dot notation.
+- Added `domain` method to API fluent routing methods.
+- [#337](https://github.com/cloudcreativity/laravel-json-api/issues/337)
+Can now apply global scopes to JSON API resources via [adapter scopes.](./docs/basics/adapters.md#scopes)
+
+### Fixed
+- [#370](https://github.com/cloudcreativity/laravel-json-api/pull/370)
+Fix wrong validation error title when creating a custom validator.
+- [#369](https://github.com/cloudcreativity/laravel-json-api/issues/369)
+Fix using an alternative decoding type for update (`PATCH`) requests.
+- [#362](https://github.com/cloudcreativity/laravel-json-api/issues/362)
+Fix fatal error in route class caused by polymorphic entity types.
+- [#358](https://github.com/cloudcreativity/laravel-json-api/issues/358)
+Queue listener could trigger a `ModelNotFoundException` when deserializing a job that had deleted a
+model during its `handle()` method.
+- [#347](https://github.com/cloudcreativity/laravel-json-api/issues/347)
+Update `zend-diactoros` dependency.
+
 ## [1.1.0] - 2019-04-12
 
 ### Added

composer.json

@@ -35,7 +35,7 @@
         "neomerx/json-api": "^1.0.3",
         "ramsey/uuid": "^3.0",
         "symfony/psr-http-message-bridge": "^1.0",
-        "zendframework/zend-diactoros": "^1.3"
+        "zendframework/zend-diactoros": "^1.0|^2.0"
     },
     "require-dev": {
         "ext-sqlite3": "*",

docs/basics/adapters.md

@@ -495,6 +495,58 @@ modify this default behaviour and expose soft-deleting capabilities to the clien
 
 See the [Soft Deleting](../features/soft-deletes.md) for information on implementing this.
 
+### Scopes
+
+Eloquent adapters allow you to apply scopes to your API resources, using Laravel's
+[global scopes](https://laravel.com/docs/eloquent#global-scopes) feature. When a scope is applied
+to an Eloquent adapter, any routes that return that API resource in the response content will have
+the scope applied.
+
+> An example use case for this would be if your API only contains resources related to the current signed
+in user. In this case, you would only ever want resources owned by that user to appear in the API. I.e.
+from the client's perspective, any resources belonging to other users do not exist. In this case, a global
+scope would ensure that a `404 Not Found` is returned for resources that belong to other users.
+
+> In contrast, if your API serves a mixture of resources belonging to different users, then 
+`401 Unauthorized` or `403 Forbidden` responses might be more appropriate when attempting to access other
+users' resources. In this scenario, [Authorizers](./security.md) would be a better approach than global
+scopes.
+
+Scopes can be added to an Eloquent adapter as either scope classes or as closure scopes. To use the former,
+write a class that implements Laravel's `Illuminate\Database\Eloquent\Scope` interface. The class can then
+be added to your adapter using constructor dependency injection and the `addScopes` method:
+
+```php
+namespace App\JsonApi\Posts;
+
+use CloudCreativity\LaravelJsonApi\Eloquent\AbstractAdapter;
+
+class Adapter extends AbstractAdapter
+{
+
+    public function __construct(\App\Scopes\UserScope $scope)
+    {
+      parent::__construct(new \App\Post());
+      $this->addScopes($scope);
+    }
+
+    // ...
+}
+```
+
+> Using a class scope allows you to reuse that scope across multiple adapters.
+
+If you prefer to use a closure for your scope, these can be added to an Eloquent adapter using the
+`addClosureScope` method. For example, in our `AppServiceProvider::register()` method:
+
+```php
+$this->app->afterResolving(\App\JsonApi\Posts\Adapter::class, function ($adapter) {
+  $adapter->addClosureScope(function ($query) {
+    $query->where('author_id', \Auth::id());
+  });
+});
+```
+
 ## Custom Adapters
 
 Custom adapters can be used for any domain record that is not an Eloquent model. Adapters will work with this

docs/features/async.md

@@ -217,6 +217,43 @@ class ProcessPodcast implements ShouldQueue
 }
 ```
 
+## Manually Marking Client Jobs as Complete
+
+This package will, in most cases, automatically mark the stored representation of the job as complete.
+We do this by listening the Laravel's queue events.
+
+There is one scenario where we cannot do this: if your job deletes a model during its `handle` method.
+This is because we cannot deserialize the job in our listener without causing a `ModelNotFoundException`.
+
+In these scenarios, you will need to manually mark the stored representation of the job as complete.
+Use the `didComplete()` method, which accepts one argument: a boolean indicating success (will be
+`true` if not provided).
+
+For example:
+
+```php
+namespace App\Jobs;
+
+use CloudCreativity\LaravelJsonApi\Queue\ClientDispatchable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+
+class RemovePodcast implements ShouldQueue
+{
+
+    use ClientDispatchable;
+
+    // ...
+
+    public function handle()
+    {
+        // ...logic to remove a podcast.
+
+        $this->podcast->delete();
+        $this->didComplete();
+    }
+}
+```
+
 ## Routing
 
 The final step of setup is to enable asynchronous process routes on a resource. These

docs/features/media-types.md

@@ -504,6 +504,8 @@ the request as its first argument. For a create request, the argument will be `n
 resource. E.g. `GET /api/v1/posts` or when the resource is in a relationship such as
 `GET /api/v1/users/1/posts`.
 
+#### Encoding Example
+
 For example, say we wanted to support returning an avatar's image via our API we would need to
 support the media type of the stored avatar. Our avatar content negotiator may look like this:
 
@@ -534,7 +536,7 @@ class ContentNegotiator extends BaseContentNegotiator
 ```
 
 In this example, `encodingMediaTypes()` returns the list of the encodings supported by our API. The
-`when` method adds an encoding to the list if the first argument is true - in this case, if the
+`when` method adds an encoding to the list if the first argument is `true` - in this case, if the
 request method is `GET`.
 
 > The `EncodingList` class also has an `unless` method, along with other helper methods.
@@ -594,6 +596,9 @@ class ContentNegotiator extends BaseContentNegotiator
 }
 ```
 
+> The `MultipartDecoder` is a decoder you will need to write with your own logic. There's an
+example of what a decoder might look like below.
+
 The media types listed on your content negotiator are **added** to the list of media types that
 your API supports. They will be used for every controller action that the content negotiator
 is used for.
@@ -609,12 +614,35 @@ be `null`.
 relationship object. E.g. `POST /api/v1/posts/1/tags`. This method receives the domain record for
 the request as its first arguments, and the relationship field name as its second argument.
 
+#### Decoding Example
+
 For example, if we wanted to support uploading an Avatar image to create an `avatars` resource,
-our content negotiator could be:
+we would need to write a decoder that handled files:
 
 ```php
+namespace App\JsonApi;
 
-namespace DummyApp\JsonApi\Avatars;
+use CloudCreativity\LaravelJsonApi\Contracts\Decoder\DecoderInterface;
+
+class MultipartDecoder implements DecoderInterface
+{
+
+    /**
+     * @inheritdoc
+     */
+    public function decode($request): array
+    {
+        // return whatever array data you expect from the request.
+        // in this example we are expecting a file, so we will return all files.
+        return $request->allFiles();
+    }
+}
+```
+
+Then we would need to use this decoder in our `avatars` content negotiator:
+
+```php
+namespace App\JsonApi\Avatars;
 
 use App\Avatar;
 use App\JsonApi\MultipartDecoder;

docs/features/soft-deletes.md

@@ -172,6 +172,8 @@ class Adapter extends AbstractAdapter
 }
 ```
 
+> You can use dot notation for the `$softDeleteField` value, if you are using a nested attribute field.
+
 The client can now send the following request to soft-delete a resource:
 
 ```http

src/Contracts/Resolver/ResolverInterface.php

@@ -37,7 +37,7 @@ public function isType($type);
      * Get the domain record type for the supplied JSON API resource type.
      *
      * @param string $resourceType
-     * @return string|null
+     * @return string|string[]|null
      */
     public function getType($resourceType);
 

src/Eloquent/AbstractAdapter.php

@@ -28,6 +28,7 @@
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations;
+use Illuminate\Database\Eloquent\Scope;
 use Illuminate\Support\Collection;
 use Neomerx\JsonApi\Contracts\Encoder\Parameters\EncodingParametersInterface;
 use Neomerx\JsonApi\Encoder\Parameters\EncodingParameters;
@@ -86,6 +87,11 @@ abstract class AbstractAdapter extends AbstractResourceAdapter
      */
     protected $defaultPagination = null;
 
+    /**
+     * @var array
+     */
+    private $scopes;
+
     /**
      * Apply the supplied filters to the builder instance.
      *
@@ -105,6 +111,7 @@ public function __construct(Model $model, PagingStrategyInterface $paging = null
     {
         $this->model = $model;
         $this->paging = $paging;
+        $this->scopes = [];
     }
 
     /**
@@ -130,8 +137,12 @@ public function query(EncodingParametersInterface $parameters)
      */
     public function queryToMany($relation, EncodingParametersInterface $parameters)
     {
+        $this->applyScopes(
+            $query = $relation->newQuery()
+        );
+
         return $this->queryAllOrOne(
-            $relation->newQuery(),
+            $query,
             $this->getQueryParameters($parameters)
         );
     }
@@ -148,8 +159,12 @@ public function queryToMany($relation, EncodingParametersInterface $parameters)
      */
     public function queryToOne($relation, EncodingParametersInterface $parameters)
     {
+        $this->applyScopes(
+            $query = $relation->newQuery()
+        );
+
         return $this->queryOne(
-            $relation->newQuery(),
+            $query,
             $this->getQueryParameters($parameters)
         );
     }
@@ -210,6 +225,49 @@ public function findMany(array $resourceIds)
         return $this->findManyQuery($resourceIds)->get()->all();
     }
 
+    /**
+     * Add scopes.
+     *
+     * @param Scope ...$scopes
+     * @return $this
+     */
+    public function addScopes(Scope ...$scopes): self
+    {
+        foreach ($scopes as $scope) {
+            $this->scopes[get_class($scope)] = $scope;
+        }
+
+        return $this;
+    }
+
+    /**
+     * Add a global scope using a closure.
+     *
+     * @param \Closure $scope
+     * @param string|null $identifier
+     * @return $this
+     */
+    public function addClosureScope(\Closure $scope, string $identifier = null): self
+    {
+        $identifier = $identifier ?: spl_object_hash($scope);
+
+        $this->scopes[$identifier] = $scope;
+
+        return $this;
+    }
+
+    /**
+     * @param Builder $query
+     * @return void
+     */
+    protected function applyScopes($query): void
+    {
+        /** @var Scope $scope */
+        foreach ($this->scopes as $identifier => $scope) {
+            $query->withGlobalScope($identifier, $scope);
+        }
+    }
+
     /**
      * Get a new query builder.
      *
@@ -220,7 +278,11 @@ public function findMany(array $resourceIds)
      */
     protected function newQuery()
     {
-        return $this->model->newQuery();
+        $this->applyScopes(
+            $builder = $this->model->newQuery()
+        );
+
+        return $builder;
     }
 
     /**

src/Eloquent/Concerns/SoftDeletesModels.php

@@ -21,6 +21,7 @@
 use CloudCreativity\LaravelJsonApi\Utils\Str;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Schema\Builder;
+use Illuminate\Support\Arr;
 use Illuminate\Support\Collection;
 use Neomerx\JsonApi\Contracts\Encoder\Parameters\EncodingParametersInterface;
 
@@ -61,13 +62,14 @@ protected function findQuery($resourceId)
     protected function fillAttributes($record, Collection $attributes)
     {
         $field = $this->getSoftDeleteField($record);
+        $attributesArr = $attributes->toArray();
 
-        if ($attributes->has($field)) {
-            $this->fillSoftDelete($record, $field, $attributes->get($field));
+        if (Arr::has($attributesArr, $field)) {
+            $this->fillSoftDelete($record, $field, Arr::get($attributesArr, $field));
         }
 
         $record->fill(
-            $this->deserializeAttributes($attributes->forget($field), $record)
+            $this->deserializeAttributes(Arr::except($attributesArr, $field), $record)
         );
     }
 

src/Facades/JsonApi.php

@@ -20,17 +20,17 @@
 
 use CloudCreativity\LaravelJsonApi\Routing\ApiRegistration;
 use CloudCreativity\LaravelJsonApi\Routing\Route;
-use Illuminate\Support\Facades\Facade as BaseFacade;
+use Illuminate\Support\Facades\Facade;
 
 /**
- * Class Facade
+ * Class JsonApi
  *
  * @package CloudCreativity\LaravelJsonApi
  * @method static ApiRegistration register(string $apiName, array|\Closure $options = [], \Closure|null $callback = null)
  * @method static string defaultApi(string|null $apiName)
  * @method static Route currentRoute()
  */
-class JsonApi extends BaseFacade
+class JsonApi extends Facade
 {
 
     /**