Allow hydrators to set `_embedded`

[weierophinney]

I have an odd case where the entity (hal resource) has a property name that is also (sometimes) the name of a link and embedded object. Basically a message can be sent by a user (which a link and embedded object exist for), or a non-user where some basic information had been gathered to identify them (but no link or embedded resource because they're not an user).

Quick example:

{
    "sender": {
        "name": "Test User",
        "number": "15556667878"
    },
    "_links": {
        "sender": {
            "href": "http://example.com/users/12345"
        }
    },
    "_embedded": {
        "sender": {
            "id": "12345",
            "name": "Test User",
            "number": "15556667878"
        }
    }
}

Because the hydrator can send back a link collection, which is merged into the entities links during render, it's possible to have both a link and an entity property with the same name. However, it's not possible to have both a entity property and an embedded entity with the same name, since both are passed from the hydrator using a simple array.

My thought is to add support for hydrators to return an _embedded key (optionally), and anything found there will be treated as embedded entities.

If I put this together as a PR, any opposition to merging it in?

---

Originally posted by @tjlytle at https://github.com/zfcampus/zf-hal/issues/52

[weierophinney]

The only potential problem I see may be just an error of omission: any item under _embedded MUST be itself a HAL resource (or collection of HAL resources) (per the HAL spec). What you have above is a bare object, not a HAL resource -- if the intention is that it will also be a HAL resource, then no objections here. :)

---

Originally posted by @weierophinney at https://github.com/zfcampus/zf-hal/issues/52#issuecomment-52493477

[weierophinney]

@weierophinney Yeah, I dropped out most of it for brevity. Anything passed as _embedded would have to be a renderable resource or collection.

---

Originally posted by @tjlytle at https://github.com/zfcampus/zf-hal/issues/52#issuecomment-52493863

[weierophinney]

@tjlytle Go for it, then. :)

---

Originally posted by @weierophinney at https://github.com/zfcampus/zf-hal/issues/52#issuecomment-52498555

[weierophinney]

Wouldn't this allow hydrators to do more than they're intended to do? My understanding is that their primary purpose is to extract/hydrate data from/to an object. If that's correct, configuring HAL links would seem out of scope for Hydrators...

Instead maybe we could fire an event after extraction and before linking?

---

Originally posted by @gsomoza at https://github.com/zfcampus/zf-hal/issues/52#issuecomment-67941705

[weierophinney]

@gabrielsomoza Hydrators exist to help facilitate the process of creating a representation; they're effectively part of the view layer when it comes to Apigility. As such, I think this is perfectly in their realm.

@tjlytle How's the PR coming? :)

---

Originally posted by @weierophinney at https://github.com/zfcampus/zf-hal/issues/52#issuecomment-68790658