Feature request: Full support for Structured Values / Value Objects / Embedded

Proposal: Support for Value Objects

I would like to suggest that full support for objects, which does / might not have an ID and (when using Doctrine) might be saved in a json field of their parent object would be implemented. I am calling these “ValueObjects” bellow and as an example of such object I would suppose there exist a class named ‘SomeStructure’ which has been marked as ‘ValueObject’.

They could be denoted by a specific Annotation / Configuration, e.g.:

/**
 * @ValueObject()
 */
class SomeStructure
{
    public $someField;
}

By full support I understand:

• they should require no ID in any context

• they should require no IRI in any context

• they should require no path to resource in any context

• possibility to define a field on ApiResource, able to accept item (one) of ‘SomeStructure’, with phpDoc @var SomeStructure $someField

• possibility to define a field on ApiResource, able to accept collection (array) of ‘SomeStructure’, with phpDoc @var SomeStructure[] $someField

• correct automatic normalization and denormalization of these values (without need of writing custom normalizers / decorating normalizers and without normalizer complaining about missing iri or path…)

• possibility to define validation directly on these ValueObjects (which might be triggered by using ‘Valid’ for item and ‘All(Valid)’ for collection on their parents)

• possibility to define normalization and validation groups

• automatic generation of proper swagger/openApi documentation for them with examples (so that examples of them are not shown as ‘[“string”]’ in Swagger UI)

• possibility of nesting of ValueObjects, so that one ValueObject might have another ValueObject under its field (as well as collection of ValueObject of specific type)

• possibility of combining ApiResources and ValueObjects, so that one ValueObject might have (reference to) ApiResource under its field (as well as collection of ApiResource of specific type). It would be nice to provide options to choose whether retrieve and embed the resource or just include iri / id.

• they should allow clean and safe use without hacks. (Currently it is possible to define class as ApiResource and forbid all operations, but this approach is not stable (easy to fail))

Notes:

I am calling them here ‘ValueObject’ but the term (and implementation) might be different. They are referred to as ‘StructuredValue’ by @teohhanhui (in https://github.com/api-platform/core/issues/181#issuecomment-122871245 ) and @Arkowsky (in https://github.com/api-platform/api-platform/issues/1105 ) and under ‘ValueObject & no identifier’ by @ogizanagi (in https://github.com/api-platform/core/issues/227 )

References:

• https://github.com/api-platform/api-platform/issues/1105
• https://github.com/api-platform/core/issues/227
• https://github.com/api-platform/core/issues/181#issuecomment-122871245
• https://github.com/api-platform/core/issues/166#issuecomment-123144942
• https://github.com/api-platform/core/issues/1392#issuecomment-343227659
• https://github.com/api-platform/api-platform/issues/1105
• https://stackoverflow.com/questions/56275937/how-can-i-annotate-my-attribute-which-is-value-object-in-order-that-api-platform

[soyuka]

Didn’t quite got the time to finish my work on that, I hope I can open a PR soon.

[teohhanhui]

Thanks for the summary. This is definitely much needed and will fix a lot of problems, including around documenting non-resource classes.