Upgrade Guide
4.x to 5.0
Background
This major release upgrades the underlying neomerx/json-api dependency from v1 to v5 of our fork, laravel-json-api/neomerx-json-api.
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.
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.
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.
Upgrading
To upgrade, run the following Composer command:
composer require cloudcreativity/laravel-json-api:5.0.0-alpha.1 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\EncodingParametersInterfacereplace withCloudCreativity\LaravelJsonApi\Contracts\Http\Query\QueryParametersInterfaceNeomerx\JsonApi\Encoder\Parameters\EncodingParametersreplace withCloudCreativity\LaravelJsonApi\Http\Query\QueryParametersNeomerx\JsonApi\Schema\SchemaProviderreplace withCloudCreativity\LaravelJsonApi\Schema\SchemaProvider
And it will also definitely be using these type-hints, that must be replaced:
EncodingParametersInterfacewithQueryParametersInterfaceEncodingParameterswithQueryParameters
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\SortParameterInterfacereplace withCloudCreativity\LaravelJsonApi\Contracts\Http\Query\SortParameterInterfaceNeomerx\JsonApi\Encoder\Parameters\SortParameterreplace withCloudCreativity\LaravelJsonApi\Http\Query\SortParameterNeomerx\JsonApi\Contracts\Document\ErrorInterfacereplace withNeomerx\JsonApi\Contracts\Schema\ErrorInterfaceNeomerx\JsonApi\Document\Errorreplace withNeomerx\JsonApi\Schema\ErrorNeomerx\JsonApi\Exceptions\ErrorCollectionreplace withNeomerx\JsonApi\Schema\ErrorCollectionNeomerx\JsonApi\Contracts\Document\LinkInterfacereplace withNeomerx\JsonApi\Contracts\Schema\LinkInterfaceNeomerx\JsonApi\Contracts\Document\DocumentInterfacereplace withNeomerx\JsonApi\Contracts\Schema\DocumentInterfaceNeomerx\JsonApi\Contracts\Http\Headers\HeaderInterfacereplace withCloudCreativity\LaravelJsonApi\Contracts\Http\Headers\HeaderInterfaceNeomerx\JsonApi\Contracts\Http\Headers\AcceptHeaderInterfacereplace withCloudCreativity\LaravelJsonApi\Contracts\Http\Headers\AcceptHeaderInterfaceNeomerx\JsonApi\Contracts\Http\Headers\HeaderParametersParserInterfacereplace withCloudCreativity\LaravelJsonApi\Contracts\Http\Headers\HeaderParametersParserInterfaceNeomerx\JsonApi\Contracts\Http\Query\QueryParametersParserInterfacereplace withCloudCreativity\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:
public function getId(object $resource): string {} public function getAttributes(object $resource): array {} public function getRelationships(object $resource, bool $isPrimary, array $includeRelationships): array {} In addition, properties also now have type-hints. For example, you need to add a string type-hint to the $resourceType property.
Optionally, you can remove the getId() method from model schemas if the content of the method looks like this:
public function getId(object $resource): string { return (string) $resource->getRouteKey(); } Errors
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.
3.x to 4.0
Use this link to view the 4.0 upgrade guide.
