This package uses doctrine/annotations in order to be able to convert models into json api resources. The new native php 8 attributes can achieve the same and are already supported since v1.1.0. That makes the annotations superfluous, so their support can be removed in the next major release v2.0.0.

Given is a model with a value object without any attribute properties. The model converter would convert the value object to null, although it is not null as property. It should be an empty hash instead.

The resource conveter currently supports no union types. Since php 8 is now the only support php version for new releases, we can continue adding union type support. It's currently disabled in src/Converter/ResourceConverter.php:82.

When designing RESTful API's you often want to use url's with additional context like this:

https://api.local/v1/customer/{customerId}/invoice/{invoiceId}

The current JSON API request makes it hard to pull out all named route parameters before the json api request part of the URL starts. There should be an easy to use mechanism to fetch named route parameters from the request, in addition to the existing id method. Without having that feature, one has to find a workaround to bypass the application default request object to the request handler without using the default json api tools.

The model conversion should support the new php 8 attributes like this:

#[Type("dummy-model")]
class DataModel
{
    #[Id]
    private ?int $id = 123456;

    #[Attribute]
    private ?string $name = 'loremIpsum';

    #[Attribute('values')]
    private ValueObject $valueObject;

    #[Attribute('empty-values')]
    private ?ValueObject $valueObjectNotInitialized = null;

    #[Attribute(ignoreOnNull: true)]
    private ?string $ignoreOnNull = null;
}

The currently used doctrine/annotations will still be supported. We could think about removing annotation support in the next major release v2.0.0. Although we have to drop php 7.4 support in order to have php 8 attributes, we can put this update into version v1.1.0.

Since it's planned to drop the doctrine/annotations support and replace it with php 8 attributes, a deprecation error should be triggered every time the annotations will be used under a php 8 environment.

When the JSON-API server receives a PATCH request, the model converter will automatically fill in the existing payload attributes into the provided model instance. As a result, we have a blank model instance where only those properties are filled, which have been provided with values in the request body.

A PATCH request is designed to modify an existing document partially, but here comes the problem: When trying to work with the converted payload model instance further, we don't know if a property with a null value should be persisted to be null or if it just wasn't set in the request body. We loose the necessarry request payload context. Therefor we require an optional model method, which will provide the information, whether a certain property is intended to be null, because it needs to be "removed", or if it's just blank because it has not been provided. So something equivalent to the php isset function.

The model converter always converts value objects with defined attributes to completete instances with null values, although the value object is null. The resulting json resource attribute should be null in that case.