thephpleague/fractal — pull request #131 by crhayes (2014-11-28 04:04:59+00:00)
Title: Pass the scope identifier into the serializer item and collection method

This is a small change that I believe will add more flexibility to the serialization process.

This change will do two things:

1) Allow you to access the original key value of the resource being serialized.
2) More importantly, allow you to tell whether the resource being serialized is a 'root' resource or not; if there is a $scopeIdentifier then we know we are dealing with a nested resource, otherwise we have a root resource.

To illustrate point 1, if I have an array of ```ideas``` with sideloaded ```user``` and ```responses```, I might include the following in my IdeaTransformer:

```
public function includeResponses(array $idea) {
$responses = $idea['responses'];

return $this->collection($responses, new ResponseTransformer);
}

public function includeUser(array $idea) {
$user = $idea['user'];

return $this->item($user, new UserTransformer);
}
```

Even though I haven't specified a $resourceKey in the ```item``` or ```collection``` methods, I can still access the key that was originally on the ```$idea``` array (```responses``` and ```user``` respectively). Furthermore, if I do specify a key in the collection or item method, like so:

```
return $this->item($user, new UserTransformer, 'some_key');
```
then this will give me access to that specified key, as well as the original key in the $idea array.

For point 2, a change was made in an earlier version that created the separate ```item``` and ```collection``` methods for more flexibility. Knowing whether or not you are dealing with a root resource or a nested resource will provide even greater flexibility.

This would be very beneficial for a serializer I am writing to sideload data for Ember.js.