Merge pull request #88 from lode/cleanup-and-document

Author: lode

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
 
@@ -19,9 +21,9 @@ composer require alsvanzelf/jsonapi
 
 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.
 
 
 

UPGRADE_2_TO_3.md

@@ -1,43 +1,70 @@
 # Upgrade from library v2 to v3
 
-## Checking links, ...
+## Enums
 
-Objects more often use uninitialized properties. `has*()` helper methods have been added to support the new flow.
+All constants have been replaced by enums.
 
-- `$object->links` to `if ($object->hasLinks()) $object->links`
+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`
 
-## Interfaces
+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)
 
-When extending interfaces, you'll have to add method argument types and return types.
+Document levels:
+- `Document::LEVEL_ROOT` (`'root'`) to `DocumentLevelEnum::Root`
+- `Document::LEVEL_JSONAPI` (`'jsonapi'`) to `DocumentLevelEnum::Jsonapi`
+- `Document::LEVEL_Resource` (`'resource'`) to `DocumentLevelEnum::Resource`
 
-Check [all interfaces](/src/interfaces) for the correct typing.
+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`
 
-## Enums
+Relationship types:
+- `RelationshipObject::TO_ONE` (`'one'`) to `RelationshipTypeEnum::ToOne`
+- `RelationshipObject::TO_MANY` (`'many'`) to `RelationshipTypeEnum::ToMany`
 
-Content types:
-- `Document::CONTENT_TYPE_OFFICIAL` to `ContentTypeEnum::Official`
-- `Document::CONTENT_TYPE_DEBUG` to `ContentTypeEnum::Debug`
-- `Document::CONTENT_TYPE_JSONP` to `ContentTypeEnum::Jsonp`
+Validator object containers (only used internally):
+- `Validator::OBJECT_CONTAINER_*` to `ObjectContainerEnum::*`
 
-Jsonapi versions:
-- `Document::JSONAPI_VERSION_1_0` to `JsonapiVersionEnum::V_1_0`
-- `Document::JSONAPI_VERSION_1_1` to `JsonapiVersionEnum::V_1_1`
-- `Document::JSONAPI_VERSION_LATEST` to `JsonapiVersionEnum::Latest`
 
-Document levels:
-- `Document::LEVEL_ROOT` to `DocumentLevelEnum::Root`
-- `Document::LEVEL_JSONAPI` to `DocumentLevelEnum::Jsonapi`
-- `Document::LEVEL_Resource` to `DocumentLevelEnum::Resource`
+## Strict type checking
 
-Sorting orders:
-- `RequestParser->getSortFields()` returns a `SortOrderEnum` instead of `string` for the `order` field
+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.
 
-Relationship types:
-- `RelationshipObject::TO_ONE` to `RelationshipTypeEnum::ToOne`
-- `RelationshipObject::TO_MANY` to `RelationshipTypeEnum::ToMany`
+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.
 
-## Internal
+Some invalid types were already checked at run-time and threw library exceptions. This now changed into php type errors.
 
-Enums:
-- `RequestParser::SORT_*` to `SortOrderEnum::*`
-- `Validator::OBJECT_CONTAINER_*` to `ObjectContainerEnum::*`
+
+## 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