Merge branch 'release/1.4.0'

Author: lindyhopchris

.gitignore

@@ -1,2 +1,3 @@
 vendor/
 composer.lock
+.phpunit.result.cache

.travis.yml

@@ -36,11 +36,6 @@ matrix:
       env:
         - LARAVEL_VERSION=^6.0
         - PHPUNIT_VERSION=^8.0
-  allow_failures:
-    - php: "7.3"
-      env:
-        - LARAVEL_VERSION=^6.0
-        - PHPUNIT_VERSION=^8.0
 
 install:
   - composer require "laravel/framework:${LARAVEL_VERSION}" --no-update -n

CHANGELOG.md

@@ -2,6 +2,16 @@
 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.4.0] - 2019-09-04
+
+### Added
+- Package now supports Laravel 6.
+- [#333](https://github.com/cloudcreativity/laravel-json-api/issues/333)
+Eloquent adapters now have a `filterWithScopes()` method, that maps JSON API filters to
+model scopes and the Eloquent `where*` method names. This is opt-in: i.e. to use, the
+developer must call `filterWithScopes()` within their adapter's `filter()` method.
+- Added `put`, `putAttr` and `putRelation` methods to the `ResourceObject` class.
+
 ## [1.3.1] - 2019-08-19
 
 ### Fixed

README.md

@@ -69,7 +69,10 @@ A demo application is available at [here](https://github.com/cloudcreativity/dem
 | `5.5.*` | `^1.0` |
 
 Make sure you consult the [Upgrade Guide](http://laravel-json-api.readthedocs.io/en/latest/upgrade/) 
-when upgrading.
+when upgrading between major or pre-release versions.
+
+> You may notice that there are `2.0.0-alpha` tags. We **do not** recommend using these versions
+> until we hit `beta` releases.
 
 ## Lumen
 

composer.json

@@ -39,7 +39,7 @@
     },
     "require-dev": {
         "ext-sqlite3": "*",
-        "cloudcreativity/json-api-testing": "^1.1",
+        "cloudcreativity/json-api-testing": "^1.2",
         "composer/semver": "^1.5",
         "guzzlehttp/guzzle": "^6.3",
         "mockery/mockery": "^1.1",
@@ -78,7 +78,7 @@
             }
         }
     },
-    "minimum-stability": "dev",
+    "minimum-stability": "stable",
     "prefer-stable": true,
     "config": {
         "sort-packages": true

docs/basics/adapters.md

@@ -96,6 +96,9 @@ class Adapter extends AbstractAdapter
 }
 ```
 
+If your resource supports client-generated ids, refer to the client-generated ids section in the
+[Creating Resources chapter.](../crud/creating.md)
+
 ### Attributes
 
 When filling a model with attributes received in a JSON API request, the adapter will convert the JSON API
@@ -707,19 +710,8 @@ class Adapter extends AbstractAdapter
 }
 ```
 
-Or if your resource uses a client-generated ID, you can assign the id in the `creating` hook:
-
-```php
-class Adapter extends AbstractAdapter
-{
-    // ...
-    
-    protected function creating(Comment $comment, $resource): void
-    {
-        $comment->{$comment->getRouteKeyName()} = $resource['id']; 
-    }
-}
-```
+> If your resource uses a [client-generated ID](../crud/creating.md#client-generated-ids), you 
+will need to use the `creating` hook to assign the id to the model.
 
 There are two additional hooks that are invoked when an adapter is deleting a resource: `deleting` and `deleted`.
 These receive the record being deleted as the first function argument.

docs/crud/creating.md

@@ -1,3 +1,133 @@
 # Creating Resources
 
-@todo
+A resource can be created by sending a `POST` request to the URL that represents the collection
+of resources. For example, a new `posts` resource might be created with the following request:
+
+```php
+POST /posts HTTP/1.1
+Content-Type: application/vnd.api+json
+Accept: application/vnd.api+json
+
+{
+    "data": {
+        "type": "posts",
+        "attributes": {
+            "title": "Hello World",
+            "content": "..."
+        },
+        "relationships": {
+            "tags": {
+                "data": [
+                    {
+                        "type": "tags",
+                        "id": "1"
+                    }
+                ]
+            }
+        }
+    }
+}
+``` 
+
+This will result in the following response (depending on what is in your `posts` `Schema` class):
+
+```php
+HTTP/1.1 201 Created
+Location: http://example.com/api/posts/1
+Content-Type: application/vnd.api+json
+
+{
+    "data": {
+        "type": "posts",
+        "id": "1",
+        "attributes": {
+            "title": "Hello World",
+            "content": "..."
+        },
+        "relationships": {
+            "tags": {
+                "links": {
+                    "self": "http://example.com/api/posts/1/relationships/tags",
+                    "related": "http://example.com/api/posts/1/tags"
+                }
+            }
+        },
+        "links": {
+            "self": "http://example.com/api/posts/1"
+        }
+    }
+}
+```
+
+## Requirements
+
+For this to work, you must:
+
+- add the `posts` resource in your API's config, in the `resources` array; and
+- register [routes](../basics/routing.md) for your `posts` resource; and
+- create the [validators](../basics/validators.md), [adapter](../basics/adapters.md) and
+[schema](../basics/schemas.md) classes for the `posts` resource; and
+- optionally set up an [authorizer](../basics/security.md) class if you want to authorize the request.
+
+## Supported Query Parameters
+
+The following JSON API query parameters are supported for this request:
+
+- [inclusion of related resources](../fetching/inclusion.md)
+- [sparse fieldsets](../fetching/sparse-fieldsets.md)
+
+> Filter, page and sort parameters are not supported because this endpoint returns a single resource
+object as its primary data.
+
+## Client Generated IDs
+
+By default the server will reject a request to create a resource with a client-generated id. Any
+such requests will receive a `403 Forbidden` response, as defined in the JSON API spec.
+
+However you can easily enable client-generated ids for a resource by adding a rule to your
+validators class, and using the `creating` hook on your adapter.
+
+On your validators class, add a validation rule for the `id`. This tells the validators that
+it can accept a client-generated id. For example:
+
+```php
+class Validators extends AbstractValidators
+{
+    // ...
+    
+    protected function rules($record = null): array
+    {
+        return [
+            'id' => 'required|regex:/' . \Ramsey\Uuid\Uuid::VALID_PATTERN . '/',
+            // ... other rules
+        ];
+    }
+}
+```
+
+> Note that you **do not** need to check whether the id already exists. The JSON API spec
+defines that the server must respond with a `409 Conflict` response when processing
+a request to create a resource with a client-generated id that already exists. This package
+therefore checks any ids provided by the client and sends the `409 Conflict` response if
+they already exist.
+
+The final step is to use the `creating` hook in your adapter class to transfer the
+client-generated id to your model:
+
+```php
+class Adapter extends AbstractAdapter
+{
+
+    // ...
+
+    /**
+     * @param Video $video
+     * @param $resource
+     * @return void
+     */
+    protected function creating(Video $video, $resource)
+    {
+        $video->{$video->getKeyName()} = $resource['id'];
+    }
+}
+```

docs/fetching/filtering.md

@@ -11,7 +11,8 @@ highly coupled with the application's logic and choice of data storage.
 This package therefore provides the following capabilities:
 
 - Validation of the `filter` parameter.
-- An easy hook in the Eloquent adapter to convert validated filter parameters to database queries. 
+- An easy hook in the Eloquent adapter to convert validated filter parameters to database queries.
+- An opt-in implementation to map JSON API filters to model scopes and/or Eloquent's magic `where*` method.
 
 ## Example Requests
 
@@ -72,37 +73,15 @@ class Validators extends AbstractValidators
 
 ## Validation
 
-Filter parameters should always be validated to ensure that their use in database queries is valid. You can
-validate them in your [Validators](../basics/validators.md) query rules. For example:
+Filter parameters should always be validated to ensure that their use in database queries is valid. 
+You can validate them in your [Validators](../basics/validators.md) query rules. For example:
 
 ```php
 class Validators extends AbstractValidators
 {
     // ...
 
-    protected function queryRules(): array
-    {
-        return [
-            'filter.title' => 'filled|string',
-            'filter.slug' => 'filled|string',
-            'filter.authors' => 'array|min:1',
-            'filter.authors.*' => 'integer',
-        ];
-    }
-
-}
-```
-
-By default we allow a client to submit any filter parameters as we assume that you will validate the values
-of expected filters as in the example above. However, you can whitelist expected filter parameters by listing
-them on the `$allowedFilteringParameters` of your validators class. For example:
-
-```php
-class Validators extends AbstractValidators
-{
-    // ...
-    
-    protected $allowedFilteringParameters = ['title', 'authors'];
+    protected $allowedFilteringParameters = ['title', 'slug', 'authors'];
 
     protected function queryRules(): array
     {
@@ -117,6 +96,9 @@ class Validators extends AbstractValidators
 }
 ```
 
+The above whitelists the allowed filter parameters, and then also validates the values that can be
+submitted for each.
+
 Any requests that contain filter keys that are not in your allowed filtering parameters list will be rejected
 with a `400 Bad Request` response, for example:
 
@@ -143,7 +125,75 @@ Content-Type: application/vnd.api+json
 The Eloquent adapter provides a `filter` method that allows you to implement your filtering logic.
 This method is provided with an Eloquent query builder and the filters provided by the client.
 
-For example, our `posts` adapter filtering implementation could be:
+### Filter Scopes
+
+A newly generated Eloquent adapter will use our `filterWithScopes()` implementation. For example:
+
+```php
+class Adapter extends AbstractAdapter
+{
+
+    // ...
+
+    /**
+     * Mapping of JSON API filter names to model scopes.
+     *
+     * @var array
+     */
+    protected $filterScopes = [];
+
+    /**
+     * @param Builder $query
+     * @param Collection $filters
+     * @return void
+     */
+    protected function filter($query, Collection $filters)
+    {
+        $this->filterWithScopes($query, $filters);
+    }
+}
+```
+
+The `filterWithScopes` method will map JSON API filters to model scopes, and pass the filter value to that scope.
+For example, if the client has sent a `filter[slug]` query parameter, we expect either there to be a 
+`scopeSlug` method on the model, or we will use Eloquent's magic `whereSlug` method.
+
+If you need to map a filter parameter to a different scope name, then you can define it here.
+For example if `filter[slug]` needed to be passed to the `onlySlug` scope, it can be defined
+as follows:
+
+```php
+protected $filterScopes = [
+    'slug' => 'onlySlug'
+];
+```
+
+If you want a filter parameter to not be mapped, define the mapping as `null`, for example:
+
+```php
+protected $filterScopes = [
+    'slug' => null
+];
+```
+
+Alternatively you could let some filters be applied using scopes, and then implement your own logic
+for others. For example:
+
+```php
+protected function filter($query, Collection $filters)
+{
+    $this->filterWithScopes($query, $filters->only('foo', 'bar', 'bat'));
+
+    if ($baz = $filters->get('baz')) {
+        // filter logic for baz.
+    }
+}
+```
+
+### Custom Filter Logic
+
+If you do not want to use our filter by scope implementation, then it is easy to implement your
+own logic. Remove the call to `filterWithScopes()` and insert your own logic. For example:
 
 ```php
 class Adapter extends AbstractAdapter
@@ -166,5 +216,7 @@ class Adapter extends AbstractAdapter
 }
 ```
 
-> As filters are also applied when filtering the resource through a relationship, it is good practice
+### Relationships
+
+Filters are also applied when filtering the resource through a relationship. It is good practice
 to qualify any column names.

docs/index.md

@@ -20,7 +20,7 @@ For full information on the spec, plus examples, see [http://jsonapi.org](http:/
 ## Tutorial
 
 Want a tutorial to get started? Read the
-[Laravel tutorial on the *How to JSON:API* website.]((https://howtojsonapi.com/laravel.html))
+[Laravel tutorial on the *How to JSON:API* website.](https://howtojsonapi.com/laravel.html)
 
 ## Demo