8000 Merge branch 'feature/v0.5' into develop · m-bymike/laravel-json-api@c53a405 · GitHub
[go: up one dir, main page]
Skip to content

Commit c53a405

Browse files
lindyhopchrislindyhopchris
committed
Merge branch 'feature/v0.5' into develop
2 parents c6898ec + edb7118 commit c53a405

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+1957
-2527
lines changed

‎UPGRADE.md

Lines changed: 352 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,358 @@
22

33
This file provides notes on how to upgrade between versions.
44

5+
## v0.4 to v0.5
6+
7+
The dependent framework-agnostic package has a number of changes. Below lists the changes you will need to make
8+
to your application. However, if you are also extending underlying package functionality you will also need to refer
9+
to the `v0.5` to `v0.6` upgrade notes here:
10+
[cloudcreativty/json-api Upgrade Notes](https://github.com/cloudcreativity/json-api/blob/feature/v0.6/UPGRADE.md)
11+
12+
### Config
13+
14+
Paging config is now defined on a per-API basis, so you need to move your paging config into your API namespace
15+
config in the `json-api.php` config file. We have updated the comment blocks to reflect this; you can find those
16+
in the `config/json-api.php` file within this package.
17+
18+
Before:
19+
20+
``` php
21+
return [
22+
'namespaces' => [
23+
'v1' => [
24+
'url-prefix' => '/api/v1',
25+
'supported-ext' => null,
26+
],
27+
],
28+
29+
// ...
30+
31+
'paging' => [
32+
'params' => [
33+
'page' => null,
34+
'per-page' => null,
35+
],
36+
'meta' => [
37+
'key' => null,
38+
'current-page' => 'page',
39+
'per-page' => 'size',
40+
'first-item' => null,
41+
'last-item' => null,
42+
'total' => null,
43+
'last-page' => 'last',
44+
],
45+
]
46+
];
47+
```
48+
49+
After:
50+
51+
``` php
52+
return [
53+
'namespaces' => [
54+
'v2' => [
55+
'url-prefix' => '/api/v2',
56+
'supported-ext' => null,
57+
'paging' => [
58+
'page' => null,
59+
'per-page' => null,
60+
],
61+
'paging-meta' => [
62+
'current-page' => 'page',
63+
'per-page' => 'size',
64+
'first-item' => null,
65+
'last-item' => null,
66+
'total' => null,
67+
'last-page' => 'last',
68+
],
69+
],
70+
],
71+
];
72+
```
73+
74+
### Authorizers
75+
76+
#### Abstract Authorizer
77+
78+
If you are extending the `AbstractAuthorizer` class and implementing your own constructor, you will need to
79+
inject an instance of `CloudCreativity\JsonApi\Contracts\Repositories\ErrorRepositoryInterface` into the parent
80+
constructor. This change means you can now add errors to the error collection on your authorizer using the string
81+
keys for error objects held within your `json-api-errors` config file. For example:
82+
83+
``` php
84+
public function canRead($record, EncodingParametersInterface $parameters)
85+
{
86+
if (!\Auth::check()) {
87+
$this->addError('access-denied');
88+
return false;
89+
}
90+
91+
return true;
92+
}
93+
```
94+
95+
Note that the recommended way to create error objects is via the error repository (which holds your error config)
96+
because it provides opportunities to add in translation etc of errors in the future.
97+
98+
You will also need to implement the `canModifyRelationship` method. This was previously implemented in the abstract
99+
class but the previous implementation no longer works because of the change below.
100+
101+
#### Update Authorization
102+
103+
Update authorization can now access the resource sent by the client. At the point the authorizer is invoked, the
104+
resource will have been validated to check that it complies with the JSON API spec but it will **not** have been
105+
checked that it is valid according to your business logic - i.e. attributes and relationships will not have
106+
been validated against the specific rules for that resource type.
107+
108+
Change the `canUpdate` method from this:
109+
110+
``` php
111+
canUpdate($record, EncodingParametersInterface $parameters)
112+
```
113+
114+
to:
115+
116+
``` php
117+
// CloudCreativity\JsonApi\Contracts\Object\ResourceInterface;
118+
canUpdate(
119+
$record,
120+
ResourceInterface $recource,
121+
EncodingParametersInterface $parameters
122+
)
123+
```
124+
125+
#### Modify Relationship Authorization
126+
127+
Relationship modification authroization can now access the relationship sent by the client, as per the update
128+
authorization changes above.
129+
130+
Change the `canModifyRelationship` method from this:
131+
132+
``` php
133+
public function canModifyRelationship(
134+
$relationshipKey,
135+
$record,
136+
EncodingParametersInterface $parameters
137+
)
138+
```
139+
140+
to:
141+
142+
``` php
143+
// CloudCreativity\JsonApi\Contracts\Object\RelationshipInterface
144+
public function canModifyRelationship(
145+
$relationshipKey,
146+
$record,
147+
RelationshipInterface $relationship,
148+
EncodingParametersInterface $parameters
149+
)
150+
```
151+
152+
### Controllers
153+
154+
#### Request Handler
155+
156+
The request class is no longer injected into the parent constructor. This change was necessary to support Laravel 5.3.
157+
Instead you now need to implement the `getRequestHandler` method and return a string of the fully qualified class
158+
name of the handler that is to be used. If you were not calling the parent constructor, you must now call it.
159+
160+
For example in an Eloquent controller, this:
161+
162+
``` php
163+
public function __construct(
164+
Posts\Request $request,
165+
Posts\Hydrator $hydrator,
166+
Posts\Search $search
167+
) {
168+
parent::__construct(new Post(), $request, $hydrator, $search);
169+
}
170+
```
171+
172+
Must be changed to:
173+
174+
``` php
175+
public function __construct(Posts\Hydrator $hydrator, Posts\Search $search)
176+
{
177+
parent::__construct(new Post(), $hydrator, $search);
178+
}
179+
180+
protected function getRequestHandler()
181+
{
182+
return Posts\Request::class;
183+
}
184+
```
185+
186+
#### Action Methods
187+
188+
The method signature of all the action methods have changed - they now all receive the validated JSON API request
189+
object as they first argument.
190+
191+
For example, this:
192+
193+
``` php
194+
public function read($resourceId) {}
195+
```
196+
197+
Has become this:
198+
199+
``` php
200+
use CloudCreativity\JsonApi\Contracts\Http\Requests\RequestInterface as JsonApiRequest;
201+
// ...
202+
public function read(JsonApiRequest $request) {}
203+
```
204+
205+
Use the request object to get the resource id, relationship name and document (the JSON API request content). Refer
206+
to the interface for methods available.
207+
208+
#### Search All
209+
210+
You now need to always inject a search object into the Eloquent controller, otherwise the controller will return a
211+
`501 Not Implemented` response for the index action.
212+
213+
To use the previous search behaviour for an Eloquent model, type hint the following class in your controller
214+
constructor and pass it into the parent constructor:
215+
216+
``` php
217+
use CloudCreativity\LaravelJsonApi\Search\SearchAll;
218+
219+
public function __construct(SearchAll $search)
220+
{
221+
parent::__construct(new Post(), null, $search);
222+
}
223+
```
224+
225+
### Hydrators
226+
227+
The namespace of the `AbstractHydrator` has changed from `CloudCreativity\LaravelJsonApi\Hydrator\AbstractHydrator`
228+
to `CloudCreativity\JsonApi\Hydrator\AbstractHydrator`.
229+
230+
### Requests
231+
232+
Class `CloudCreativity\LaravelJsonApi\Http\Requests\AbstractRequest` has been removed. Instead you should extend
233+
`CloudCreativity\JsonApi\Requests\RequestHandler`.
234+
235+
Note that the constructor for this new class has the authorizer as the first argument and the validators as the
236+
second (i.e. it is the other way round from what it was before). We've made this change because authorization
237+
occurs before validation, so it makes more sense for the arguments to be this way round.
238+
239+
### Responses (Reply Trait)
240+
241+
The method signature for the `errors` method has changed. To maintain the old behaviour use `error` instead (it
242+
accepts an error collection as well as a single error).
243+
244+
### Schemas
245+
246+
The JSON API specification recommends using hyphens for member names, e.g. `foo-bar`. The Eloquent schema now uses
247+
this recommendation as its default behaviour. E.g. a model key of `foo_bar` will be serialized as `foo-bar`.
248+
249+
To maintain the old behaviour (of using the model key for the member key), set the `$hyphenated` property on your
250+
schema to `false`. If you want to implement your own logic, overload the `keyForAttribute` method.
251+
252+
If you have irregular mappings of model keys to attribute keys, you can define these in your `$attributes` property,
253+
e.g.
254+
255+
``` php
256+
protected $attributes = [
257+
'foo',
258+
'bar',
259+
'foo_bar' // will be dasherized to 'foo-bar' by default
260+
'baz' => 'bat' // model key `baz` will be serialized to attribute key `bat`
261+
];
262+
```
263+
264+
### Search
265+
266+
We've merged the abstract sorted search class into the abstract search class, to simplify things.
267+
268+
You'll need to change:
269+
270+
``` php
271+
use CloudCreativity\LaravelJsonApi\Search\AbstractSortedSearch;
272+
273+
class Search extends AbstractSortedSearch
274+
{
275+
}
276+
```
277+
278+
to:
279+
280+
``` php
281+
use CloudCreativity\LaravelJsonApi\Search\AbstractSearch;
282+
283+
class Search extends AbstractSearch
284+
{
285+
}
286+
```
287+
288+
#### Constructor
289+
290+
If you are overloading the constructor, you will need to call the parent constructor and provide it with the
291+
following two dependencies:
292+
293+
```
294+
CloudCreativity\JsonApi\Contracts\Http\HttpServiceInterface
295+
CloudCreativity\JsonApi\Contracts\Pagination\PaginatorInterface
296+
```
297+
298+
#### Sort Parameter Field Conversion
299+
300+
When working out what column to use for a sort parameter, the sort parameter will automatically be snake cased if
301+
your model uses snake attributes. If it does not use snake attributes, the parameter will be camel cased.
302+
303+
If you have irregular mappings of search params to column names, add that mapping to your `$sortColumns` property,
304+
e.g. `$sortColumns = ['foo-bar' => 'baz_bat']`.
305+
306+
If you want to use a completely different logic for converting search params to column names, overload the
307+
`columnForField()` method.
308+
309+
### Validator Providers
310+
311+
The classes that provide validators for individual resource types generally extend `AbstractValidatorProvider`. This
312+
now receives the resource type that is being validated into its public methods, and this is now passed down through
313+
the internal methods. You'll therefore need to make the changes described below.
314+
315+
This change has been made so that a single validator provider can be used for multiple resource types if desired.
316+
Although you are likely to keep a validator provider per resource type (because attribute and relationship rules will
317+
be specific to a resource type), this has given us the capability to implement a generic validator provider capable of
318+
validating any resource type according to the JSON API spec.
319+
320+
#### Constructor
321+
322+
If you have implemented a constructor, you will need to type hint the following interface and pass it to the parent
323+
constructor:
324+
325+
```
326+
CloudCreativity\LaravelJsonApi\Contracts\Validators\ValidatorFactoryInterface
327+
```
328+
329+
#### Resource Type Property
330+
331+
You can remove the `$resourceType` property as it is no longer required.
332+
333+
#### Method Changes
334+
335+
You'll need to adjust the signature of the following abstract methods, from:
336+
337+
``` php
338+
attributeRules($record = null)
339+
relationshipRules(RelationshipsValidatorInterface $relationships, $record = null)
340+
filterRules()
341+
```
342+
343+
to:
344+
345+
``` php
346+
attributeRules($resourceType, $record = null)
347+
relationshipRules(RelationshipsValidatorInterface $relationships, $resourceType, $record = null)
348+
filterRules($resourceType)
349+
```
350+
351+
The `filterRules` method is actually no longer abstract, so if you are returning an empty array from it you can delete
352+
it.
353+
354+
The signatures of other `protected` methods have also changed to pass down this additional argument. If you have
355+
implemented any other methods, check the abstract class for the new argument order.
356+
5357
## v0.3 to v0.4
6358

7359
This was a substantial reworking of the package based on our experience of using it in production environments.

‎composer.json

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,9 @@
2323
],
2424
"require": {
2525
"php": ">=5.5.0",
26-
"laravel/framework": "5.1.*|5.2.*",
27-
"cloudcreativity/json-api": "^0.5.2",
26+
"laravel/framework": "5.1.*|5.2.*|5.3.*",
27+
"neomerx/json-api": "^0.8.9",
28+
"cloudcreativity/json-api": "0.6.x-dev",
2829
"symfony/psr-http-message-bridge": "^0.2.0",
2930
"zendframework/zend-diactoros": "^1.3"
3031
},
@@ -41,5 +42,10 @@
4142
"psr-4": {
4243
"CloudCreativity\\LaravelJsonApi\\": "test/"
4344
}
45+
},
46+
"extra": {
47+
"branch-alias": {
48+
"dev-feature/v0.5": "0.5.x-dev"
49+
}
4450
}
4551
}

0 commit comments

Comments
 (0)
0