v2.4.0: support for specification v1.1 (final)

This is a small release, but important since it adds the last compatibility with the final v1.1 of the specification.

• On errors you can now use ErrorObject->blameHeader('X-Foo') when a requesting header is to blame for the error (#69)
• You can now detect the difference between a missing or empty include or sort query parameter. E.g. ?include= causes RequestParser->hasIncludePaths() to return true and RequestParser->getIncludePaths() to return an empty array. An empty include query parameter means no included resources should be returned. (#70)
• Better documentation on how extensions and profiles work. (#72)

Further this release improves support for php 8. (#71)

v2.3.0: local ids, extensions, and improved links and profiles (updating specification v1.1)

This release makes updates to the new features of https://github.com/lode/jsonapi/releases/tag/v2.1.0, as the jsonapi specification v1.1 got changes (it is now at RC 3 and might still change, but the latest concepts are updated in this release).

Support local ids

Clients can now use a local id (lid) instead of an id. This is useful when the client wants to connect relationships to a resource not yet known by the server.

• Added RequestParser->hasLocalId() and RequestParser->getLocalId() to check/get local ids from documents send by a client.
• Added setLocalId() on a ResourceDocument, ResourceObject or ResourceIdentifierObject, for sending a local id as a client.

In a jsonapi document this will look like:

{
	"data": {
		"type": "user",
		"lid": "42"
	}
}

See #53 and the specification.

Changes for links

Link objects get a lot of new documented members. On a LinkObject you can now call:

• ->setHumanTitle() to allow clients to add a human readable label to the link
• ->setRelationType() for clarifying what kind of RFC 8288 relation type the target has
• ->setMediaType() for clarifying which RFC 6838 media type the target has
• ->addLanguage()/->setHreflang() for stating which RFC 5646 language(s) the target is in
• ->setDescribedBy()/->setDescribedByLinkObject() for referencing to an JSON Scheme related to the link

Also, array links are deprecated. This caused confusion and wasn't used much.

• deprecated ErrorObject->appendTypeLink(), use ErrorObject->setTypeLink() instead.
• deprecated LinksObject->append()
• deprecated LinksObject->addLinksArray()
• deprecated LinksObject->appendLinkObject()

See #55, #62, the specification, the RFC 8288 relation types, the RFC 6838 media types, and the RFC 5646 language tags.

Changes for profiles and extensions

Customizing jsonapi was clarified. Profiles got better specification, and a concept of extensions got added. In short:

• Profiles can be used to define meaning for existing undefined members inside the jsonapi document.
• Extensions can be used to define new members inside the jsonapi document.

This release adds support for the Atomic Operations extension, and did updates to the Cursor Pagination profile.

• Added Document->applyExtension()
• Changed Document->applyProfile(): will add a profile to the root jsonapi object, and not to the root links object anymore.
• Changed Document->setSelfLink(): will add an object if extensions/profiles are applied, where before only a string might be added.
• Deprecated Profile->getKeyword(): aliasing of profile keywords got deprecated.
• Deprecated Converter::mergeProfilesInContentType(): use Converter::prepareContentType() instead.

See #59, #47, #67, the specification for atomic operations, and the specification for cursor pagination.

Documenting JSON Scheme

It is now easier to document which JSON Scheme is used (for jsonapi or next to jsonapi).

• Added Document->setDescribedByLink()

See #54.

v2.2.3: fix for PSR4 namespace mismatch

This fixes warnings you might see when running composer install with --optimize-autoloader.

See #68, thanks @jwissels!

v2.2.2: fix for nested include paths

Before, using multiple include paths which have the same start, only the last one would be recognized and the others ignored. This is fixed in #61.

v2.2.1: fix for non-POST requests (mainly)

Merge pull request #60 from lode/fix-request-with-partial-server-context

v2.2.0: help in parsing query parameters and request documents

This release makes it easier to process query parameters and request documents. There's a new RequestParser class which can be constructed from PSR-7 request objects or $_GET/$_POST/$_SERVER superglobals. See below or check the example code with all options.

Query parameters

On a a request for GET /users?fields[user]=name,location&sort=-name you can:

$requestParser->hasSparseFieldset('user'); // true
$requestParser->getSparseFieldset('user'); // ['name', 'location']

$requestParser->hasSortFields(); // true
$requestParser->getSortFields(); // [['field' => 'name', 'order' => RequestParser::SORT_DESCENDING]]

Request documents

On a request for POST /users with this POST data:

{
    "data": {
        "type": "user",
        "attributes": {
        	"name": "Zaphod"
        }
    }
}

You can check for contents inside a request document, without a lot of isset/array_has_key on nested arrays:

$requestParser->hasAttribute('name'); // true
$requestParser->getAttribute('name'); // 'Zaphod'

v2.1.0: extensions, arrays of links, @-members (supporting specification v1.1)

Support for v1.1 of the JSON:API specification, including:

Extensions via profiles

Extending a document structure with profiles. See an example profile and a specific cursor pagination example:

$profile = new CursorPaginationProfile();
$document->applyProfile($profile);

Array of links under a single key

E.g. for type error links:

$errorObject->appendTypeLink('https://...');

@-members

Which can be used for JSON-LD for example. They can be added to any object:

$anything->addAtMember('foo', 'bar');

v2.0.0: New specification-based interface (next to the human-friendly interface)

v2's main feature is having a strict specification-based interface for building documents. This is added next to keeping the human-friendly interface for people who don't know the spec, and don't want to get to know it.

Other features include:

• Explicitly empty relationships
• Jsonapi object in output to help discovery
• Unit and output tests
• php7 ready (php5.6 is still supported, php5.4 and 5.5 are dropped)

This release is breaking backwards compatibility with v1. However, most of the interface and output stayed the same. See the UPGRADE doc on how to upgrade.

The main reasons for the BC break are:

• the jsonapi specification started to recommend CamelCase in their v1.1
• php7 marks resource a reserved keyword, thus the main class name changed
• the current implementation offers too little flexibility for future changes in the specification

See the examples for more information.

Note: v2.0 of the library doesn't yet support v1.1 of the specification. A v2.1 is coming up and will support v1.1 of the specification.

v2.0.0-beta: New specification-based interface (next to the human-friendly interface)

v2's main feature is having a strict specification-based interface for building documents. This is added next to keeping the human-friendly interface for people who don't know the spec, and don't want to get to know it.

Further php7 is supported next to php5, and unit tests and json-output tests are added for the whole library.

This release is breaking backwards compatibility with v1. However, most of the interface and output stayed the same. See the UPGRADE doc on how to upgrade.

The main reasons for the BC break are:

• the jsonapi specification started to recommend CamelCase in their v1.1, thus all method names changed
• php7 marks resource a reserved keyword, thus the main class name changed (php5 is still supported, however support for php5.4 and php5.5 is dropped)
• the current implementation offers too little flexibility for future extensions of the spec

See the examples for more information.

Note: v2.0 of the library doesn't yet support v1.1 of the specification.

v1.5.1 Fix for free format relationships

Fixes free format relationships on resources #32, thanks @vvdt for reporting.