Upgrade Guide

4.x to 5.0

Background

This major release upgrades the underlyingneomerx/json-api dependency fromv1 tov5 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 installboth this package and the newer package, unlocking an upgrade path between the two. While you cannot have an API thatmixes the two packages, an application could now have an older API running off the old package, and a newer APIimplemented with the new package. Overtime you can deprecate the older API and eventually remove it - removingcloudcreativity/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:APIformatting. The problem we have always had withcloudcreativity/laravel-json-api is the package is too tightlycoupled to the Neomerx implementation. This means this upgrade is a major internal change. While we have tested theupgrade 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 hiddenbehind generic interfaces. This fixed the problems with coupling and was one of the main motivations in building thenew 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 anychanges to the implementation, e.g. by overriding elements of our implementation or using any of the Neomerx classesdirectly, 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 withCloudCreativity\LaravelJsonApi\Contracts\Http\Query\QueryParametersInterface
  • Neomerx\JsonApi\Encoder\Parameters\EncodingParameters replace withCloudCreativity\LaravelJsonApi\Http\Query\QueryParameters
  • Neomerx\JsonApi\Schema\SchemaProvider replace withCloudCreativity\LaravelJsonApi\Schema\SchemaProvider

And it will also definitely be using these type-hints, that must be replaced:

  • EncodingParametersInterface withQueryParametersInterface
  • EncodingParameters withQueryParameters

The following import statements also need changing, however you should not worry if you cannot find any usages of themwithin your application:

  • Neomerx\JsonApi\Contracts\Encoder\Parameters\SortParameterInterface replace withCloudCreativity\LaravelJsonApi\Contracts\Http\Query\SortParameterInterface
  • Neomerx\JsonApi\Encoder\Parameters\SortParameter replace withCloudCreativity\LaravelJsonApi\Http\Query\SortParameter
  • Neomerx\JsonApi\Contracts\Document\ErrorInterface replace withNeomerx\JsonApi\Contracts\Schema\ErrorInterface
  • Neomerx\JsonApi\Document\Error replace withNeomerx\JsonApi\Schema\Error
  • Neomerx\JsonApi\Exceptions\ErrorCollection replace withNeomerx\JsonApi\Schema\ErrorCollection
  • Neomerx\JsonApi\Contracts\Document\LinkInterface replace withNeomerx\JsonApi\Contracts\Schema\LinkInterface
  • Neomerx\JsonApi\Contracts\Document\DocumentInterface replace withNeomerx\JsonApi\Contracts\Schema\DocumentInterface
  • Neomerx\JsonApi\Contracts\Http\Headers\HeaderInterface replace withCloudCreativity\LaravelJsonApi\Contracts\Http\Headers\HeaderInterface
  • Neomerx\JsonApi\Contracts\Http\Headers\AcceptHeaderInterface replace withCloudCreativity\LaravelJsonApi\Contracts\Http\Headers\AcceptHeaderInterface
  • Neomerx\JsonApi\Contracts\Http\Headers\HeaderParametersParserInterface replace withCloudCreativity\LaravelJsonApi\Contracts\Http\Headers\HeaderParametersParserInterface
  • Neomerx\JsonApi\Contracts\Http\Query\QueryParametersParserInterface replace 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 yourschemas. For example thegetId(),getAttributes() andgetRelationships() 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 astring type-hint to the$resourceType property.

Optionally, you can remove thegetId() 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. Checkyour 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.

2.x to 3.0

Use this link to view the 3.0 upgrade guide.