10000 Merge tag 'v0.10.0' into develop · startupengine/laravel-json-api@a1767b3 · GitHub
[go: up one dir, main page]
Skip to content

Commit a1767b3

Browse files
lindyhopchrislindyhopchris
committed
Merge tag 'v0.10.0' into develop
Update testing for Laravel 5.4 and add better JSON API helpers. Refer to changelog for details.
2 parents 0a8e087 + eb2dd6d commit a1767b3

File tree

8 files changed

+65
-79
lines changed

8 files changed

+65
-79
lines changed

‎CHANGELOG.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
All notable changes to this project will be documented in this file. This project adheres to
33
[Semantic Versioning](http://semver.org/) and [this changelog format](http://keepachangelog.com/).
44

5-
## Unreleased
5+
## [0.10.0] - 2017-07-29
66

77
### Added
88
- The resource registrar now automatically adds a JSON API's route URL and name prefixes.

‎README.md

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,12 @@ and [cloudcreativity/json-api](https://github.com/cloudcreativity/json-api).
1010

1111
From [jsonapi.org](http://jsonapi.org)
1212

13-
> If you've ever argued with your team about the way your JSON responses should be formatted, JSON API is your anti-bikeshedding weapon.
13+
> If you've ever argued with your team about the way your JSON responses should be formatted, JSON API is your
14+
anti-bikeshedding weapon.
1415
>
15-
> By following shared conventions, you can increase productivity, take advantage of generalized tooling, and focus on what matters: your application. Clients built around JSON API are able to take advantage of its features around efficiently caching responses, sometimes eliminating network requests entirely.
16+
> By following shared conventions, you can increase productivity, take advantage of generalized tooling, and focus
17+
on what matters: your application. Clients built around JSON API are able to take advantage of its features around
18+
efficiently caching responses, sometimes eliminating network requests entirely.
1619

1720
For full information on the spec, plus examples, see http://jsonapi.org
1821

@@ -27,7 +30,7 @@ We use semantic versioning but Laravel does not. This table will help...
2730
| Laravel | This Package |
2831
| --- | --- |
2932
| 5.3.* | ^0.9 |
30-
| 5.4.* | ^0.9 |
33+
| 5.4.* | ^0.10 |
3134

3235
Make sure you consult the [Upgrade Guide](http://laravel-json-api.readthedocs.io/en/latest/upgrade/) when upgrading.
3336

@@ -64,4 +67,4 @@ Please note the following:
6467
* **Bug Fixes** - submit a pull request against the `master` branch.
6568
* **Enhancements / New Features** - submit a pull request against the `develop` branch.
6669

67-
We'd recommend submitting an issue before taking the time to put together a pull request.
70+
We recommend submitting an issue before taking the time to put together a pull request.

‎composer.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@
5555
},
5656
"extra": {
5757
"branch-alias": {
58-
"dev-develop": "0.10.x-dev"
58+
"dev-develop": "0.11.x-dev"
5959
}
6060
},
6161
"minimum-stability": "stable",

‎docs/api.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -173,9 +173,11 @@ The generated API file contains a sensible default, for example:
173173
### Encoders
174174

175175
In the example, the config tells the codec matcher that the `application/vnd.api+json` and
176-
`text/plain` are valid `Accept` headers, along with how to encode responses for each type. If the client sends an `Accept` media type that is not recognised, a `406 Not Acceptable` response will be sent.
176+
`text/plain` are valid `Accept` headers, along with how to encode responses for each type. If the client sends an
177+
`Accept` media type that is not recognised, a `406 Not Acceptable` response will be sent.
177178

178-
> The options for how to encode responses for each media type are the same as the options for PHP's `json_encode()` function.
179+
> The options for how to encode responses for each media type are the same as the options for PHP's `json_encode()`
180+
function.
179181

180182
### Decoders
181183

‎docs/custom/controllers.md

Lines changed: 29 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -5,29 +5,19 @@ responses.
55

66
## Setup
77

8-
In order to send JSON API responses, you will need to apply the `ReplyTrait` to your controller. If your resource
9-
has a hydrator, you can also inject it via the constructor.
10-
11-
Here is an example controller:
8+
In order to send JSON API responses, you will need to apply the `CreatesResponses` trait to your controller. Here is
9+
an example controller:
1210

1311
```php
1412
namespace App\Http\Controllers\Api;
15-
16-
use App\JsonApi\Users;
13+
1714
use CloudCreativity\LaravelJsonApi\Http\Controllers\CreatesResponses;
1815
use Illuminate\Routing\Controller;
1916

2017
class UsersController extends Controller
2118
{
2219

2320
use CreatesResponses;
24-
25-
private $hydrator;
26-
27-
public function __construct(Users\Hydrator $hydrator)
28-
{
29-
$this->hydrator = $hydrator;
30-
}
3121

3222
// Methods as per below...
3323
}
@@ -53,12 +43,13 @@ correctly.
5343

5444
```php
5545
/**
46+
* @param \CloudCreativity\JsonApi\Contracts\Store\StoreInterface $store
5647
* @param \CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface $request
5748
* @return \Illuminate\Http\Response
5849
*/
59-
public function index(RequestInterface $request)
50+
public function index(StoreInterface $store, RequestInterface $request)
6051
{
61-
$records = $this->api()->getStore()->query(
52+
$records = $store->query(
6253
$request->getResourceType(),
6354
$request->getParameters()
6455
);
@@ -71,21 +62,20 @@ public function index(RequestInterface $request)
7162

7263
```php
7364
/**
74-
* @param \CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface $request
65+
* @param \App\JsonApi\Users\Hydrator $hydrator
66+
* @param \CloudCreativity\JsonApi\Contracts\Object\ResourceObjectInterface $resource
7567
* @return \Illuminate\Http\Response
7668
*/
77-
public function create(RequestInterface $request)
69+
public function create(Hydrator $hydrator, ResourceObjectInterface $resource)
7870
{
79-
$resource = $request->getDocument()->getResource();
71+
$record = new User();
72+
$hydrator->hydrate($resource, $record);
73+
8074
// As an example, if we wanted to wrap the change in a transaction...
81-
$record = \DB::transaction(function () use ($resource, $request) {
82-
$record = new User();
83-
$this->hydrator->hydrate($request->getDocument()->getResource(), $record);
75+
\DB::transaction(function () use ($record) {
8476
$record->save();
85-
86-
return $record;
8777
});
88-
78+
8979
return EF5E $this->reply()->created($record);
9080
}
9181
```
@@ -94,27 +84,27 @@ public function create(RequestInterface $request)
9484

9585
```php
9686
/**
97-
* @param \CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface $request
87+
* @param \App\User $record
9888
* @return \Illuminate\Http\Response
9989
*/
100-
public function read(RequestInterface $request)
90+
public function read(User $record)
10191
{
102-
return $this->reply()->content($request->getRecord());
92+
return $this->reply()->content($record);
10393
}
10494
```
95+
10596
### Update
10697

10798
```php
10899
/**
109-
* @param \CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface $request
100+
* @param \App\JsonApi\Users\Hydrator $hydrator
101+
* @param \CloudCreativity\JsonApi\Contracts\Object\ResourceObjectInterface $resource
102+
* @param \App\User $record
110103
* @return \Illuminate\Http\Response
111104
*/
112-
public function update(RequestInterface $request)
105+
public function update(Hydrator $hydrator, ResourceObjectInterface $resource, User $record)
113106
{
114-
/** @var User $record */
115-
$record = $request->getRecord();
116-
$resource = $request->getDocument()->getResource();
117-
$this->hydrator->hydrate($resource, $record);
107+
$hydrator->hydrate($resource, $record);
118108
$passwordChanged = $record->hasPasswordChanged();
119109
$record->save();
120110

@@ -131,13 +121,11 @@ public function update(RequestInterface $request)
131121

132122
```php
133123
/**
134-
* @param \CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface $request
124+
* @param \App\User $record
135125
* @return \Illuminate\Http\Response
136126
*/
137-
public function delete(RequestInterface $request)
127+
public function delete(User $record)
138128
{
139-
/** @var User $record */
140-
$record = $request->getRecord();
141129
$record->delete();
142130

143131
return $this->reply()->noContent();
@@ -159,11 +147,11 @@ If you link one resource to another through relationship, you'll need this to re
159147
```php
160148
/**
161149
* @param \CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface $request
150+
* @param \App\User $record
162151
* @return \Illuminate\Http\Response
163152
*/
164-
public function readRelatedResource(RequestInterface $request)
153+
public function readRelatedResource(RequestInterface $request, User $record)
165154
{
166-
$record = $request->getRecord();
167155
$key = $request->getRelationshipName();
168156
$method = 'get' . ucfirst($key);
169157

@@ -180,11 +168,11 @@ This is for reading the relationship between two resources.
180168
```php
181169
/**
182170
* @param \CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface $request
171+
* @param \App\User $record
183172
* @return \Illuminate\Http\Response
184173
*/
185-
public function readRelationship(RequestInterface $request)
174+
public function readRelationship(RequestInterface $request, User $record)
186175
{
187-
$record = $request->getRecord();
188176
$key = $request->getRelationshipName();
189177
$method = 'get' . ucfirst($key);
190178

‎docs/index.md

Lines changed: 19 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,12 @@ Based on the framework agnostic packages [neomerx/json-api](https://github.com/n
88

99
From [jsonapi.org](http://jsonapi.org)
1010

11-
> If you've ever argued with your team about the way your JSON responses should be formatted, JSON API is your anti-bikeshedding weapon.
11+
> If you've ever argued with your team about the way your JSON responses should be formatted, JSON API is your
12+
anti-bikeshedding weapon.
1213
>
13-
> By following shared conventions, you can increase productivity, take advantage of generalized tooling, and focus on what matters: your application. Clients built around JSON API are able to take advantage of its features around efficiently caching responses, sometimes eliminating network requests entirely.
14+
> By following shared conventions, you can increase productivity, take advantage of generalized tooling, and focus on
15+
what matters: your application. Clients built around JSON API are able to take advantage of its features around
16+
efficiently caching responses, sometimes eliminating network requests entirely.
1417

1518
For full information on the spec, plus examples, see [http://jsonapi.org](http://jsonapi.org).
1619

@@ -21,24 +24,32 @@ available to download, view the code and play around with as needed.
2124

2225
## Theory of Operation
2326

24-
Your application will have one (or many) APIs that conform to the JSON API spec. You define an API in your via routes, while JSON API settings are configured in a config file for each API. If you have multiple APIs, each has a unique *name*.
27+
Your application will have one (or many) APIs that conform to the JSON API spec. You define an API in your via routes,
28+
while JSON API settings are configured in a config file for each API. If you have multiple APIs, each has a unique
29+
*name*.
2530

2631
A JSON API contains a number of *resource types* that are available within your API. Each resource type
27-
relates directly to a PHP object class. We refer to instances of JSON API resource types as *resources*, and instances of your PHP classes as *records*.
32+
relates directly to a PHP object class. We refer to instances of JSON API resource types as *resources*, and instances
33+
of your PHP classes as *records*.
2834

2935
Each resource type has the following units that serve a particular purpose:
3036

31-
1. **Adapter**: Defines how to load a record using a JSON API resource identifier, and how to query for many records when the client fetches many resources.
37+
1. **Adapter**: Defines how to load a record using a JSON API resource identifier, and how to query for many records
38+
when the client fetches many resources.
3239
2. **Hydrator**: Deserializes data from a JSON API resource into the record to which it relates.
3340
3. **Schema**: Serializes a record into its JSON API representation.
3441
4. **Validators**: Provides validator instances to validate JSON API query parameters and HTTP content body.
3542

36-
Optionally you can also add an **Authorizer** instance to authorize incoming JSON API request, either for multiple resource types or for a specific resource type.
43+
Optionally you can also add an **Authorizer** instance to authorize incoming JSON API request, either for multiple
44+
resource types or for a specific resource type.
3745

38-
This may sound like a lot of units, but we believe the single purpose approach makes these highly testable and easy to reason about!
46+
This may sound like a lot of units, but we believe the single purpose approach makes these highly testable and easy to
47+
reason about!
3948

4049
### Why *Records* not *Models*?
4150

42-
In Laravel the phrase *model* is potentially confusing with Eloquent models. While some applications might solely encode Eloquent models to JSON API resources, others will use a mixture of Eloquent models and other PHP classes, or might not even be using Eloquent models.
51+
In Laravel the phrase *model* is potentially confusing with Eloquent models. While some applications might solely
52+
encode Eloquent models to JSON API resources, others will use a mixture of Eloquent models and other PHP classes,
53+
or might not even be using Eloquent models.
4354

4455
So we decided to refer to PHP object instances that are converted to JSON API resources as *records*.

‎docs/installation.md

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,18 +21,12 @@ If you would like to use the `JsonApi` facade, add the following to the list of
2121
``` php
2222
'aliases' => [
2323
// ... existing aliases
24-
'JsonApi' => 'CloudCreativity\LaravelJsonApi\Facade'
24+
'JsonApi' => CloudCreativity\LaravelJsonApi\Facades\JsonApi::class,
2525
]
2626
```
2727

2828
> The `JsonApi` facade maps to the `CloudCreativity\LaravelJsonApi\Services\JsonApiService` class.
2929
30-
Then publish the package config file:
31-
32-
``` bash
33-
$ php artisan vendor:publish --provider="CloudCreativity\LaravelJsonApi\ServiceProvider"
34-
```
35-
3630
## Exception Handling
3731

3832
Parts of the package throw exceptions to abort execution and render JSON API errors. Your will therefore need to

‎docs/upgrade.md

Lines changed: 3 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -94,21 +94,9 @@ The `ReplyTrait` has been renamed to:
9494

9595
This new trait has the same method `reply()` so you will not need to make any changes to your controllers.
9696

97-
The new trait also adds a handy `api()` method. This will return the API instance that is handling the inbound request.
98-
This means if you were accessing the API's store in your controller, you can now access the store via this method.
99-
For example, in your `index()` action:
100-
101-
```php
102-
public function index(RequestInterface $request)
103-
{
104-
$records = $this->api()->getStore()->query(
105-
$request->getResourceType(),
106-
$request->getParameters()
107-
);
108-
109-
return $this->reply()->content($records);
110-
}
111-
```
97+
We have massively improved the injection of dependencies into controller actions. There should be no breaking changes
98+
to your current controller action methods, but you may want to consult the chapter on non-Eloquent controllers to
99+
see how we now recommend implementing controller methods.
112100

113101
### Testing
114102

0 commit comments

Comments
 (0)
0