Upgrade Notes

To 4.0 from 3.x

Overall, versions 3 and 4 are nearly identical and the main changes were made in SchemaInterface. An extra parameter ContextInterface was added to SchemaInterface::getAttributes and SchemaInterface::getRelationships. Thus the following changes are needed for migration

// add `use`
use Neomerx\JsonApi\Contracts\Schema\ContextInterface;

class YourSchema extends BaseSchema
{
    // ...

    // add `ContextInterface $context`
    public function getAttributes($author, ContextInterface $context): iterable
    {
    }

    // add `ContextInterface $context`
    public function getRelationships($resource, ContextInterface $context): iterable
    {
    }
}

The context contains an extra information about resource such as its position in the data tree and encoder options such as filter field set and included paths. The context might be used for smarter loading resources from a database. Here is an example how a context might look in a debugger

To 3.0 from 2.x

Overall, versions 2 and 3 are very similar, though some of the classes, interfaces, constants and methods were renamed. Here is a list of things that should help you to migrate.

Moved interfaces and classes

• Replace Neomerx\JsonApi\Contracts\Document\DocumentInterface; with Neomerx\JsonApi\Contracts\Schema\DocumentInterface;
• Replace Neomerx\JsonApi\Contracts\Document\ErrorInterface; with Neomerx\JsonApi\Contracts\Schema\ErrorInterface;
• Replace Neomerx\JsonApi\Exceptions\ErrorCollection; with Neomerx\JsonApi\Schema\ErrorCollection;

Schema changes

Resource type should be declared with method getType(): string.

Signature has been changed for the following methods

• getAttributes has changed to getAttributes($resource): iterable
• getRelationships has changed to getRelationships($resource): iterable

Relationship constants has been renamed

• relationship key self::DATA renamed to self::RELATIONSHIP_DATA
• relationship key self::SHOW_SELF renamed to self::RELATIONSHIP_LINKS_SELF
• relationship key self::SHOW_RELATED renamed to self::RELATIONSHIP_LINKS_RELATED

Link constructor has been changed completely. See Links section for more.

Error and methods for adding errors to ErrorCollection has new parameter ?iterable $typeLinks. Please make sure you use the new signatures.

To 2.0 from 1.x

PHP strong types were added to all applicable interface and class methods. Actual methods to be updated depending on your usage however many users will need to change only the following ones

class YourSchema extends BaseSchema
{
    public function getId($resource): ?string
    {
        // `: ?string` is added

        ...
    }

    public function getAttributes($resource, array $fieldKeysFilter = null): ?array
    {
        // `array $fieldKeysFilter = null` and `: ?array` are added

        ...
    }

    public function getRelationships($resource, bool $isPrimary, array $includeRelationships): ?array
    {
        // `: ?array` is added

        ...
    }
}

QueryParametersParser and RestrictiveQueryChecker were replaced with BaseQueryParser which parses defined by JSON API spec parts (e.g. fieldsets, includes, sorts) and provides helpful methods to work with not defined parts (e.g. filters, pagination).

Adapter class Request for non-PSR7 requests has been dropped.

Code related to JSON API Extensions has been deprecated and removed from the library.

Extensions and codec matcher were removed from class Responses which was renamed to BaseResponses.

Header parsers were simplified and changed significantly. Please read the related documentation in parsing API parameters section.

To 1.0 from 0.8.11

Added serialization to arrays which required refactoring protected members of class Encoder. If you do not inherit Encoder class in order change/extend its functionality you will migrate to 1.0 without changes in your code.

If you do inherit Encoder class and use protected members such as $container, $encoderOptions and etc you should use new methods getContainer(), getEncoderOptions() and etc. Also method encodeDataInternal() was renamed to encodeDataToArray() and now returns array instead of string. In order to convert array to json string method encodeToJson() should be used.

To 0.8.0 from 0.7.1

• Method getRelationships of Schema has changed its signature from getRelationships($resource, array $includeList = []) to getRelationships($resource, $isPrimary, array $includeList). New parameter $isPrimary informs if $resource will be put into primary data section rather than included. Parameter $includeList do not have default value now. For more see.
• If you declared manual Link adding in getRelationships of Schema and those links had relative paths it should be changed from 'boo' => new Link('some/link') to 'boo' => new Link($this->getSelfSubUrl($resource) . '/some/link'). For more see.

Both changes are made for better paging support in relationships.

• Optional field $selfSubUrl in Schema should now have only starting slash (no ending slash anymore). If not set manually it will be composed as $this->selfSubUrl = '/' . $this->resourceType;. For more see.

• LinkInterface was moved from Neomerx\JsonApi\Contracts\Schema namespace to Neomerx\JsonApi\Contracts\Document.

• Link was moved from Neomerx\JsonApi\Schema namespace to Neomerx\JsonApi\Document.

• EncodingParametersInterface was moved from Neomerx\JsonApi\Contracts\Http\Parameters namespace to Neomerx\JsonApi\Contracts\Encoder.

• EncodingParameters was moved from Neomerx\JsonApi\Http\Parameters namespace to Neomerx\JsonApi\Encoder.

These changes were inspired by this enhancement request.

HTTP classes for parsing and checking headers/query parameters are separated for better structure. It's a small part of the project though it was significantly refactored. Some of the highlights below. If you have any questions/difficulties while upgrading please don't hesitate to ask.

Class EncodingParameters now contains all parameters that come from HTTP query string (pagination, filters, sorting, etc). Also EncodingParameters moved from \Neomerx\JsonApi\Encoder\EncodingParameters to \Neomerx\JsonApi\Encoder\Parameters\EncodingParameters. That's probably the most frequent change you will have to do in your code.

HTTP headers related methods were moved from ParametersInterface to HeaderParametersInterface (\Neomerx\JsonApi\Contracts\Http\Headers\HeaderParametersInterface).

All HTTP query related methods from ParametersInterface were merged to EncodingParametersInterface.

Related issue.

To 0.7.0 from 0.6.6

• Homegrown HTTP interfaces (e.g. CurrentRequestInterface) were replaced with PSR-7 (\Psr\Http\Message\ServerRequestInterface particularly). See #109 for details. Small changes on your side will be required if you use HTTP part from this package (ParameterParser, CodecMatcher, ParametersChecker and etc).
• Class for HTTP Response creation (Responses) was significantly refactored. Now it provides full variety of JSON API responses and has a few abstract method which allows integrate it with any framework/application. For more see here and here.
• Error handling was improved. RendererContainerInterface and RendererInterface. New class JsonApiException and ErrorCollection were added. For more see.
• PSR-3 logging was added. For usage sample see.
• CodecMatcherInterface::findDecoder was renamed to CodecMatcherInterface::matchDecoder.

To 0.6.5 from 0.6.4

Field $selfSubUrl in Schema has become optional. By default it is constructed as

    $this->selfSubUrl = '/' . $this->resourceType . '/';

If you specify $selfSubUrl it will be checked that it starts and ends with /. Thus for performance reasons it is recommended to not set $selfSubUrl (unless it is different from default value).

To 0.6.0 from 0.5.X

Links, Meta, API Version

Passing Links, Meta and JSON API version information via Encoder parameters have been deprecated and removed from the code. They should be passed via with... methods e.g.

$encoder
    ->withLinks($links)
    ->withMeta($docMeta)
    ->withJsonApiVersion($versionMeta)
    ->encodeData(...);

Schema Relationships

A new parameter array[] $includeRelationships was added to method Schema::getRelationships. The parameter contains a list of relationship names which will be included in output result as full resources (attributes and relationships). It could be used for more optimal data fetch requests to a database. For example if a model Comment contains field author_id and $includeRelationships do not contain author an Author instance with empty attributes could be returned. It eliminates the necessity to make request(s) to a database for such cases.

The new parameter should be added to existing Schemas

class CommentSchema extends BaseSchema
{
    ...

    public function getRelationships($comment, array $includeRelationships)
    {
        ...
    }
    
    ...
}

Schema Links

Fields $isShowSelf (default true) and $isShowSelfInIncluded (default false) were replaced with methods getResourceLinks and getIncludedResourceLinks (default implementation below). If you have not changed $isShowSelf and $isShowSelfInIncluded you do not need to make any changes in your code.

public function getResourceLinks($resource)
{
    $links = [
        LinkInterface::SELF => $this->getSelfSubLink($resource),
    ];

    return $links;
}

public function getIncludedResourceLinks($resource)
{
    return [];
}