This tutorial has a new version, check it out!
> APIs > Symfony RESTful API: Basics++ (Course 3)
Buy Access to Course
06.

Serialization Event Subscriber

Share this awesome video!

|

Keep on Learning!

Start your All-Access Pass

With a Subscription, click any sentence in the script to jump to that part of the video!

Login Subscribe

I think the best part of doing API magic in Symfony is the serializer we've been using. We just give it objects - whether those are entities or something else - and it takes care of turning its properties into JSON. And we have control too: by using the exclusion policy and other annotations like @SerializedName that lets us control the JSON key a property becomes.

When does the Serializer Fail?

Heck, we can even add virtual properties! Just add a function inside your class, add the @VirtualProperty() annotation above it... and bam! You now have another field in your JSON response that's not actually a property on the class. That's great! It handles 100% of what we need! Right... right?

Ah, ok: there's still this last, nasty 1% of use-cases where virtual property won't work. Why? Well, imagine you want to include the URL to the programmer in its JSON representation. To make that URL, you need the router service. But can you access services from within a method in Programmer? No! We're in trouble!

This is usually where I get really mad and say "Never mind, I'm not using the stupid serializer anymore!" Then I stomp off to my bedroom to play video games.

But come on, we can definitely overcome this. In fact, there are two ways. The more interesting is with an event subscriber on the serializer.

Creating a Serializer Event Subscriber

In AppBundle, create a new directory called Serializer and put a fancy new class inside called LinkSerializationSubscriber. Set the namespace to AppBundle\Serializer:

13 lines | src/AppBundle/Serializer/LinkSerializationSubscriber.php
// ... lines 1 - 2
namespace AppBundle\Serializer;
use JMS\Serializer\EventDispatcher\EventSubscriberInterface;
class LinkSerializationSubscriber implements EventSubscriberInterface
{
// ... lines 9 - 11
}

To create a subscriber with the JMSSerializer, you need to implement EventSubscriberInterface... and make sure you choose the one from JMS\Serializer. There's also a core interface that, unfortunately, has the exact same name.

In PhpStorm, I'll open the Generate shortcut and select "Implement Methods". This will tell me all the methods that the interface requires. And, it's just one: getSubscribedEvents:

13 lines | src/AppBundle/Serializer/LinkSerializationSubscriber.php
// ... lines 1 - 6
class LinkSerializationSubscriber implements EventSubscriberInterface
{
public static function getSubscribedEvents()
{
}
}

Stop: here's the goal. Whenever we serialize something, there are a few events we can hook into to customize that process. In this method, we'll tell the serializer exactly which events we want to hook into. One of those will allow us to add a new field... which will be the URL to whatever Programmer is being serialized.

Return an array with another array inside: we'll need a few keys here. The first is event - the event name we need to hook into. There are two for serialization: serializer.pre_serialize and serializer.post_serialize:

30 lines | src/AppBundle/Serializer/LinkSerializationSubscriber.php
// ... lines 1 - 8
class LinkSerializationSubscriber implements EventSubscriberInterface
{
// ... lines 11 - 17
public static function getSubscribedEvents()
{
return array(
array(
'event' => 'serializer.post_serialize',
// ... lines 23 - 25
)
);
}
}

We need the second because it lets you change the data that's being turned into JSON.

Add a method key and set it to onPostSerialize - we'll create that in a second:

30 lines | src/AppBundle/Serializer/LinkSerializationSubscriber.php
// ... lines 1 - 21
'event' => 'serializer.post_serialize',
'method' => 'onPostSerialize',
// ... lines 24 - 30

Next, add format set to JSON:

30 lines | src/AppBundle/Serializer/LinkSerializationSubscriber.php
// ... lines 1 - 21
'event' => 'serializer.post_serialize',
'method' => 'onPostSerialize',
'format' => 'json',
// ... lines 25 - 30

This means the method will only be called when we're serializing into JSON... which is fine - that's all our API does.

Finally, add a class key set to AppBundle\Entity\Programmer:

30 lines | src/AppBundle/Serializer/LinkSerializationSubscriber.php
// ... lines 1 - 21
'event' => 'serializer.post_serialize',
'method' => 'onPostSerialize',
'format' => 'json',
'class' => 'AppBundle\Entity\Programmer'
// ... lines 26 - 30

This says, "Hey! Only call onPostSerialize for Programmer classes!".

Adding a Custom Serialized Field

Setup, done! Create that public function onPostSerialize(). Just like with core Symfony events, you'll be passed an event argument, which in this case is an instance of ObjectEvent:

30 lines | src/AppBundle/Serializer/LinkSerializationSubscriber.php
// ... lines 1 - 8
class LinkSerializationSubscriber implements EventSubscriberInterface
{
public function onPostSerialize(ObjectEvent $event)
{
// ... lines 13 - 15
}
// ... lines 17 - 28
}

Now, we can start messing with the serialization process.

Before we go any further, go back to our test. The goal is for each Programmer to have a new field that is a link to itself. In testGETProgrammer(), add a new assert that checks that we have a uri property that's equal to /api/programmers/UnitTester:

229 lines | src/AppBundle/Tests/Controller/Api/ProgrammerControllerTest.php
// ... lines 1 - 5
class ProgrammerControllerTest extends ApiTestCase
{
// ... lines 8 - 35
public function testGETProgrammer()
{
// ... lines 38 - 51
$this->asserter()->assertResponsePropertyEquals($response, 'uri', '/api/programmers/UnitTester');
}
// ... lines 54 - 227
}

Ok, let's see how we can use the fancy subscriber to add this field automatically.