====== Sérialisation avec jms/serializer-bundle ======
===== Installation =====
<code>
D:\webprojects\test-api-project>composer require jms/serializer-bundle
Using version ^3.4 for jms/serializer-bundle
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
Restricting packages listed in "symfony/symfony" to "4.3.*"

Prefetching 16 packages 
  - Downloading (100%)  

Package operations: 16 installs, 0 updates, 0 removals
  - Installing hoa/exception (1.17.01.16): Loading from cache
  - Installing hoa/event (1.17.01.13): Loading from cache
  - Installing hoa/consistency (1.17.05.02): Loading from cache
  - Installing hoa/visitor (2.17.01.16): Loading from cache
  - Installing hoa/ustring (4.17.01.16): Loading from cache
  - Installing hoa/protocol (1.17.01.14): Loading from cache
  - Installing hoa/zformat (1.17.01.10): Loading from cache
  - Installing hoa/iterator (2.17.01.10): Loading from cache
  - Installing hoa/compiler (3.17.08.08): Loading from cache
  - Installing hoa/regex (1.17.01.13): Loading from cache
  - Installing hoa/math (1.17.05.16): Loading from cache
  - Installing hoa/stream (1.17.02.21): Loading from cache
  - Installing hoa/file (1.17.07.11): Loading from cache
  - Installing jms/metadata (2.1.0): Loading from cache
  - Installing jms/serializer (3.3.0): Loading from cache
  - Installing jms/serializer-bundle (3.4.1): Loading from cache
Writing lock file
Generating autoload files
ocramius/package-versions: Generating version class...
ocramius/package-versions: ...done generating version class
Symfony operations: 1 recipe (3bdaac2ac8821bc8af3d710ff51a1686)
  -  WARNING  jms/serializer-bundle (>=3.0): From github.com/symfony/recipes-contrib:master
    The recipe for this package comes from the "contrib" repository, which is open to community contributions.
    Review the recipe at https://github.com/symfony/recipes-contrib/tree/master/jms/serializer-bundle/3.0

    Do you want to execute this recipe?
    [y] Yes
    [n] No
    [a] Yes for all packages, only for the current installation session
    [p] Yes permanently, never ask again for this project
    (defaults to n): y
  - Configuring jms/serializer-bundle (>=3.0): From github.com/symfony/recipes-contrib:master
Executing script cache:clear [OK]
Executing script assets:install public [OK]

Some files may have been created or updated to configure your new packages.
Please review, edit and commit them: these files are yours.


</code>
===== Usage =====
==== Sérialiser un objet ====
Trois points important
  - Clause use : ''use **JMS\Serializer\SerializerInterface**;''
  - Injection : ''public function check(..., **SerializerInterface $serializer** )''
  - Sérialisation : ''$string  = **$serializer->serialize**($objet, 'json');''
<code php>
<?php
namespace App\Controller;
...
use JMS\Serializer\SerializerInterface;
...
class CheckVersionController extends AbstractController
{
     /**
      * @Route("/api/checkv", name="api_checkversion")
      */
    public function check(Request $request, SerializerInterface $serializer )
    {
       // Création d'un objet
        $proj = new Projects();
        $proj->setName('Test');
        
        // Sérialisation de l'Objet
        $data = $serializer->serialize($proj, 'json');

        // Envois de la réponse
        $response = new Response($data);
        $response->headers->set('Content-Type', 'application/json');
        return $response;
    }
}
</code>
==== Politique d'exclusion dans l'Entity ====
Avec les annotations directement dans le fichier de l'Entity on peut exclure des properties de la sérialisation.
<note important>Ne pas oublier d'inclure l'usage des annotations pour la sérialisation dans le fichier de l'Entity avec\\  ''use JMS\Serializer\Annotation as Serializer;''</note>
=== Tout Exclure ===
Avec l'annotation '' @Serializer\ExclusionPolicy("ALL")'' :
<code php  [enable_line_numbers="true",highlight_lines_extra="6,10"]>
<?php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use JMS\Serializer\Annotation as Serializer;

/**
 * @ORM\Entity(repositoryClass="App\Repository\ProjectsRepository")
 * @Serializer\ExclusionPolicy("ALL")
 */
class Projects
{
</code>
=== Exposer (inclure)  une propertie ===
Quand tout a été exclu on peut exposer certaines properties  avec l'annotation ''@Serializer\Expose'' (lignes 20 et 26) :
<code php [enable_line_numbers="true",highlight_lines_extra="3,7,20,26"]>
<?php
...
use JMS\Serializer\Annotation as Serializer;

/**
 * @ORM\Entity(repositoryClass="App\Repository\ProjectsRepository")
 * @Serializer\ExclusionPolicy("ALL")
 */
class Projects
{
    /**
     * @ORM\Id()
     * @ORM\GeneratedValue()
     * @ORM\Column(type="integer")
     */
    private $id;

    /**
     * @ORM\Column(type="string", length=40)
     * @Serializer\Expose
     */
    private $name;

    /**
     * @ORM\Column(type="string", length=255)
     * @Serializer\Expose
     */
    private $url;
</code>
==== Utiliser des groupes ====
On peut utiliser des groupes, voir l'annotation ''@Serializer\Groups({"group1", "group2"})''
<note important>Il ne faut pas utiliser les groupes en même temps que les annotation Exclude et Expose.</note>
=== Annotations dans le fichier de l'Entity ===
Pour chaque propertie on ajoute l'Annotation ''@Serializer\Groups({"Groupes d'appartenance"})'' 
<code php  [enable_line_numbers="true",highlight_lines_extra="4,15,21,27,33,39,45,51"]>
<?php
namespace App\Entity;
use Doctrine\ORM\Mapping as ORM;
use JMS\Serializer\Annotation as Serializer;

/**
 * @ORM\Entity(repositoryClass="App\Repository\ProjectsRepository")
 */
class Projects
{
    /**
     * @ORM\Id()
     * @ORM\GeneratedValue()
     * @ORM\Column(type="integer")
     * @Serializer\Groups({"all"})
     */
    private $id;

    /**
     * @ORM\Column(type="string", length=40)
     * @Serializer\Groups({"all"})
     */
    private $name;

    /**
     * @ORM\Column(type="string", length=255)
     * @Serializer\Groups({"all","version"})
     */
    private $url;

    /**
     * @ORM\Column(type="integer")
     * @Serializer\Groups({"all","version"})
     */
    private $vmaj;

    /**
     * @ORM\Column(type="integer")
     * @Serializer\Groups({"all","version"})
     */
    private $vmin;

    /**
     * @ORM\Column(type="integer")
     * @Serializer\Groups({"all","version"})
     */
    private $revision;

    /**
     * @ORM\Column(type="integer")
     * @Serializer\Groups({"all","version"})
     */
    private $construction;
    ...
</code>
=== Modification du Controller ===
  - (ligne 5) On rajoute la clause ''use JMS\Serializer\SerializationContext;''
  - (ligne 15) On rajoute le paramétre : ''SerializationContext::create()->setGroups(array('version'))'' a l'appel ''$serializer->serialize'', ou ''version'' est le nom du groupe que l'on veut voir sérialiser.
<code php  [enable_line_numbers="true",highlight_lines_extra="5,15"]>
<?php
namespace App\Controller;
...
use JMS\Serializer\SerializerInterface;
use JMS\Serializer\SerializationContext;
...
class CheckVersionController extends AbstractController
{
    /**
     * @Route("/api/checkv/{projName}", name="api_checkVersion", methods={"GET"})
     */
    public function check(Request $request, SerializerInterface $serializer, string $projName)
    {
        $proj = $this->getDoctrine()->getRepository('App:Projects')->findOneBy(['name' => $projName]);
        $data = $serializer->serialize($proj, 'json',SerializationContext::create()->setGroups(array('version')));

</code>
==== Autres Annotations ====
  * [[http://jmsyst.com/libs/serializer/master/reference/annotations]]

==== Utiliser les evenements ====
On  peut utiliser les evenements : 
  * **serializer.pre_serialize** : l'évènement est de type  ''JMS\Serializer\EventDispatcher\PreSerializeEvent'' et permet de changer le type de l'objet à sérialiser. Il est également possible d'accéder aux données de l'objet à sérialiser, ainsi qu'au visiteur (objet utilisé pour parcourir l'objet à sérialiser). 
  * **serializer.post_serialize** : l'évènement est de type  ''JMS\Serializer\EventDispatcher\ObjectEvent'' et permet de modifier le résultat de la sérialisation de l'objet.
  * **serializer.pre_deserialize** : l'évènement est de type  ''JMS\Serializer\EventDispatcher\PreDeserializeEvent'' et permet de modifier les données soumises à l'application et/ou modifier le type de l'objet à obtenir après désérialisation.
  * **serializer.post_deserialize** : l'évènement est de type  ''JMS\Serializer\EventDispatcher\ObjectEvent'' et permet de faire des manipulations sur l'objet désérialisé comme de la validation ou ajouter des informations à l'objet qui pourrait provenir d'un service (API) externe par exemple.


Plus d'infos : [[https://openclassrooms.com/fr/courses/4087036-construisez-une-api-rest-avec-symfony/4302366-allez-plus-loin-avec-jmsserializer#/id/r-4302459]]
==== Utiliser un Handler ====
C'est a dire créer un méthode qui sera appelée <<à la place>> de la méthode ''serialize'' ou ''deserialize''.\\
Ce qui laisse la maîtrise totale de la sérialisation ou dé-sérialisation...

Plus d'infos : [[https://openclassrooms.com/fr/courses/4087036-construisez-une-api-rest-avec-symfony/4302366-allez-plus-loin-avec-jmsserializer#/id/r-4302489]]
====== Voir aussi ======
  * [[https://symfony.com/doc/current/serializer.html|Doc officielle sur le sérialiseur inclus dans Symfony]]
  * [[prog:symfony:bundles:jms-serializer-bundle]]