[RFC] Simple Relation with targetted-class

[sroze]

I think that the current usage of Hateoas\Relation annotation could be simplified. Right now we need to add each relations at the class-level.

First of all, we sometime repeat the href link of an entity that is linked in two others for instance. We also must name the relation most of the time with the same name as the attribute's name: renaming could the optional.

To solve these issues, what do you think to allow attribute-level usage of Relation annotation, and add an target attribute on it ?

That way, entity defined in the documentation up to Embedding resources could be write:

/**
 * @Hateoas\Self(href = "expr('/api/user/' ~ object.getId())")
 */
class User
{
    /**
     * @Hateoas\Relation(
     *     target="User",
     *     embedded=true
     * )
     */
    private $manager;
}

To clarify the self relation, we could create an Hateoas\Self annotation. This could also reveal its usage by relations targeted to this entity.

The embedded attribute value become a boolean value that simply defines if this relation have to be embedded or just linked. We could rely on the JMS Serializer Accessor annotation to optionally use another getter.

Note that for me (and it appears that for JMS Serializer too), the exclusion in case of null value is logical so I think that we could make it by default and provide a way to force null values with a forceNull attribute on Hateoas\Exclusion annotation.

[adrienbrault]

FYI there is a link() function available with the expression language https://github.com/willdurand/Hateoas#the-link-function

The only reason I could see for Relation on attribute would be to infer the content of what to embed.
I think that having to explicitly define rel is a good practice (it makes sure that the REST/HAL interface is separated from the code).

[sroze]

I updated the sample, for sure the idea was also to remove the need of embedded attribute value (other than the boolean) ! Note that for me (and it appears that for JMS Serializer too), the exclusion in case of null value is logical so I think that we could make it by default and provide a way to force null values with a forceNull attribute on Hateoas\Exclusion annotation.

About the rel definition, I compare it to the columnName of Doctrine ORM: for sure it's configurable but based on the name of the attribute there's a default value, and it make it simple !

Another idea is that if the column already as Doctrine ORM annotation such has JoinColumn or *To*, or as JMS Serializer's Type annotation, we could read them to populate values such as target, exclusion groups, etc...

To finish, the link() function don't reuse extra attributes such as "type" (that I'm using) defined in the target class.

[adrienbrault]

So I think that allowing @Relation on attributes makes sense (I wonder if that should be allowed in yaml/xml). If the name is not set, it would use the attribute name; and if "embedded" is not defined, it would default to expr(object.get<name>).

Regarding solving the link thing, it does not seem trivial.

[sroze]

if "embedded" is not defined, it would default to expr(object.get).

I disagree: if embedded is not defined, it simply shouldn't be embedded. If the value is a true boolean, then the default could be expr(object.get<name>). Note that I think that using the PropertyAccess component would be a better idea.

It's like impossible to solve the link() problem because it is used in the href wrapped into an expression. Using a target parameter on the Relation attribute make it a lot easier - maybe just possible - to grab additional informations...

(I updated the first message)

[sroze]

@adrienbrault @willdurand It that seems good for you ? Is a PR that implement this behaviour would be merged ?