8000 [Docs] Update upgrade guide · CodingSeo/laravel-json-api@6ecf775 · GitHub
[go: up one dir, main page]
Skip to content

Commit 6ecf775

Browse files
lindyhopchrislindyhopchris
committed
[Docs] Update upgrade guide
1 parent d59c49a commit 6ecf775

File tree

2 files changed

+34
-201
lines changed

2 files changed

+34
-201
lines changed

‎CHANGELOG.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ floats. This is to ensure that the developer is correctly testing boolean filter
1717
- Minimum Laravel version is now `7.0`.
1818
- Amended the store interface so that it always takes a string resource type and string id,
1919
instead of the deprecated resource identifier object.
20-
- Moved the `Validation\ErrorTranslator` class to `Error\Translator`.
20+
- Moved the `Validation\ErrorTranslator` class to `Document\Error\Translator`.
2121
- The `Testing\MakesJsonApiRequests::jsonApi()` method no longer accepts any function arguments,
2222
and returns an instance of `Testing\TestBuilder`. This allows the developer to fluently execute
2323
test JSON API requests.

‎docs/upgrade.md

Lines changed: 33 additions & 200 deletions
Original file line numberDiff line numberDiff line change
@@ -1,222 +1,55 @@
11
# Upgrade Guide
22

3-
## 1.0.0-rc.* to ^1.0
3+
## 1.x to 2.0
44

5-
No changes are required to upgrade.
5+
Version 2 drops support for all 5.x and 6.x versions of Laravel, and sets the minimum PHP version to 7.2.
6+
This is because Laravel 7 introduced a few changes (primarily to the exception handler and the namespace
7+
of the test response class) that meant it was not possible to support Laravel 6 and 7.
68

7-
## 1.0.0-beta.6 to 1.0.0-rc.1
9+
This release is primarily a tidy-up release: we have removed all functionality that has been marked
10+
as deprecated since the 1.0 pre-releases. Upgrading should be simple if you are not using any of the
11+
deprecated pre-release features.
812

9-
### Config
13+
The following are some notes on additional upgrade steps.
1014

11-
We have re-implemented content-negotiation so that you can support non-JSON API media types at
12-
runtime. As part of this change we've made a slight change to the API config to make it clearer
13-
what the config sets.
15+
### Errors
1416

15-
Currently your API's content negotiation config looks like this:
17+
If you were type-hinting our error class, it has been moved from `Document\Error` to `Document\Error\Error`.
18+
In addition, the `Validation\ErrorTranslator` class has been moved to `Document\Error\Translator`.
1619

17-
```php
18-
return [
19-
// ...
20-
21-
/*
22-
|--------------------------------------------------------------------------
23-
| Content Negotiation
24-
|--------------------------------------------------------------------------
25-
|
26-
| This is where you register how different media types are mapped to
27-
| encoders and decoders. Encoders do the work of converting your records
28-
| into JSON API resources. Decoders are used to convert incoming request
29-
| body content into objects.
30-
|
31-
| If there is not an encoder/decoder registered for a specific media-type,
32-
| then an error will be sent to the client as per the JSON-API spec.
33-
|
34-
*/
35-
'codecs' => [
36-
'encoders' => [
37-
'application/vnd.api+json',
38-
],
39-
'decoders' => [
40-
'application/vnd.api+json',
41-
],
42-
],
43-
];
44-
```
45-
46-
You will need to change it to this:
20+
This will only affect applications that have customised error responses.
4721

48-
```php
49-
return [
50-
// ...
51-
52-
53-
/*
54-
|--------------------------------------------------------------------------
55-
| Encoding Media Types
56-
|--------------------------------------------------------------------------
57-
|
58-
| This defines the JSON API encoding used for particular media
59-
| types supported by your API. This array can contain either
60-
| media types as values, or can be keyed by a media type with the value
61-
| being the options that are passed to the `json_encode` method.
62-
|
63-
| These values are also used for Content Negotiation. If a client requests
64-
| via the HTTP Accept header a media type that is not listed here,
65-
| a 406 Not Acceptable response will be sent.
66-
|
67-
| If you want to support media types that do not return responses with JSON
68-
| API encoded data, you can do this at runtime. Refer to the
69-
| Content Negotiation chapter in the docs for details.
70-
|
71-
*/
72-
'encoding' => [
73-
'application/vnd.api+json',
74-
],
75-
76-
/*
77-
|--------------------------------------------------------------------------
78-
| Decoding Media Types
79-
|--------------------------------------------------------------------------
80-
|
81-
| This defines the media types that your API can receive from clients.
82-
| This array is keyed by expected media types, with the value being the
83-
| service binding that decodes the media type.
84-
|
85-
| These values are also used for Content Negotiation. If a client sends
86-
| a content type not listed here, it will receive a
87-
| 415 Unsupported Media Type response.
88-
|
89-
| Decoders can also be calculated at runtime, and/or you can add support
90-
| for media types for specific resources or requests. Refer to the
91-
| Content Negotiation chapter in the docs for details.
92-
|
93-
*/
94-
'decoding' => [
95-
'application/vnd.api+json',
96-
],
97-
];
98-
```
22+
### Testing
9923

100-
### Routing
24+
The method signature of the test `jsonApi()` helper method on the `MakesJsonApiRequests` trait has been changed.
25+
This now accepts no function arguments and returns a test builder instance that allows you to fluidly construct test
26+
requests.
10127

102-
We have made changes to the routing to introduce a fluent syntax for defining routes. This will
103-
not affect your application unless you type-hinted the `Routing\ApiGroup` class in any of your
104-
route definitions. You will now need to type-hint `Routing\RouteRegistrar` instead.
105-
106-
Change this:
28+
For example this on your test case:
10729

10830
```php
109-
use CloudCreativity\LaravelJsonApi\Routing\ApiGroup;
110-
111-
JsonApi::register('v1', [], function (ApiGroup $api) {
112-
// ...
113-
});
31+
$response = $this->jsonApi('GET', '/api/v1/posts', ['include' => 'author']);
11432
```
11533

116-
to this:
117-
118-
```php
119-
use CloudCreativity\LaravelJsonApi\Routing\RouteRegistrar;
120-
121-
JsonApi::register('v1', [], function (RouteRegistrar $api) {
122-
// ...
123-
});
124-
```
125-
126-
### Controllers
127-
128-
#### Eloquent
129-
130-
The `Http\Controllers\EloquentController` class has been removed. This has been deprecated for
131-
some time, and had no code in it. You can extend `Http\Controllers\JsonApiController` directly.
132-
133-
#### Searching Hook
134-
135-
As before the `searching` hook now occurs *before* records are queried with the resource's adapter.
136-
We have added a `searched` hook that is invoked *after* records are returned by the adapter. This
137-
hook receives the search results as its first argument.
138-
139-
You probably do not need to make any changes, unless the new `searched` hook is more useful to you
140-
than the `searching` hook.
141-
142-
#### Reading Hook
143-
144-
The `reading` hook is now executed *before* the resource's adapter is called. Previously it was
145-
invoked *after* the adapter. The first argument of this hook remains the record that is being read.
146-
147-
We have added a `didRead` hook that is executed *after* the resource's adapter is called. Its first
148-
argument is the result returned by the adapter. This will usually be the record being read, but may
149-
be `null` if the client provided any filter parameters and the record does not match those filters.
150-
151-
If you have implemented the `reading` hook on any of your controllers, and you intend it to always
152-
receive the record that the request relates to, you do **not** need to make any changes. If you intend
153-
the hook to receive the record that will be in the response, you should change the hook to `didRead`
154-
and ensure the code handles the record being `null`.
155-
156-
#### Type-Hinting
157-
158-
We have changed the type-hinting of some protected methods so that they now type-hint the concrete
159-
instance of `ValidatedRequest`. This will only affect your application if you have overloaded any
160-
of the protected methods.
161-
162-
### Adapters
163-
164-
If any of your adapters were extending `Store\EloquentAdapter`, you now need to extend
165-
`Eloquent\AbstractAdapter` instead.
166-
167-
We have removed deprecated properties and methods from the Eloquent adapter. A lot of these have
168-
been deprecated for some time, so are unlikely to affect your application unless you have Eloquent
169-
adapters that have not been changed for some time. If in doubt, check the changelog that lists
170-
the removals.
171-
172-
### Validators
173-
174-
> The changes listed here are unlikely to affect most applications.
175-
176-
If you have implemented the `Contracts\Validation\ValidatorFactoryInterface` interface rather than
177-
extending our `Validation\AbstractValidators` class, you will need to add the `delete()` method
178-
to your implementation.
179-
180-
In our `Validation\AbstractValidators` class we have renamed the following two protected methods:
181-
- `createData` is now `dataForCreate`.
182-
- `updateData` is now `dataForUpdate`.
183-
- `relationshipData` is now `dataForRelationship`.
184-
- `createResourceValidator` is now `validatorForResource`.
185-
- `createQueryValidator` is now `validatorForQuery`.
186-
187-
We have also simplified our validator classes into a single class. The following classes have
188-
been removed:
189-
- `Validation\AbstractValidator`: use `Factories\Factory::createValidator()` or extend `Validation\Validator`.
190-
- `Validation\ResourceValidator`: use `Factories\Factory::createResourceValidator()`.
191-
- `Validation\QueryValidator`: use `Factories\Factory::createQueryValidator()`.
192-
193-
### Packages (Resource Providers)
194-
195-
The method signature for the `mount` method on the `AbstractProvider` class has changed to this:
34+
Is now:
19635

19736
```php
198-
/**
199-
* Mount routes onto the provided API.
200-
*
201-
* @param \CloudCreativity\LaravelJsonApi\Routing\RouteRegistrar $api
202-
* @return void
203-
*/
204-
public function mount(RouteRegistrar $api): void
205-
{
206-
//
207-
}
37+
$response = $this
38+
->jsonApi()
39+
->includePaths('author')
40+
->get('/api/v1/posts');
20841
```
20942

210-
> If you were previously using the second argument, check out the new documentation for adding
211-
custom routes to the API in the [Routing chapter.](./basics/routing.md)
212-
213-
We have also added PHP 7 type-hinting to all other methods on the provider. (There were not many of them,
214-
so as we were changing the signature of one method, it made sense to change all.)
215-
216-
## 1.0.0-alpha.4 to 1.0.0-beta.6
43+
> Have a look at the `Testing/TestBuilder` class for the full list of methods you can use when building
44+
> a test request.
21745
218-
View [beta upgrade notes here.](https://github.com/cloudcreativity/laravel-json-api/blob/v1.0.0-beta.6/docs/upgrade.md)
46+
All other test methods have been left on the `MakesJsonApiRequests` have been left, but we have marked a number
47+
as deprecated. These deprecated methods will be removed in 3.0 in preference of using method chaining from the
48+
`jsonApi()` method.
21949

220-
## 1.0.0-alpha.* to 1.0.0-alpha.4
50+
#### Test Query Parameters
22151

222-
View [alpha upgrade notes here.](https://github.com/cloudcreativity/laravel-json-api/blob/v1.0.0-alpha.4/docs/upgrade.md)
52+
As per [this issue](https://github.com/cloudcreativity/laravel-json-api/issues/427), we now fail a test if
53+
any query parameters values are not strings, integers or floats. This is because query parameters are received
54+
over HTTP as strings, so for example testing a `true` boolean is invalid and can lead to tests incorrectly
55+
passing.

0 commit comments

Comments
 (0)
0