Add PASS_THRU extraction

[bakura10]

Hi,

This add another extraction strategy (I think we all have them now), that I called PASS_THRU. Basically, it allows a parent hydrator to decide how to extract child resources, and is a hint to a renderer to use this representation.

For instance, let's say you have a User with a roles ManyToMany associations. If you use the "ID" strategy, you'll have a payload that looks like this:

{"username": "Toto", "roles": [4, 2]}

If you use "EMBED", it will use the hydrator attached to the Role entity, and payload will look like this:

{"username": "Toto", "roles": [{"id": 4, "name": "member"}, {"id":2, "name": "admin"]}

However for those cases, what we prefer is to have a simpler representation as array:

{"username": "Toto", "roles": ["member", "admin"]}

This PASS_THRU extraction policy is made for that: you can decide that for this specification association, it's up to the parent hydrator (in this case, the UserHydrator) to decide how to represent this nested resource. For instance, you can write a UserHydrator that builds itself how roles are represented:

class UserWithRoleHydrator extends ClassMethods
{
    public function extract($object)
    {
        $payload = parent::extract($object);
        $roles   = $object->getRoles();

        $payload['roles'] = []; // Clear automatic extraction from ClassMethods

        foreach ($roles as $role) {
            $payload['roles'][] = $role->getName();
        }

        return $payload;
    }
}

And here is how you can configure the association:

/**
 * @REST\Association(routable=false, extraction="PASS_THRU")
 */
protected $roles;

Let me know if you like the idea :)

ping @danizord @Ocramius

[coveralls]

Coverage increased (+0.04%) when pulling 55943a6 on pass-thru-extraction into 335a424 on master.

[bakura10]

Anyone? I'll merge that otherwise :).

[Ocramius]

Unclear wording

[bakura10]

Thanks.