Merge branch 'v3'

Author: lode

.github/workflows/lint.yml

@@ -1,6 +1,7 @@
 name: lint
 on:
   pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
     paths:
       - "**.php"
 

.github/workflows/test.yml

@@ -1,6 +1,7 @@
 name: test
 on:
   pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
     paths:
       - "**.php"
 

README.md

@@ -8,6 +8,8 @@ while being easy to understand for people without knowledge of the jsonapi stand
 The JSON:API standard makes it easy for clients to fetch multiple resources in one call and understand the relations between them.
 Read more about it at [jsonapi.org](https://jsonapi.org/).
 
+The library's code uses strict typing and is checked against a high standard in phpstan and rector. It is tested extensively with 99% coverage.
+
 
 ## Installation
 
@@ -17,11 +19,11 @@ Read more about it at [jsonapi.org](https://jsonapi.org/).
 composer require alsvanzelf/jsonapi
 ```
 
-The library supports, and is is tested on, php versions 5.6, 7 and 8.
+The library requires php 8.2. Use the latest [v2.x release](/releases/tag/v2.5.0) for lower php versions.
 
-#### Upgrading from v1
+#### Upgrading from v1 or v2
 
-If you used v1 of this library, see [UPGRADE_1_TO_2.md](/UPGRADE_1_TO_2.md) on how to upgrade.
+If you used v1 or v2 of this library, see [UPGRADE_1_TO_2.md](/UPGRADE_1_TO_2.md) or [UPGRADE_2_TO_3.md](/UPGRADE_1_TO_2.md) on how to upgrade.
 
 
 
@@ -32,7 +34,7 @@ If you used v1 of this library, see [UPGRADE_1_TO_2.md](/UPGRADE_1_TO_2.md) on h
 ```php
 use alsvanzelf\jsonapi\ResourceDocument;
 
-$document = new ResourceDocument($type='user', $id=42);
+$document = new ResourceDocument(type: 'user', id: 42);
 $document->add('name', 'Zaphod Beeblebrox');
 $document->add('heads', 2);
 $document->sendResponse();
@@ -175,11 +177,11 @@ use alsvanzelf\jsonapi\ResourceDocument;
 use alsvanzelf\jsonapi\interfaces\ExtensionInterface;
 
 class ExampleExtension implements ExtensionInterface {
-	public function getOfficialLink() {
+	public function getOfficialLink(): string {
 		return 'https://example.org/extension-documentation';
 	}
 
-	public function getNamespace() {
+	public function getNamespace(): string {
 		return 'foo';
 	}
 }

UPGRADE_2_TO_3.md

@@ -0,0 +1,70 @@
+# Upgrade from library v2 to v3
+
+## Enums
+
+All constants have been replaced by enums.
+
+Content types:
+- `Document::CONTENT_TYPE_OFFICIAL` (`'application/vnd.api+json'`) to `ContentTypeEnum::Official`
+- `Document::CONTENT_TYPE_DEBUG` (`'application/json'`) to `ContentTypeEnum::Debug`
+- `Document::CONTENT_TYPE_JSONP` (`'application/javascript'`) to `ContentTypeEnum::Jsonp`
+
+Jsonapi versions:
+- `Document::JSONAPI_VERSION_1_0` (`'1.0'`) to `JsonapiVersionEnum::V_1_0`
+- `Document::JSONAPI_VERSION_1_1` (`'1.1'`) to `JsonapiVersionEnum::V_1_1`
+- `Document::JSONAPI_VERSION_LATEST` (`'1.1'`) to `JsonapiVersionEnum::latest()` (still refering to v1.1)
+
+Document levels:
+- `Document::LEVEL_ROOT` (`'root'`) to `DocumentLevelEnum::Root`
+- `Document::LEVEL_JSONAPI` (`'jsonapi'`) to `DocumentLevelEnum::Jsonapi`
+- `Document::LEVEL_Resource` (`'resource'`) to `DocumentLevelEnum::Resource`
+
+Sorting orders (as return value in the `order` field from `RequestParser->getSortFields()`):
+- `RequestParser::SORT_ASCENDING` (`'ascending'`) to `SortOrderEnum::Ascending`
+- `RequestParser::SORT_DESCENDING` (`'descending'`) to `SortOrderEnum::Descending`
+
+Relationship types:
+- `RelationshipObject::TO_ONE` (`'one'`) to `RelationshipTypeEnum::ToOne`
+- `RelationshipObject::TO_MANY` (`'many'`) to `RelationshipTypeEnum::ToMany`
+
+Validator object containers (only used internally):
+- `Validator::OBJECT_CONTAINER_*` to `ObjectContainerEnum::*`
+
+
+## Strict type checking
+
+When using the library you shouldn't notice this unless passing values of the wrong type. When extending the library you probably will notice this when overriding methods.
+
+In both cases the upgrade is relatively easy, you can just follow php's type errors. Using phpstan will also help you find typing mismatches.
+
+Some invalid types were already checked at run-time and threw library exceptions. This now changed into php type errors.
+
+
+## Object properties are uninitialized by default
+
+Objects more often use uninitialized properties. In some cases, `has*()` helper methods have been added to support the new flow. Otherwise, an `isset()` can be used if needed.
+
+_This should only affect you when you extend the libraries classes. Otherwise you can just use the library methods to handle these properties._
+
+- `->links`, on `Document`, `ErrorObject`, `RelationshipObject`, `ResourceObject`, can be checked with `->hasLinks()`
+- `Document`: `->httpStatusCode`, `->jsonapi`, `->meta`
+- `ErrorObject`: `->id`, `->code`, `->title`, `->detail`, `->meta`, `->httpStatusCode`
+- `JsonapiObject`: `->meta`, `->version`
+- `LinkObject`: `->href`, `->rel`, `->describedby`, `->title`, `->type`, `->meta`
+- `RelationshipObject`: `->meta`, `->resource`, `->type`
+- `ResourceDocument`: `->resource`
+- `ResourceIdentifierObject`: `->type`, `->id`, `->lid`, `->meta`, `->validator`
+- `ResourceObject`: `->attributes`, `->relationships`
+
+
+## Json encoding and decoding errors
+
+The default encoding options changed to also include `JSON_THROW_ON_ERROR`. Failure to encode already used to throw an exception, but now it will default to a `\JsonException`.
+
+
+## Removed deprecations
+
+- Old v1-style classes (`base.php`, `collection.php`, `error.php`, `errors.php`, `exception.php`, `resource.php`, `response.php`)
+- Array-style links (`->appendLink()`, `->addLinksArray()`, `->appendLinkObject()`, `ErrorObject->appendTypeLink()`, `LinksArray`, `LinksObject->append()`)
+- `CursorPaginationProfile->getKeyword()`
+- `Converter::mergeProfilesInContentType()`, use `Converter::prepareContentType()` instead

composer.json

@@ -13,7 +13,7 @@
 		}
 	],
 	"require": {
-		"php": ">=5.6",
+		"php": ">=8.2",
 		"ext-json": "*"
 	},
 	"autoload": {