v3.0.0: Strict typing, requiring php 8.2, and other cleanup

This version is mainly a cleanup without functional change. There is no change from the jsonapi specification.

The main changes are:

• Enums instead of constants. This will be the main change you'll need to adjust for, see the UPGRADE doc for details. In short:
  • Document::CONTENT_TYPE_* to ContentTypeEnum::*
  • Document::JSONAPI_VERSION_* to JsonapiVersionEnum::*
  • Document::LEVEL_* to DocumentLevelEnum::*
  • RequestParser::SORT_* to SortOrderEnum::*
  • RelationshipObject::TO_* to RelationshipTypeEnum::*
• Requiring php 8.2 as minimum version. Already 90% of composer installs run this version. Also from 2026 on, php 8.1 and lower are not receiving regular or security updates anymore.
• Removing deprecated features. There were deprecated since v2.0 / 2019 (old v1-style classes) and v2.3 / 2021 (array links and profile alias, introduced in v2.1 and never that popular). A big chance you don't use them when already using v2.x.
• Adding type hints. All code now uses strict typing and is checked against a high standard in phpstan and rector. As before, the test coverage is 99%.

Apart from the constants to enums change, you probably won't notice the upgrade if:

• you run php 8.2+; otherwise you need to stay on v2
• you don't extend library classes; otherwise you might need to adjust typing in your extending classes
• you pass the right type of values; otherwise you need adjust for that

If you encounter issues, it shouldn't be too hard to upgrade either. You'll get clear explanations from php type errors. See the UPGRADE doc for the details.

v3.0.0-beta: Strict typing, requiring php 8.2, and other cleanup

This version is mainly a cleanup without functional change. There is no change from the jsonapi specification.

The main changes are:

• Enums instead of constants. This will be the main change you'll need to adjust for, see the UPGRADE doc for details. In short:
  • Document::CONTENT_TYPE_* to ContentTypeEnum::*
  • Document::JSONAPI_VERSION_* to JsonapiVersionEnum::*
  • Document::LEVEL_* to DocumentLevelEnum::*
  • RequestParser::SORT_* to SortOrderEnum::*
  • RelationshipObject::TO_* to RelationshipTypeEnum::*
• Requiring php 8.2 as minimum version. Already 90% of composer installs run this version. Also from 2026 on, php 8.1 and lower are not receiving regular or security updates anymore.
• Removing deprecated features. There were deprecated since v2.0 / 2019 (old v1-style classes) and v2.3 / 2021 (array links and profile alias, introduced in v2.1 and never that popular). A big chance you don't use them when already using v2.x.
• Adding type hints. All code now uses strict typing and is checked against a high standard in phpstan and rector. As before, the test coverage is 99%.

Apart from the constants to enums change, you probably won't notice the upgrade if:

• you run php 8.2+; otherwise you need to stay on v2
• you don't extend library classes; otherwise you might need to adjust typing in your extending classes
• you pass the right type of values; otherwise you need adjust for that

If you encounter issues, it shouldn't be too hard to upgrade either. You'll get clear explanations from php type errors. See the UPGRADE doc for the details.

v2.5.0: cleanup

A small cleanup:

• Improving linting level.
• Some small fixes in phpdocs.
• No changes in function declarations. Leaving that to another major version.
• Nicer exceptions when passing invalid data to some functions, which already threw 'unknown method' exceptions.

Bumping minor version because there are a few new interface you could use if you're building own objects and documents.

This is last release before a new major, moving to new php version and stricter typing.

v2.4.1: fix PHP 8.4 deprecations

Merge pull request #77 from jasperwissels/prepare-php-84

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'