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.
To upgrade, run the following Composer command:
composer require cloudcreativity/laravel-json-api:5.0.0-alpha.1We'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.
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
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();
}The functions that are used to call meta data has also been changed. Before there were these 2 functions:
public function getPrimaryMeta($resource)
{
return ['foo => 'bar'];
}
public function getInclusionMeta($resource)
{
return $this->getPrimaryMeta($resource);
}These have now been replaced with 1 function:
public function getResourceMeta($resource): ?array
{
return ['foo => 'bar'];
}This method will be used in place of the other 2. In the rare event that your inclution meta was different from primary, you may need to amalgemate.
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.