Buy
Buy

Serialization Event Subscriber

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:

... 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:

... 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:

... 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:

... lines 1 - 21
'event' => 'serializer.post_serialize',
'method' => 'onPostSerialize',
... lines 24 - 30

Next, add format set to JSON:

... 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:

... 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:

... 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:

... 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.

Leave a comment!

  • 2018-09-05 weaverryan

    Hey Tim van der Zouwen!

    Ok, I might have some info for you, though I have almost zero experience with the Sonata libraries :).

    1) SonataMediaBundle itself comes with some serialization config that tells JMSSerializer how to serialize the Media entity: https://github.com/sonata-p.... That's great news! However, notice that every field is assigned a few groups like "sonata_api_read,sonata_api_write,sonata_search" for the "name" field. When you serialize, I believe you will need to include one of these groups so that these fields setup. I would add a new, optional 2nd $groups argument to the serialize() so that you can pass in a custom group (you'll also need to add a 3rd argument to createApiResponse() with this same argument).

    2) But, there is one other thing that is troubling me. You said:

    >Response from GET /api/joboffer/1
    >...
    >["image"]=>
    >object(stdClass)#6405 (0) {
    >}
    >...

    The weird part about this is the stdClass object. The image property should be a Media object - not an stdClass. I would double-check (by var_dump($jobOffer)) to make sure that this property is what you expect. I also found it strange that it printed this string "object(stdClass)#6405 (0) {" in ISON. That's not JSON - that's the result of var_dump(). What does the full JSON response look like? I think something else is not quite right...

    Cheers!

  • 2018-09-03 Tim van der Zouwen

    Hey Victor,

    I'm trying to serialize my JobOffer Entity just like Programmer in the tutorial. This is in my showAction in my jobOfferController.php:


    /**
    * @Route("/api/joboffers/{id}", name="api_joboffer_show")
    * @Method("GET")
    */
    public function showAction($id)
    {
    /**
    * @var JobOffer $jobOffer
    */
    $jobOffer = $this->getDoctrine()
    ->getRepository('AppBundle:JobOffer\JobOffer')
    ->findOneById($id);

    if(!$jobOffer)
    {
    throw $this->createNotFoundException('No job Offer found with ID: ' . $id);
    }

    $response = $this->createApiResponse($jobOffer);

    return $response;
    }

    The createApiResponse lives in my BaseController.php like in the tutorial:


    class BaseController extends Controller
    {
    protected function createApiResponse($data, $statusCode = 200)
    {
    $json = $this->serialize($data);

    return new Response($json, $statusCode, [
    'Content-Type' => 'application/json'
    ]);
    }

    protected function serialize($data)
    {
    $context = new SerializationContext();
    $context->setSerializeNull(true);

    $request = $this->get('request_stack')->getCurrentRequest();
    $groups = array("Default");

    if ($request->query->get('deep')){
    $groups[] = 'deep';
    }

    $context->setGroups($groups);

    return $this->container->get('jms_serializer')
    ->serialize($data, 'json', $context);
    }
    }

    For the image I use the Sonata Media Bundle (I have the same issue with the Sonata Classification Bundle)
    And I use a media.yml to configure it (config.yml imports: - { resource: Sonata/media.yml }) sonata_madia: ...
    Full configuration:
    https://sonata-project.org/...

    I hope this makes things more clear.

  • 2018-08-31 Victor Bocharsky

    Hey Tim,

    Hm, could you tell us to what exactly are you trying to serialize JobOffer? Are you trying to serialize JobOffer as JSON? And your response looks like a var_dump()' output. What code gives you this output? And how did you expose Media entity properties? As I understand this entity comes from third-party bundle, so you can't add annotation to it, right? Do you use some YAML/XML configuration for it?

    Cheers!

  • 2018-08-30 Tim van der Zouwen

    Hi,

    I don't know if this is the tutorial to ask this, but I have the following question.

    I have an Entity JobOffer. This Entity contains an image from the Sonata MediaBundle like this:

    Entity JobOffer
    ...
    /**
    * @Serializer\Expose()
    * @ORM\ManyToOne(targetEntity="Application\Sonata\MediaBundle\Entity\Media", cascade={"all"})
    */
    private $image;
    ...

    When I get the response I can see the property like this:

    Response from GET /api/joboffer/1
    ...
    ["image"]=>
    object(stdClass)#6405 (0) {
    }
    ...

    Unfortunately I'm not able to get the details like the name or reference of the Image.

    What do I have to change to get this information?

  • 2018-02-06 Paweł Chry

    thanks, (sorry, somehow I forgot it's not about Symfony The Serializer Component, and I searched there)

  • 2018-02-06 Victor Bocharsky

    Hi Pawel,

    AFAIK, it isn't. Probably you don't see it in the docs for bundle, try to look at docs for serializer package itself:
    https://jmsyst.com/libs/ser...

    Cheers!

  • 2018-02-06 Paweł Chry

    Hi, Is `@VirtualProperty` outdated? Can't find anything about that in documentation.