Conditionally Serializing Fields with Groups
Keep on Learning!
If you liked what you've learned so far, dive in! Subscribe to get access to this tutorial plus video, code and script downloads.
With a Subscription, click any sentence in the script to jump to that part of the video!
Login SubscribeOnce upon a time, I worked with a client that had a really interesting API requirement. In fact, one that totally violate REST... but it's kinda cool. They said:
When we have one object that relates to another object - like how our programmer relates to a user - sometimes we want to embed the user in the response and sometimes we don't. In fact, we want the API client to tell us via - a query parameter - whether or not they want embedded objects in the response.
Sounds cool...but it totally violates REST because you now have two different URLs that return the same resource... each just returns a different representation. Rules are great - but come on... if this is useful to you, make it happen.
Testing the Deep Functionality
Let's start with a quick test: copy part of testGETProgramer() and name the new method testGETProgrammerDeep(). Now, add a query parameter called ?deep:
| // ... lines 1 - 5 | |
| class ProgrammerControllerTest extends ApiTestCase | |
| { | |
| // ... lines 8 - 58 | |
| public function testGETProgrammerDeep() | |
| { | |
| $this->createProgrammer(array( | |
| 'nickname' => 'UnitTester', | |
| 'avatarNumber' => 3, | |
| )); | |
| $response = $this->client->get('/api/programmers/UnitTester?deep=1'); | |
| $this->assertEquals(200, $response->getStatusCode()); | |
| // ... lines 68 - 70 | |
| } | |
| // ... lines 72 - 245 | |
| } |
The idea is simple: if the client adds ?deep=1, then the API should expose more embedded objects. Use the asserter to say assertResponsePropertyExists(), pass that the $response and the property we'll expect, which is user. Since this will be an entire user object, check specifically for user.username:
| // ... lines 1 - 5 | |
| class ProgrammerControllerTest extends ApiTestCase | |
| { | |
| // ... lines 8 - 58 | |
| public function testGETProgrammerDeep() | |
| { | |
| // ... lines 61 - 67 | |
| $this->asserter()->assertResponsePropertiesExist($response, array( | |
| 'user.username' | |
| )); | |
| } | |
| // ... lines 72 - 245 | |
| } |
Very nice!
Serialization Groups
If you look at this response in the browser, we definitely do not have a user field. But there are only two little things we need to do to add it.
First, expose the user property with @Serializer\Expose():
| // ... lines 1 - 21 | |
| class Programmer | |
| { | |
| // ... lines 24 - 65 | |
| /** | |
| // ... lines 67 - 69 | |
| * @Serializer\Expose() | |
| */ | |
| private $user; | |
| // ... lines 73 - 196 | |
| } |
Of course, it can't be that simple: now the user property would always be included. To avoid that, add @Serializer\Groups() and use a new group called deep:
| // ... lines 1 - 21 | |
| class Programmer | |
| { | |
| // ... lines 24 - 65 | |
| /** | |
| // ... lines 67 - 68 | |
| * @Serializer\Groups({"deep"}) | |
| * @Serializer\Expose() | |
| */ | |
| private $user; | |
| // ... lines 73 - 196 | |
| } |
Here's the idea: when you serialize, each property belongs to one or more "groups". If you don't include the @Serializer\Groups annotation above a property, then it will live in a group called Default - with a capital D. Normally, the serializer serializes all properties, regardless of their group. But you can also tell it to serialize only the properties in a different group, or even in a set of groups. We can use groups to serialize the user property under only certain conditions.
But before we get there - I just noticed that the password field is being exposed on my User. That's definitely lame. Fix it by adding the Expose use statement, removing that last part and writing as Serializer instead. That's a nice trick to get that use statement:
| // ... lines 1 - 7 | |
| use JMS\Serializer\Annotation as Serializer; | |
| // ... lines 9 - 14 | |
| class User implements UserInterface | |
| { | |
| // ... lines 17 - 84 | |
| } |
Now set @Serializer\ExclusionPolicy() above the class with all and add @Expose above username:
| // ... lines 1 - 9 | |
| /** | |
| * @Serializer\ExclusionPolicy("all") | |
| * @ORM\Table(name="battle_user") | |
| * @ORM\Entity(repositoryClass="AppBundle\Repository\UserRepository") | |
| */ | |
| class User implements UserInterface | |
| { | |
| // ... lines 17 - 23 | |
| /** | |
| * @Serializer\Expose() | |
| * @ORM\Column(type="string", unique=true) | |
| */ | |
| private $username; | |
| // ... lines 29 - 84 | |
| } |
Back in Programmer.php, remove the "groups" code temporarily and refresh. OK good, only the username is showing. Put that "groups" code back.
Setting the SerializationGroup
Ok... so now, how can we serialize a specific set of groups? To answer that, open ProgrammerController and find showAction(). Follow createApiResponse() into the BaseController and find serialize():
| // ... lines 1 - 16 | |
| abstract class BaseController extends Controller | |
| { | |
| // ... lines 19 - 123 | |
| protected function serialize($data, $format = 'json') | |
| { | |
| $context = new SerializationContext(); | |
| $context->setSerializeNull(true); | |
| return $this->container->get('jms_serializer') | |
| ->serialize($data, $format, $context); | |
| } | |
| } |
When we serialize, we create this SerializationContext, which holds a few options for serialization. Honestly, there's not much you can control with this, but you can set which groups you want to serialize.
First, get the $request object by fetching the request_stack service and adding getCurrentRequest(). Next, create a new $groups variable and set it to only Default: we always want to serialize the properties in this group:
| // ... lines 1 - 16 | |
| abstract class BaseController extends Controller | |
| { | |
| // ... lines 19 - 123 | |
| protected function serialize($data, $format = 'json') | |
| { | |
| $context = new SerializationContext(); | |
| $context->setSerializeNull(true); | |
| $request = $this->get('request_stack')->getCurrentRequest(); | |
| $groups = array('Default'); | |
| // ... lines 131 - 137 | |
| } | |
| } |
Now say if ($request->query->get('deep')) is true then add deep to $groups. Finish this up with $context->setGroups($groups):
| // ... lines 1 - 16 | |
| abstract class BaseController extends Controller | |
| { | |
| // ... lines 19 - 123 | |
| protected function serialize($data, $format = 'json') | |
| { | |
| // ... lines 126 - 129 | |
| $groups = array('Default'); | |
| if ($request->query->get('deep')) { | |
| $groups[] = 'deep'; | |
| } | |
| $context->setGroups($groups); | |
| // ... lines 135 - 137 | |
| } | |
| } |
Go Deeper!
You could also use $request->query->getBoolean('deep') instead of get() to convert
the deep query parameter into a boolean. See accessing request data for other
useful methods.
And just like that, we're able to conditionally show fields. Sweet!
Re-run our test for testGETProgrammerDeep():
./bin/phpunit -c app --filter testGETProgrammer
It passes! To really prove it, refresh the browser. Nope, no user property. Now add ?deep=1 to the URL. That's a cool way to leverage groups.
Wow, nice work guys! We've just taken another huge chunk out of our API with pagination, filtering and a whole lot of cool serialization magic. Ok, now keep going with the next episode!
@weaverryan First, I'd love to say thank you because your tutorial is outstanding. The quality is just superb..
Quick question, you mention this violates REST.
If you have an entity Battle like in your example, would you return the id of the programmer in it only?
For example:
From what I understand OPTION 1 is not RESTful
OPTION 1:
{
"id": 12,
"programmer": {
"id": 1,
"nickname": "UnitTester",
"avatar": 3
}
}
But, OPTION 2 would be?
OPTION 2:
{
"id": 12,
"programmer": {
"id": 1
}
}
Or maybe OPTION 3?
OPTION 3:
{
"id": 12,
"programmer_id": 1
}
What would the best RESTful way to handle OneToMany(s) like this?
Thank you!