[Docs] Update upgrade guide

Author: lindyhopchris

CHANGELOG.md

@@ -3,6 +3,14 @@
 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/).
 
+## [5.0] - UNRELEASED
+
+### Changed
+
+- **BREAKING** Upgraded the `neomerx/json-api` dependency from `v1` to `v5` of our fork
+  `laravel-json-api/neomerx-json-api`. Refer to the [Upgrade Guide](./docs/upgrade.md) for details of the required
+  changes.  
+
 ## [4.0.1] - 2022-04-24
 
 ### Fixed

docs/upgrade.md

@@ -1,266 +1,111 @@
 # Upgrade Guide
 
-## 3.x to 4.0
+## 4.x to 5.0
 
-To upgrade, run the following Composer commands:
+### Background
 
-```bash
-composer remove cloudcreativity/json-api-testing --dev
-composer require cloudcreativity/laravel-json-api:^4.0 --no-update
-composer require laravel-json-api/testing:^1.1 --dev --no-update
-composer up cloudcreativity/* laravel-json-api/*
-```
-
-### PHP 8.1
-
-To remove deprecation messages from PHP 8.1, we've added return types or `#[\ReturnTypeWillChange]` annotations to
-methods for internal interfaces. This is unlikely to break your application, unless you have extended one of our classes
-and overridden an internal method.
-
-### Testing
+This major release upgrades the underlying `neomerx/json-api` dependency from `v1` to `v5` of our fork,
+`laravel-json-api/neomerx-json-api`.
 
-We are switching to using the `laravel-json-api/testing` package. This will help in the future with upgrading to the
-new `laravel-json-api/laravel` package, because it will mean when you upgrade your tests should continue to work
-without modifications. I.e. having a great test suite for your JSON:API functionality will help you safely upgrade in
-the future.
+Upgrading this dependency means that both this package (`cloudcreativity/laravel-json-api`) and the newer package
+(`laravel-json-api/laravel`) now use the same version of the Neomerx encoder. This means applications can now install
+both this package and the newer package, unlocking an upgrade path between the two. While you cannot have an API that
+mixes the two packages, an application could now have an older API running off the old package, and a newer API
+implemented with the new package. Overtime you can deprecate the older API and eventually remove it - removing
+`cloudcreativity/laravel-json-api` in the process.
 
-The `laravel-json-api/testing` dependency uses the `cloudcreativity/json-api-testing` package, which is what you have 
-been using up until now. It's just a more recent version, so there are a few changes to implement when upgrading.
+In case you're not aware, the Neomerx dependency is the package that does the encoding of classes to the JSON:API
+formatting. The problem we have always had with `cloudcreativity/laravel-json-api` is the package is too tightly
+coupled to the Neomerx implementation. This means this upgrade is a major internal change. While we have tested the
+upgrade to the best of our ability, if you find problems with it then please report them as issues on Github.
 
-The new testing package is fully 
-[documented on the Laravel JSON:API site](https://laraveljsonapi.io/docs/1.0/testing/) so we recommend you take a look
-at that if you get stuck when upgrading.
+While the new package (`laravel-json-api/laravel`) does use the Neomerx encoder, the use of that encoder is hidden
+behind generic interfaces. This fixed the problems with coupling and was one of the main motivations in building the
+new package.
 
-#### Test Case
+### Upgrading
 
-In the test case where you're importing `MakesJsonApiRequests`, change the `use` statement from this:
+To upgrade, run the following Composer command:
 
-```php
-use CloudCreativity\LaravelJsonApi\Testing\MakesJsonApiRequests;
-```
-
-to this:
-
-```php
-use LaravelJsonApi\Testing\MakesJsonApiRequests;
+```bash
+composer require cloudcreativity/laravel-json-api:5.0.0-alpha.1
 ```
 
-#### Test Response
-
-If anywhere in your application you have type-hinted our specific `TestResponse` you will need to change the `use`
-statement. (Note that most applications won't have type-hinted the `TestResponse` anywhere.)
-
-Previously:
+We've documented the changes that most applications will need to make below. However, if your application has made any
+changes to the implementation, e.g. by overriding elements of our implementation or using any of the Neomerx classes
+directly, there may be additional changes to make. If you're unsure how to upgrade anything, create a Github issue. 
+
+### Import and Type-Hint Renaming
+
+Most of the upgrade can be completed by doing a search and replace for import statements and type-hints.
+
+Your application will definitely be using the following import statements that must be replaced:
+
+- `Neomerx\JsonApi\Contracts\Encoder\Parameters\EncodingParametersInterface` replace with
+  `CloudCreativity\LaravelJsonApi\Contracts\Http\Query\QueryParametersInterface`
+- `Neomerx\JsonApi\Encoder\Parameters\EncodingParameters` replace with
+  `CloudCreativity\LaravelJsonApi\Http\Query\QueryParameters`
+- `Neomerx\JsonApi\Schema\SchemaProvider` replace with
+  `CloudCreativity\LaravelJsonApi\Schema\SchemaProvider`
+
+And it will also definitely be using these type-hints, that must be replaced:
+
+- `EncodingParametersInterface` with `QueryParametersInterface`
+- `EncodingParameters` with `QueryParameters`
+
+The following import statements also need changing, however you should not worry if you cannot find any usages of them
+within your application:
+
+- `Neomerx\JsonApi\Contracts\Encoder\Parameters\SortParameterInterface` replace with
+  `CloudCreativity\LaravelJsonApi\Contracts\Http\Query\SortParameterInterface`
+- `Neomerx\JsonApi\Encoder\Parameters\SortParameter` replace with
+  `CloudCreativity\LaravelJsonApi\Http\Query\SortParameter`
+- `Neomerx\JsonApi\Contracts\Document\ErrorInterface` replace with
+  `Neomerx\JsonApi\Contracts\Schema\ErrorInterface`
+- `Neomerx\JsonApi\Document\Error` replace with
+  `Neomerx\JsonApi\Schema\Error`
+- `Neomerx\JsonApi\Exceptions\ErrorCollection` replace with
+  `Neomerx\JsonApi\Schema\ErrorCollection`
+- `Neomerx\JsonApi\Contracts\Document\LinkInterface` replace with
+  `Neomerx\JsonApi\Contracts\Schema\LinkInterface`
+- `Neomerx\JsonApi\Contracts\Document\DocumentInterface` replace with
+  `Neomerx\JsonApi\Contracts\Schema\DocumentInterface`
+- `Neomerx\JsonApi\Contracts\Http\Headers\HeaderInterface` replace with
+  `CloudCreativity\LaravelJsonApi\Contracts\Http\Headers\HeaderInterface`
+- `Neomerx\JsonApi\Contracts\Http\Headers\AcceptHeaderInterface` replace with
+  `CloudCreativity\LaravelJsonApi\Contracts\Http\Headers\AcceptHeaderInterface`
+- `Neomerx\JsonApi\Contracts\Http\Headers\HeaderParametersParserInterface` replace with
+  `CloudCreativity\LaravelJsonApi\Contracts\Http\Headers\HeaderParametersParserInterface`
+- `Neomerx\JsonApi\Contracts\Http\Query\QueryParametersParserInterface` replace with
+  `CloudCreativity\LaravelJsonApi\Contracts\Http\Query\QueryParametersParserInterface`
+
+### Schemas
+
+We have added argument and return type-hints to all methods on the schema class. You will need to add these to all your
+schemas. For example the `getId()`, `getAttributes()` and `getRelationships()` methods now look like this:
 
 ```php
-use CloudCreativity\LaravelJsonApi\Testing\TestResponse;
-```
+public function getId(object $resource): string {}
 
-It now needs to be:
+public function getAttributes(object $resource): array {}
 
-```php
-use LaravelJsonApi\Testing\TestResponse;
+public function getRelationships(object $resource, bool $isPrimary, array $includeRelationships): array {}
 ```
 
-#### Test Actions
+In addition, properties also now have type-hints. For example, you need to add a `string` type-hint to the
+`$resourceType` property.
 
-The following test actions have been deprecated for some time and have now been removed. This is because these helper
-methods used the JSON:API implementation internally, which was potentially risky as the JSON:API implementation itself
-is the subject of the tests. These are the methods:
-
-- `doSearch()`
-- `doSearchById()`
-- `doCreate()`
-- `doRead()`
-- `doUpdate()`
-- `doDelete()`
-- `doReadRelated()`
-- `doReadRelationship()`
-- `doReplaceRelationship()`
-- `doAddToRelationship()`
-- `doRemoveFromRelationship()`
-
-Here are example replacements:
+Optionally, you can remove the `getId()` method from model schemas if the content of the method looks like this:
 
 ```php
-// doSearch()
-$response = $this->jsonApi('posts')->get('/api/v1/posts');
-
-// doSearchById()
-$response = $this
-    ->jsonApi('posts')
-    ->filter(['id' => $posts])
-    ->get('/api/v1/posts');
-
-// doCreate()
-$response = $this
-    ->jsonApi('posts')
-    ->withData($data)
-    ->post('/api/v1/posts');
-
-// doRead()
-$response = $this
-    ->jsonApi('posts')
-    ->get(url('/api/v1/posts', $post));
-
-// doUpdate()
-$response = $this
-    ->jsonApi('posts')
-    ->withData($data)
-    ->patch(url('/api/v1/posts', $post));
-
-// doDelete()
-$response = $this
-    ->jsonApi('posts')
-    ->delete(url('/api/v1/posts', $post));
-
-// doReadRelated()
-$response = $this
-    ->jsonApi('comments')
-    ->get(url('/api/v1/posts', [$post, 'comments']));
-
-// doReadRelationship()
-$response = $this
-    ->jsonApi('comments')
-    ->get(url('/api/v1/posts', [$post, 'relationships', 'comments']));
-
-// doReplaceRelationship()
-$response = $this
-    ->jsonApi('comments')
-    ->withData($data)
-    ->patch(url('/api/v1/posts', [$post, 'relationships', 'comments']));
-
-// doAddToRelationship()
-$response = $this
-    ->jsonApi('comments')
-    ->withData($data)
-    ->post(url('/api/v1/posts', [$post, 'relationships', 'comments']));
-
-// doRemoveFromRelationship()
-$response = $this
-    ->jsonApi('comments')
-    ->withData($data)
-    ->delete(url('/api/v1/posts', [$post, 'relationships', 'comments']));
-```
-
-> Note in all the above we use `withData()` to set the data for the request. Previously there was a `data` method, which
-> has been removed.
-
-Also, the following HTTP verb JSON:API methods have been removed:
-
-- `getJsonApi` - use `$this->jsonApi('posts')->get($url)`
-- `postJsonApi` - use `$this->jsonApi('posts')->withData($data)->post($url)`
-- `patchJsonApi` - use `$this->jsonApi('posts')->withData($data)->patch($url)`
-- `deleteJsonApi` - use `$this->jsonApi('posts')->withData($data)->delete($url)`
-
-> For info, everything has been moved to the test builder that's returned by the `jsonApi()` method, so that we can 
-> avoid collisions with any methods that Laravel might.
-
-## 2.x to 3.0
-
-### Validators
-
-The method signature of the `rules()` method has changed so that the method has access to the data
-that is going to be validated. You will need to amend the method signature on all of your validator
-classes.
-
-The method signature was previously:
-
-```
-protected function rules($record = null): array
+public function getId(object $resource): string
 {
-    // ...
+    return (string) $resource->getRouteKey();
 }
 ```
 
-It is now:
-
-```
-protected function rules($record, array $data): array
-{
-    // ...
-}
-```
-
-> Note that `$record` will still be `null` if the request will create a new resource.
-
-### Soft Deletes
-
-Previously if no soft deletes field was set on an adapter, the JSON API field would default to the dash-case
-version of the soft deletes column on the model. For example, if the model used the column `deleted_at`,
-the JSON API field would default to `deleted-at`.
-
-In `v3`, the default is now the camel-case version of the column: i.e. `deleted_at` on the model would default
-to `deletedAt` for the JSON API field. This change has been made because the JSON API spec has changed its
-recommendation from using dash-case to camel-case.
-
-If you have existing resources that use dash-case, simply set the `softDeleteField` property on your adapter,
-for example:
-
-```php
-use CloudCreativity\LaravelJsonApi\Eloquent\AbstractAdapter;
-use CloudCreativity\LaravelJsonApi\Eloquent\Concerns\SoftDeletesModels;
-
-class Adapter extends AbstractAdapter
-{
-
-    use SoftDeletesModels;
-
-    protected $softDeleteField = 'deleted-at';
-
-}
-```
-
-## 1.x to 2.0
-
-Version 2 drops support for all 5.x and 6.x versions of Laravel, and sets the minimum PHP version to 7.2.
-This is because Laravel 7 introduced a few changes (primarily to the exception handler and the namespace
-of the test response class) that meant it was not possible to support Laravel 6 and 7.
-
-This release is primarily a tidy-up release: we have removed all functionality that has been marked
-as deprecated since the 1.0 pre-releases. Upgrading should be simple if you are not using any of the
-deprecated pre-release features.
-
-The following are some notes on additional upgrade steps.
-
 ### Errors
 
-If you were type-hinting our error class, it has been moved from `Document\Error` to `Document\Error\Error`.
-In addition, the `Validation\ErrorTranslator` class has been moved to `Document\Error\Translator`.
-
-This will only affect applications that have customised error responses.
-
-### Testing
-
-The method signature of the test `jsonApi()` helper method on the `MakesJsonApiRequests` trait has been changed.
-This now accepts no function arguments and returns a test builder instance that allows you to fluidly construct test
-requests.
-
-For example this on your test case:
-
-```php
-$response = $this->jsonApi('GET', '/api/v1/posts', ['include' => 'author']);
-```
-
-Is now:
-
-```php
-$response = $this
-    ->jsonApi()
-    ->includePaths('author')
-    ->get('/api/v1/posts');
-```
-
-> Have a look at the `Testing/TestBuilder` class for the full list of methods you can use when building
-> a test request.
-
-All other test methods have been left on the `MakesJsonApiRequests` have been left, but we have marked a number
-as deprecated. These deprecated methods will be removed in 3.0 in preference of using method chaining from the
-`jsonApi()` method.
-
-#### Test Query Parameters
-
-As per [this issue](https://github.com/cloudcreativity/laravel-json-api/issues/427), we now fail a test if
-any query parameters values are not strings, integers or floats. This is because query parameters are received
-over HTTP as strings, so for example testing a `true` boolean is invalid and can lead to tests incorrectly
-passing.
+Check whether you are using the Neomerx error object directly anywhere, by searching for the new import statement:
+`Neomerx\JsonApi\Schema\Error`. If you are, you should be aware that the constructor arguments have changed. Check
+your use against the new constructor arguments by inspecting the class directly.