TP n°2 - Manipuler les données avec Doctrine
Programmer en PHP des modifications dans la base de données

Vous allez dupliquer l’arborescence du projet PHP obtenu à la fin de la séance précédente, pour travailler sur une nouvelle version.

Vous pourrez ainsi faire évoluer le code, et revenir en arrière si besoin, en comparant l’état à la fin de la séance prédente, avec l’état courant.

1. Effectuez les opérations suivantes pour dupliquer le dossier :

   cd "$HOME/CSC4101"
   cp -r tp-01 tp-02
   cd tp-02
   cd todo-app
   

2. Ensuite, dans ce nouveau projet, on va réinitialiser les rouages du cadriciel Symfony avec Composer :

   cd "$HOME/CSC4101/tp-02/todo-app"
   rm -fr composer.lock symfony.lock var/cache/ vendor/ .project
   symfony composer install
   

   Confirmez la génération de fichiers pour Docker (on ne s’en servira pas tout de suite, mais pourquoi ne pas les avoir… le rôle de Docker ne sera pas évoqué en cours, mais vous pouvez en parler à vos encadrants de TP).

Il est donc préférable de réinitialiser le projet radicalement : à un état le plus « propre » possible. On fait ensuite réinstaller par Composer les bibliothèques du cadriciel Symfony (installées dans vendor/), et reconfigurer certains fichiers de configuration associés.

Vous allez travailler sur un nouveau projet dans le workspace dans l’IDE Eclipse, importé depuis ce nouveau répertoire de travail.

1. Pour les utilisateurs de l’IDE Eclipse, supprimez les anciennes infos du projet Eclipse :

   cd "$HOME/CSC4101/tp-02/todo-app"
   rm -fr .project .settings/
   

2. Importez dans votre IDE cette nouvelle version du projet Symfony Todo sur laquelle vous allez maintenant travailler.

   Dans Eclipse vous pouvez importer ce nouveau projet dans le même workspace que le précédent, mais avec un nom distinctif (par exemple « todo-tp-2 »).

   Si besoin, vous pourrez comparer le code des deux projets « todo-tp-2 » et « todo-tp-1 ». Mais pour l’instant, et pour éviter de vous mélanger, nous vous conseillons de fermer le projet de la séance précédente (menu Project / Close …).

Sous le capot, Doctrine utilise des requêtes SQL SELECT pour le chargement des données.

Symfony, comme tous les frameworks, possède des fonctionnalités de debug (déverminage), avec entre autre la possibilité d’avoir des messages plus verbeux, des traces, etc. (en mode développement, au moins; cf. Troubleshooting Problems).

Ce genre d’éléments de diagnostic nous permet d’essayer de traverser les couches d’exécution des différents composants du cadriciel, pour comprendre ce qui se passe, et sans avoir à modifier le code.

On va regarder ici quelles requêtes SQL sont effectivement générées par le code PHP de notre application.

1. Exécutez une des commandes de l’application :

   symfony console app:list-todos
   

2. Ouvrez un autre terminal dans le même répertoire, et exécutez la commande suivante :

   cd "$HOME/CSC4101/tp-02/todo-app"
   tail -f var/log/dev.log
   

   La commande tail -f permet de consulter la fin d’un fichier et de surveiller les ajouts éventuels.

   Pour l’instant, elle affiche les dernières lignes présentes dans le fichier, générées lors de l’appel de la commande qu’on vient de faire.

3. Regardez les traces apparaissant dans le fichier var/log/dev.log au fur et à mesure de l’exécution de commandes.

   Nous nous intéressons aux messages doctrine.DEBUG (vous pouvez a priori ignorer le reste des messages *.info).

   Vous verrez apparaître les requêtes SELECT générées, par exemple ici pour un findAll() :

   [...] doctrine.DEBUG: Executing query:
     SELECT t0.id AS id_1, t0.title AS title_2, t0.completed AS completed_3, t0.created AS created_4,
         t0.updated AS updated_5
       FROM todo t0
       {"sql":"SELECT t0.id AS id_1, t0.title AS title_2, t0.completed AS completed_3, t0.created AS
                 created_4, t0.updated AS updated_5 FROM todo t0"} []
   

   Ici, la requête est « très simple » (une version extensive du SELECT *), mais en cas de problèmes, c’est bien pratique de comprendre d’où vient le problème : le code, ou les données.

On verra plus tard, quand on sera en mode Web, qu’on aura à notre disposition le même mécanisme de traces de ces requêtes, dans la barre d’outils de mise au point de Symfony qui sera disponible directement dans l’interface Web, sans avoir à lancer un terminal en parallèle.

Première option: modifier le code effectuant la requête, à l’intérieur de la méthode execute() de notre commande ListTodosCommand.

La requête est actuellement faite avec l’instruction de chargement des tâches $todos = $this->todoRepository->findAll(); qui se traduit par un SELECT *, comme on vient de le voir.

Par défaut, la requête est faite sans critère de tri des résultats (donc par défaut, triés dans l’ordre où ils ont été stockés dans la table SQLite).

On peut modifier cet appel pour utiliser plutôt la méthode findBy() en lui passant en second argument un critère de tri sur la valeur de la propriété completed.

1. Modifiez le code de ListTodosCommand::execute() dans votre IDE :

   protected function execute(InputInterface $input, OutputInterface $output): int
   {
       //...
   
       // fetches all instances of class Todo from the DB
       //$todos = $this->todoRepository->findAll();
       $todos = $this->todoRepository->findBy([],
                                              ['completed' => 'ASC']);
   
       //...
   }
   

   On examinera la syntaxe de l’appel à findBy() un peu plus tard.

2. Exécutez la commande app:list-todos

   Les tâches doivent apparaître dans l’ordre souhaité, non-plus triées par ordre d’identifiant, mais les tâches terminées à la fin.

3. Consultez les logs pour vérifier la requête SQL exécutée.

   Vous devez voir effectivement une spécification d’ORDER BY SQL, du type :

   [...] doctrine.DEBUG: Executing query:
         SELECT t0.id AS id_1, t0.title AS title_2, t0.completed AS completed_3, t0.created AS created_4,
            t0.updated AS updated_5
         FROM todo t0
         ORDER BY t0.completed ASC
         {"sql":"SELECT t0.id AS id_1, t0.title AS title_2, t0.completed AS completed_3, t0.created AS
                    created_4, t0.updated AS updated_5 FROM todo t0 ORDER BY t0.completed ASC"} []
   

   Pour le reste, la requête est identique à la précédente.

Deuxième option : modifier l’ensemble des requêtes de chargement des tâches, pas uniquement dans ListTodosCommand.

Pour cela, il suffit de modifier la classe TodoRepository, pour surcharger la méthode findAll() qu’elle hérite d’une classe parente.

Ainsi, on modifie globalement le comportement du chargement par défaut, avec un impact sur tout le code qui utilise la méthode findAll() du repository de la classe Todo.

1. Modifiez le code de la classe TodoRepository pour ajouter la méthode findAll().

   Vous pouvez par exemple coder ceci dans src/Repository/TodoRepository.php, pour redéfinir la méthode findAll() héritée :

   /**
    * {@inheritDoc}
    * @return Todo[]
    * @see \Doctrine\ORM\EntityRepository::findAll()
    */
   public function findAll(): array
   {
           //  findBy(array $criteria, array $orderBy = null, $limit = null, $offset = null)
           return $this->findBy(
                   [],
                   ['completed' => 'ASC']
           );
   }
   

   Même si le code source de TodoRepository.php a été généré initialement par les développeurs qui ont codé le squelette dont on est parti, on considère que maintenant que c’est dans src/, c’est notre code.

   On peut donc le modifier allègrement. On ne ferait pas ça sur le code de la bibliothèque de base de Doctrine qui est quelque part dans vendor/, au risque de perdre les modifications à la prochaine mise à jour faite par Composer.

   Notez que l’IDE nous indiquait qu’une méthode findAll() était déjà présente, bien qu’en fait, il n’y en ait aucun code présent dans TodoRepository.php. C’est dû au fait que qu’une docstring mentionne l’existence de cette méthode, au-dessus de la déclaration de la classe TodoRepository

   /**
    * @extends ServiceEntityRepository<Todo>
    *
    * [...]
    * @method Todo[]    findAll()
    */
   class TodoRepository extends ServiceEntityRepository
   {
   

   Comme la méthode existe bien en effet dans une classe parente du repository, cela permet à l’IDE nous propose de l’utiliser quand on utilise la complétion, par exemple. Pratique !

2. Supprimez le changement effectué précédamment dans ListTodosCommand::execute() pour remettre $todos = $this->todoRepository->findAll();
3. Vérifiez le comportement de app:list-todos, qui est bien impacté comme on le souhaite.
4. Vérifiez que la requête est inchangée en ce qui concerne l’ORDER-BY.

5. Lancez le serveur Web de l’environnement de tests locaux de Symfony avec symfony server:start et connectez-vous à l’interface Web de consultation des tâches sur la page /todo/list

   Les tâches sont également chargées dans le nouvel ordre souhaité.

   Les traces du serveur Web vous donnent aussi les informations de debug sur les requêtes SQL :

   DEBUG  | DOCTRI Executing query:
      SELECT t0.id AS id_1, t0.title AS title_2, t0.completed AS completed_3, t0.created AS created_4, t0.updated AS updated_5
      FROM todo t0
      ORDER BY t0.completed ASC
      sql="SELECT t0.id AS id_1, t0.title AS title_2, t0.completed AS completed_3, t0.created AS created_4, t0.updated AS updated_5 FROM todo t0 ORDER BY t0.completed ASC"
   

   Le comportement a bien changé de la même façon dans l’interface Web, et c’est bien logique puisque le code qui charge les données pour l’affichage dans la page Web, présent dans src/Controller/TodoController.php utilise :

   $todos = $entityManager->getRepository(Todo::class)->findAll();
   

Est-ce que le fait de redéfinir une méthode findAll() dans notre classe TodoRepository est une chose commune ?

Oui : dans un projet Symfony, on développe en objet.

Pour modifier un comportement par défaut, il faut penser objet : on fait ça via une redéfinition d’une méthode. Rien de spécifique à PHP, ou Symfony. On fait ça en Java, et dans tous les langages objets.

Ainsi on va redéfinir un comportement par défaut, en créant une classe dédiée dans notre code, qui redéfinira ce comportement hérité d’une classe parente.

L’ordre de tri par défaut de Doctrine est contrôlé dans le code du repository générique, tant qu’on n’ajoute pas de méthode findAll spécifique. Mais il peut ainsi être redéfini dans le code d’une classe Repository spécifique, qui surcharge cette classe de base générique.

C’est le rôle des classes présentes dans notre modèle de données dans src/Repository/.

En fait, dans certains projets on pourrait se passer de classes repository spécifiques dans notre modèle de données, à condition d’appliquer à différents endroits dans le code les findBy (comme dans la première option ci-dessus).

Mais autant factoriser plutôt que d’écrire du code identique un peu partout. Comme on l’a vu dans la deuxième option, c’est souvent pratique de changer l’ordre de chargement par défaut, une bonne fois pour toute.

On a aussi besoin de ce genre de factorisations pour réaliser des requêtes de jointures particulières.

Donc dans de vrais projets Symfony et Doctrine, on en arrive vite à créer ce genre de classes Repository spécialisées.

Tant et si bien que vous verrez que l’assistant générateur de code make:entity (qu’on va utiliser dans quelques temps) créera ainsi une classe Repository pour nous, à chaque fois qu’on ajoute une entité au modèle des données.

Allons maintenant examiner la documentation.

Et non, la bonne solution n’est pas de demander à ChatGPT !

Ouvrez la documentation relative à la gestion des données avec Doctrine dans Symfony : Databases and the Doctrine ORM

Vous pouvez parcourir rapidement le début de cette documentation.

Vous devriez néanmoins repérer du code similaire à celui de notre application fil-rouge, par exemple dans Fetching objects from the Database :

$repository = ...->getRepository(Product::class);

// look for a single Product by its primary key (usually "id")
$product = $repository->find($id);

// look for a single Product by name
$product = $repository->findOneBy(['name' => 'Keyboard']);
// or find by name and price
$product = $repository->findOneBy([
    'name' => 'Keyboard',
    'price' => 1999,
]);

// look for multiple Product objects matching the name, ordered by price
$products = $repository->findBy(
    ['name' => 'Keyboard'],
    ['price' => 'ASC']
);

// look for *all* Product objects
$products = $repository->findAll();

Espérons que cela vous paraît compréhensible.

Si on veut creuser un peu plus loin, il faut lire la doc du projet Doctrine lui-même.

Pour connaître toutes les variantes possibles pour faire des requêtes, cette documentation donne plus de détails sur le fonctionnement des repository d’entités : Documentation Doctrine ORM / Working with Objects / By Simple Conditions

Vous comprenez donc maintenant (peut-être) mieux le rôle des arguments qu’on a passé à findBy() dans les modifications du chargement des tâches pour les trier :

...->findBy([],
            ['completed' => 'ASC']);

1. premier argument attendu $criteria : C’est le critère de filtre du WHERE de la requête SQL.

   Ici un tableau vide : [], donc pas de filtre à appliquer;

2. deuxième argument (optionnel) $orderBy : ['completed' => 'ASC'].

   C’est le critère de tri qu’on recherche.

Que faire de toute cette documentation ? Le but est de savoir où elle est, et de s’y référer, autant que de besoin, et surtout sur la version qui nous concerne. C’est parfois un jeu de piste, et parfois la documentation manque… mais c’est souvent mieux que de suivre des posts random sur des forums.

Note: On touvera en annexe des détails sur comment se référer à la documentation ultime : le code des composants qu’on utilise.

Nous allons ajouter une nouvelle entité Tag pour gérer dans notre modèle de données des étiquettes qui pourront, plus tard, être liées aux tâches.

Commençons par l’ajout de l’entité Tag très simple, ayant une propriété name (une chaîne de caractères).

Lancez l’assistant make:entity, dans le terminal, depuis l’intérieur du projet Symfony. Il va nous servir à générer le code de classes PHP pour gérer notre entité « Tag ».

Répondez aux questions de l’assistant pour obtenir une interaction similaire à la trace présentée ci-dessous :

symfony console make:entity

Class name of the entity to create or update (e.g. GrumpyElephant):
> Tag

created: src/Entity/Tag.php
created: src/Repository/TagRepository.php

Entity generated! Now let's add some fields!
You can always add more fields later manually or by re-running this command.

New property name (press <return> to stop adding fields):
> name

Field type (enter ? to see all types) [string]:
> 

Field length [255]:
> 

Can this field be null in the database (nullable) (yes/no) [no]:
> 

updated: src/Entity/Tag.php

Add another property? Enter the property name (or press <return> to stop adding fields):
> 



 Success! 


Next: When you're ready, create a migration with symfony console make:migration

L’assistant a créé pour nous deux classes PHP qui utilisent Doctrine :

• src/Entity/Tag.php : gère les instances en mémoire des étiquettes
• src/Repository/TagRepository.php : gère le chargement des étiquettes depuis la base de donnée

Rafraîchissez votre projet dans l’IDE si nécessaire pour voir apparaître ces deux classes.

Procédez maintenant à la recréation du fichier de stockage de la base de données SQLite :

symfony console doctrine:database:drop --force
symfony console doctrine:database:create

Créez maintenant le schéma de la base de données :

symfony console doctrine:schema:create

Les tables et index correspondant aux classes de notre modèle de données sont créées. Les tables restent vides en attendant qu’on y ajoute des données.

On a déjà croisé le module DataFixtures de Symfony qui permet d’utiliser un outil de chargement de données de test, qui permettent aux développeurs de tester le code de leur modèle de données, en chargeant des données dans la base.

On va l’utiliser pour peupler la base de données avec des données d’étiquettes pour tester la classe Tag.

Effectuez les opérations suivantes :

1. Copiez-collez le code ci-dessous de façon à l’ajouter au contenu du fichier source src/DataFixtures/AppFixtures.php :

   private function loadTags(ObjectManager $manager)
   {
           foreach ($this->getTagsData() as [$name]) {
                   $todo = new Tag();
                   $todo->setName($name);
                   $manager->persist($todo);
           }
           $manager->flush();
   }
   
   private function getTagsData()
   {
           // tag = [name];
           yield ['important'];
           yield ['facile'];
           yield ['urgent'];
           yield ['seum'];
   }
   

2. Assurez-vous que toutes les déclarations sont correctes pour que l’ajout de ce code soit correct (l’IDE Eclipse vous donne des indices, en principe, s’il souligne des choses en rouge)
3. Assurez-vous de bien ajouter l’appel à cette nouvelle méthode loadTags() dans la méthode load() existante.

4. Lancez finalement le chargement des données de test :

   symfony console doctrine:fixtures:load -n
   

Attention, vous ne devez pas voir de message d’erreur, si tout a été bien cablé dans le code ci-dessus.

Si tout va bien à ce stade, votre modèle des données semble fonctionnel.

Voyons maintenant comment on fait pour ajouter des commandes permettant de tester le chargement depuis la base de données, comme les développeurs l’avaient fait avant nous pour app:list-todos, etc.

Ici aussi, on peut utiliser le générateur de code make:entity pour modifier le code PHP de nos entités existantes, et générer les propriétés des classes PHP correspondantes, avec la syntaxe des annotations Doctrine, de façon beaucoup plus simple qu’en éditant le code manuellement.

Dans les réponses au dialogue de l’assistant, on va ajouter une nouvelle propriété tags à notre entité Todo existante (make:entity sait générer du nouveau code, mais aussi modifier du code existant).

Cette propriété Todo::tags sera de type relation avec une autre entité existante, Tag, et avec une multiplicité ManyToMany. De façon réciproque, Tag recevra une nouvelle propriété todos (notez qu’on nomme nos propriétés avec un pluriel, pour matérialiser le fait qu’il y a plusieurs entités cible de l’association).

symfony console make:entity

 Class name of the entity to create or update (e.g. BravePopsicle):
 > Todo

 Your entity already exists! So let's add some new fields!

 New property name (press <return> to stop adding fields):
 > tags

 Field type (enter ? to see all types) [string]:
 > ?

Main Types
  ,* string
  ,* text
  ,* boolean
  ,* integer or smallint or bigint
  ,* float

Relationships/Associations
  ,* relation or a wizard 🧙 will help you build the relation
  ,* ManyToOne
  ,* OneToMany
  ,* ManyToMany
  ,* OneToOne

Array/Object Types
  ,* array or simple_array
  ,* json
  ,* object
  ,* binary
  ,* blob

Date/Time Types
  ,* datetime or datetime_immutable
  ,* datetimetz or datetimetz_immutable
  ,* date or date_immutable
  ,* time or time_immutable
  ,* dateinterval

Other Types
  ,* ascii_string
  ,* decimal
  ,* guid
  ,* uuid
  ,* ulid


 Field type (enter ? to see all types) [string]:
 > relation

 What class should this entity be related to?:
 > Tag

What type of relationship is this?
 ------------ ---------------------------------------------------------------- 
  Type         Description                                                     
 ------------ ---------------------------------------------------------------- 
  ManyToOne    Each Todo relates to (has) one Tag.                             
               Each Tag can relate to (can have) many Todo objects.            

  OneToMany    Each Todo can relate to (can have) many Tag objects.            
               Each Tag relates to (has) one Todo.                             

  ManyToMany   Each Todo can relate to (can have) many Tag objects.            
               Each Tag can also relate to (can also have) many Todo objects.  

  OneToOne     Each Todo relates to (has) exactly one Tag.                     
               Each Tag also relates to (has) exactly one Todo.                
 ------------ ---------------------------------------------------------------- 

 Relation type? [ManyToOne, OneToMany, ManyToMany, OneToOne]:
 > ManyToMany

 Do you want to add a new property to Tag so that you can access/update Todo objects from it
  - e.g. $tag->getTodos()? (yes/no) [yes]:
 > 

 A new property will also be added to the Tag class so that you can access the related Todo objects from it.

 New field name inside Tag [todos]:
 > 

 updated: src/Entity/Todo.php
 updated: src/Entity/Tag.php

 Add another property? Enter the property name (or press <return> to stop adding fields):
 > 



  Success! 


 Next: When you're ready, create a migration with symfony console make:migration

Rechargez le projet dans l’IDE pour voir apparaître le code modifié dans les classes PHP Todo et Tag (oui, même si nous avons demandé à modifier Todo, Tag a été impacté aussi : « Do you want to add a new property to Tag so that you can access/update Todo objects from it - e.g. $tag->getTodos()? (yes/no) [yes] »).

Sur le modèle des ajouts de commandes effectués précédemment, ajoutez une commande app:new-tag qui prend en argument le nom de l’étiquette, et va l’ajouter à la base de données.

Procédez aux étapes suivantes :

1. Vous utilisez encore une fois l’assistant make:command (une alternative pourrait être de copier-coller le code existant et faire les bons renommages).

2. Comme d’habitude, il nous faut cabler la commande avec le module Doctrine permettant d’intéragir avec la base de données, au moyen du Repository, et ajouter un constructeur adapté, quasi identique à ce qu’on a fait plus tôt sur ListTagsCommand :

   // ...
   
   use Doctrine\Persistence\ManagerRegistry;
   
   #[AsCommand(
           name: 'app:new-tag',
           description: 'Creates a new tag',
   )]
   class NewTagCommand extends Command
   {
           /**
            *  @var TagRepository data access repository
            */
           private $tagRepository;
   
           /**
            * Plugs the database to the command
            *
            * @param ManagerRegistry $doctrineManager
            */
           public function __construct(ManagerRegistry $doctrineManager)
           {
                   $this->tagRepository = $doctrineManager->getRepository(Tag::class);
   
                   parent::__construct();
           }
   
           // ...
   

3. Il ne reste plus qu’à coder le cœur de la commande dans la méthode execute() qui permettra d’ajouter des données dans la base, via le repository, comme c’est fait dans NewTodoCommand::execute() :

   //...
   use App\Entity\Tag;
   use App\Repository\TagRepository;
   
   //...
   
           protected function execute(InputInterface $input, OutputInterface $output): int
           {
                   $io = new SymfonyStyle($input, $output);
   
                   $tag = new Tag();
                   $tag->setName($input->getArgument('name'));
   
                   $this->tagRepository->save($tag, true);
   
                   if($tag->getId()) {        
                           $io->success('Created: '. $tag);
                           return Command::SUCCESS;
                   }
                   else {
                           $io->error('could not create tag!');
                           return Command::FAILURE;
                   }
           }
   
   
   

4. Réglez les derniers détails nécessaires à l’invocation de la commande (gestion des arguments attendus dans configure(), …), en vous inspirant du code présent dans les commandes existantes liés aux tâches.

5. In fine, quand vous testez, vous allez bloquer sur une erreur du type :

   In EntityRepository.php line 283:
   
     Undefined method "save". The method name must start with either findBy, findOneBy or countBy!  
   

   En effet, dans le code du repository des étiquettes, tel que généré par make:entity, il nous manque la méthode TagRepository::save(), et elle n’existe pas non-plus dans la bibliothèque Doctrine, comme nous le signale l’erreur.

   C’est normal, il s’agit là d’une amélioration du code qu’on peut faire pour le rendre plus lisible.

   Ajoutons la méthode save() à TagRepository, sur le modèle de celle fournie dans TodoRepository::save() :

   public function save(Tag $entity, bool $flush = false): void
   {
           $this->getEntityManager()->persist($entity);
   
           if ($flush) {
                   $this->getEntityManager()->flush();
           }
   }
   

   La documentation de Doctrine vous indiquera comment utiliser Doctrine pour sauvegarder des données : préparer la sauvegarde des entités modifiées avec persist(), puis lancer les requêtes de mise à jour vers la base de données avec flush().

   On reverra cela en cours en détails. Inutile de voir tout ça pour l’instant. Disons pour résumer qu’on préfère ajouter une méthode save() au repository, qui se charge de faire tout ça pour nous en un seul appel de méthode. Cela rend le code d’execute() plus lisible, désencombré des détails de Doctrine.

6. Une fois finalisé la méthode AddTagCommand::execute(), vérifiez que ça fonctionne et que vous voyez passer les requêtes SQL INSERT générées par Doctrine dans le fichier de logs.

symfony console cache:clear

Et rappelez-vous que l’IDE ne sait pas que des fichiers nouveaux sont générés par nos assistants générateurs de code Symfony, donc pensez à recharger le projet, si vous ne trouvez pas certains fichiers source.

Sur le modèle des portions de code précédentes, ajoutez une commande app:add-tag prenant en entrée deux arguments :

1. Utilisez make:command à nouveau pour générer le squelette de code dans src/Command/AddTagCommand.php

2. Adaptez ce squelette de base de la commande, pour qu’elle recoive deux arguments, et pour cabler l’utilisation de Doctrine :

   <?php
   
   namespace App\Command;
   
   use Symfony\Component\Console\Attribute\AsCommand;
   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputArgument;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Input\InputOption;
   use Symfony\Component\Console\Output\OutputInterface;
   use Symfony\Component\Console\Style\SymfonyStyle;
   use App\Entity\Tag;
   use App\Entity\Todo;
   use Doctrine\Persistence\ManagerRegistry;
   
   #[AsCommand(
           name: 'app:add-tag',
           description: 'Add a tag to a todo (both must exist already)',
   )]
   class AddTagCommand extends Command
   {
           /**
            *  @var ManagerRegistry data access repository
            */
           private $doctrineManager;
   
           /**
            * Plugs the database to the command
            *
            * @param ManagerRegistry $doctrineManager
            */
           public function __construct(ManagerRegistry $doctrineManager)
           {
                   $this->doctrineManager = $doctrineManager;
   
                   parent::__construct();
           }
   
           protected function configure(): void
           {
                   $this
                           ->addArgument('tagName', InputArgument::REQUIRED, 'Tag name')
                           ->addArgument('todoId', InputArgument::REQUIRED, 'Id of the todo')
                           ;
           }
   
           protected function execute(InputInterface $input, OutputInterface $output): int
           {
                   $io = new SymfonyStyle($input, $output);
                   $tagName = $input->getArgument('tagName');
                   $todoId = $input->getArgument('todoId');
   
                   dump($tagName);
                   dump($todoId);
   
                   // Do the work here :
                   // TODO 1. load tag and todo
                   // TODO 2. add tag to todo
                   // TODO 3. save changes to the database
   
                   return Command::SUCCESS;
           }
   }
   
   

   Contrairement aux codes des commandes précédentes, ici, on a gardé dans une propriété de la classe ($doctrineManager) la référence au gestionnaire doctrine, pour pouvoir accéder plus tard aux deux repositories respectifs des tâches et des étiquettes.

Ajoutons le chargement des données correspondant aux arguments tagName et todoId reçus par la commande.

Modifiez le code de execute() :

1. Dans un premier temps, on récupère les deux références aux repositories Doctrine de nos deux entités, grâce à la propriété $doctrineManager qu’on a gardé en mémoire dans le constructeur :

   protected function execute(InputInterface $input, OutputInterface $output): int
   {
   
           //...
   
           // Do the work here :
           // 1. load tag and todo
           $todoRepository = $this->doctrineManager->getRepository(Todo::class);
           $tagRepository = $this->doctrineManager->getRepository(Tag::class);
   
           // ...
   
   

2. On peut donc maintenant ajouter le chargement de la tâche choisie, passée via todoId.

   On charge la tâche (qui doit exister en base de données pour que la commande réussisse), avec la méthode find() du repository, qui charge une instance à partir de son identifiant (unique) :

   protected function execute(InputInterface $input, OutputInterface $output): int
   {
   
           //...
           $todo = $todoRepository->find($todoId);
           if(! $todo){
                   $io->error('could not find todo!');
                   return Command::FAILURE;
           }
   
           // ...
   
   

3. Pour le chargement de l’étiquette (qui doit elle-aussi exister préalablement), on n’a pas passé en argument de la commande un identifiant (numéro), mais une chaîne de caractères correspondant à une propriété de notre entité (name).

   On ne peut donc pas utiliser directement find(), mais on peut utiliser la méthode findOneBy() pour effectuer une requête de sélection par critère (SELECT ... WHERE ...).

   Elle effectue une requête de chargement d’une instance (findOne…) via une sélection, selon des couples clé-valeur passés en argument (un tableau associatif ['NOM_PROPRIETE1' => VALEUR_PROPRIETE1, ...], qui se traduit par les clauses WHERE correspondantes) :

   $tag = $tagRepository->findOneBy(['name' => $tagName]);
   

   Mais notez qu’on peut aussi utiliser une version alternative, en utilisant une méthode « magique » qui contient le nom de la propriété recherchée (écriture plus limpide sans tableau en argument) :

   $tag = $tagRepository->findOneByName($tagName);
   

Examinons maintenant ce qui se passe en mémoire dans l’exécution execute(), ce code utilisant Doctrine.

On peut mettre à profit l’outil dump() de Symfony, qui sera très puissant pour vous aider dans la mise au point du code.

Maintenant qu’on a les données en mémoire, complétez execute() pour afficher notre tâche et notre étiquette :

dump($todo);
dump($tag);

Vous remarquez, dans l’affichage des dump() ci-dessous :

• que notre tâche « apprendre les bases de PHP » (instance #359 de App\Entity\Todo) a une propriété tags qui est une PersistentCollection, qui ne semble rien contenir pour l’instant.
• de façon réciproque, notre étiquette « facile » a une collection de tâches todos pas beaucoup plus conséquente…

^ App\Entity\Todo^ {#359
  -id: 1
  -title: "apprendre les bases de PHP"
  -completed: true
  [...]
  -tags: Doctrine\ORM\PersistentCollection^ {#363
    #collection: Doctrine\Common\Collections\ArrayCollection^ {#442
      -elements: []
    }
    #initialized: false
    -snapshot: []
    -owner: App\Entity\Todo^ {#359}
    -association: array:20 [ …20]
    -em: ContainerOeMwtvh\EntityManagerGhostEbeb667^ {#267 …12}
    -backRefFieldName: "todos"
    -typeClass: Doctrine\ORM\Mapping\ClassMetadata {#357 …}
    -isDirty: false
  }
}
^ App\Entity\Tag^ {#1359
  -id: 2
  -name: "facile"
  -todos: Doctrine\ORM\PersistentCollection^ {#1368
    #collection: Doctrine\Common\Collections\ArrayCollection^ {#1369
      -elements: []
    }
    #initialized: false
    -snapshot: []
    -owner: App\Entity\Tag^ {#1359}
    -association: array:16 [ …16]
    -em: ContainerOeMwtvh\EntityManagerGhostEbeb667^ {#267 …12}
    -backRefFieldName: "tags"
    -typeClass: Doctrine\ORM\Mapping\ClassMetadata {#403 …}
    -isDirty: false
  }
}

Normal, on n’a pas encore associé la tâche et l’étiquette (on suppose que c’est la première exécution, et qu’il n’y avait pas d’association entre tâches et étiquettes, ayant été sauvegardées auparavant dans la base de données)

Il est temps d’ajouter l’étiquette à la tâche, en mémoire.

Plus précisément, on va ajouter l’étiquette qu’on a chargée depuis la base de donnée, dans la collection des étiquettes de la tâche.

Rien de plus compliqué qu’utiliser la méthode Todo::addTag(), qui est là pour cela.

Notez que Todo::addTag() a été ajoutée à notre code par make:entity, lors de l’ajout de l’association entre tâches et étiquettes.

1. Modifiez execute() en ajoutant ce code :

   //...
   
   // 2. add tag to todo
   $todo->addTag($tag);
   
   dump($todo);
   dump($tag);
   

2. Testez l’appel de la commande, et vérifiez le contenu avant/après de nos instances en mémoire dans l’affichage fait par dump().

   Cette fois, l’affichage des collections tags dans la Todo nous laisse bien apparaître le lien entre nos deux entités. La collection « #363 » contient un élément (le même « #1359 » d’id 2 et de name « facile » : la même référence en mémoire que notre objet $tag) :

   ^ App\Entity\Todo^ {#359
     -id: 1
     -title: "apprendre les bases de PHP"
     -completed: true
     [...]
     -tags: Doctrine\ORM\PersistentCollection^ {#363
       #collection: Doctrine\Common\Collections\ArrayCollection^ {#442
         -elements: array:1 [
           0 => App\Entity\Tag^ {#1359
             -id: 2
             -name: "facile"
             [...]
           }
         ]
       }
       #initialized: true
       -snapshot: []
       -owner: App\Entity\Todo^ {#359}
       -association: array:20 [ …20]
       -em: ContainerOeMwtvh\EntityManagerGhostEbeb667^ {#267 …12}
       -backRefFieldName: "todos"
       -typeClass: Doctrine\ORM\Mapping\ClassMetadata {#357 …}
       -isDirty: true
     }
   }
   ^ App\Entity\Tag^ {#1359
     -id: 2
     -name: "facile"
     -todos: Doctrine\ORM\PersistentCollection^ {#1368
       #collection: Doctrine\Common\Collections\ArrayCollection^ {#1369
       -elements: []
       }
       #initialized: true
       -snapshot: []
       -owner: App\Entity\Tag^ {#1359}
       -association: array:16 [ …16]
       -em: ContainerOeMwtvh\EntityManagerGhostEbeb667^ {#267 …12}
       -backRefFieldName: "tags"
       -typeClass: Doctrine\ORM\Mapping\ClassMetadata {#403 …}
       -isDirty: false
     }
   }
   

3. Vous voyez également qu’en mémoire, si notre tâche a son étiquette, par contre, l’étiquette semble ne pas connaître la tâche (dans la collection « #1369 » de sa propriété Tag::todos, qui ne contient pas d’éléments).

4. Modifions cela dans Todo::addTag(), en ajoutant $tag->addTodo($this);, pour obtenir :

   public function addTag(Tag $tag): static
   {
       if (!$this->tags->contains($tag)) {
           $this->tags->add($tag);
           // make sure the reverse reference is set too
           $tag->addTodo($this);
       }
   
       return $this;
   }
   

   La tâche ajoute l’étiquette dans sa collection d’étiquette tags, mais elle informe ensuite l’étiquette en question qu’elle a une nouvelle tâche associée (en lui passant sa propre référence $this).

   On voit bien qu’en mémoire, il s’agit de passer des références et de les mémoriser : les objets sont liés entre-eux par l’association.

5. Vérifiez enfin l’affichage de dump() à l’exécution après cette dernière modification.

   Le modèle en mémoire est cohérent : nos deux entités se référencent maintenant mutuellement (« #1369 » contient bien maintenant un élément, #359 : nos deux entités sont liées l’une à l’autre et réciproquement) :

   ^ App\Entity\Todo^ {#359
     -id: 1
     -title: "apprendre les bases de PHP"
     -completed: true
     [...]
     -tags: Doctrine\ORM\PersistentCollection^ {#363
       #collection: Doctrine\Common\Collections\ArrayCollection^ {#442
         -elements: array:1 [
           0 => App\Entity\Tag^ {#1359
             -id: 2
             -name: "facile"
             [...]
           }
         ]
       }
       #initialized: true
       -snapshot: []
       -owner: App\Entity\Todo^ {#359}
       -association: array:20 [ …20]
       -em: ContainerOeMwtvh\EntityManagerGhostEbeb667^ {#267 …12}
       -backRefFieldName: "todos"
       -typeClass: Doctrine\ORM\Mapping\ClassMetadata {#357 …}
       -isDirty: true
     }
   }
   ^ App\Entity\Tag^ {#1359
     -id: 2
     -name: "facile"
     -todos: Doctrine\ORM\PersistentCollection^ {#1368
       #collection: Doctrine\Common\Collections\ArrayCollection^ {#1369
         -elements: array:1 [
           0 => App\Entity\Todo^ {#359
             -id: 1
             -title: "apprendre les bases de PHP"
             -completed: true
             [...]
             }
           }
         ]
       }
       #initialized: true
       -snapshot: []
       -owner: App\Entity\Tag^ {#1359}
       -association: array:16 [ …16]
       -em: ContainerOeMwtvh\EntityManagerGhostEbeb667^ {#267 …12}
       -backRefFieldName: "tags"
       -typeClass: Doctrine\ORM\Mapping\ClassMetadata {#403 …}
       -isDirty: true
     }
   }
   

   En plus d’afficher de jolies couleurs, bien qu’il y ait un cycle dans nos données, dump() fait du bon boulot et ne part pas dans une boucle infinie ! Nice :-)

6. Lancez plusieurs fois de suite la même commande app:add-tag. Vous constatez que les modifications sont bien effectuées en mémoire, mais quand on recharge les données, les collections restent désespérément vides.

   Il manque finalement la persistance en base de données.

   Vérifiez dans les logs… vous ne devriez pas voir passer d’INSERT…

Dernier élément à coder dans execute(), faire en sorte que ces modifications soient sauvegardées en base de données.

On va devoir sauvegarder explicitement, dans notre code, en ajoutant l’appel à save() pour l’une des entités, par exemple $todo.

1. Modifiez enfin execute() pour ajouter la sauvegarde :

   protected function execute(InputInterface $input, OutputInterface $output): int
   {
       //...
   
       // 3. save changes to the database
       $todoRepository->save($todo, true);
   
       return Command::SUCCESS;
   }
   

2. Testez une nouvelle fois l’invocation de la même commande symfony console app:add-tag facile 1, en regardant les logs, et vérifiez que cela fonctionne bien : la requête SQL INSERT est bien transmise à la base SQLite.

   Les messages de traces de débug de Doctrine (doctrine.DEBUG) ressemblent à :

   Executing statement: SELECT t0.id AS id_1, t0.title AS title_2, t0.completed AS completed_3, t0.created
                               AS created_4, t0.updated AS updated_5
                        FROM todo t0
                        WHERE t0.id = ?
                        (parameters: array{"1":"1"}, types: array{"1":1})
   Executing statement: SELECT t0.id AS id_1, t0.name AS name_2
                        FROM tag t0
                        WHERE t0.name = ? LIMIT 1
                        (parameters: array{"1":"facile"}, types: array{"1":2})
   Executing statement: SELECT t0.id AS id_1, t0.name AS name_2
                        FROM tag t0
                        INNER JOIN todo_tag
                              ON t0.id = todo_tag.tag_id
                              WHERE todo_tag.todo_id = ?
                        (parameters: array{"1":1}, types: array{"1":1})
   Executing statement: SELECT t0.id AS id_1, t0.title AS title_2, t0.completed AS completed_3, t0.created
                               AS created_4, t0.updated AS updated_5
                        FROM todo t0
                        INNER JOIN todo_tag
                              ON t0.id = todo_tag.todo_id
                              WHERE todo_tag.tag_id = ? (parameters: array{"1":2}, types: array{"1":1})
   Beginning transaction 
   Executing statement: INSERT INTO todo_tag (todo_id, tag_id)
                        VALUES (?, ?) (parameters: array{"1":1,"2":2}, types: array{"1":1,"2":1})
   Committing transaction
   
   

   Explications des différentes instructions :

   1. chargement de la tâche par son numéro « 1 » (appel à find(), qui charge ici notre tâche d’id 1)
   2. chargement de l’étiquette par son nom « facile » (appel à findOneByName(), qui charge notre étiquette d’id 2, comme on l’avait vu dans les dumps)
   3. ensuite vient l’impact du addTag(), qui implique le chargement des étiquettes existantes de notre tâche (if (!$this->tags->contains($tag))), qui génère une jointure pour charger les étiquettes de la tâche (premier INNER JOIN avec la table de jointure créée dans la base pour gérer l’association M-N : todo_tag)
   4. de façon réciproque, chargement des tâches de l’étiquette (deuxième INNER JOIN sur la table d’association)
   5. enfin, il est temps de sauvegarder les données (persist() et flush() générés par l’appel à save()) :
      1. Doctrine crée une transaction pour assurer que les contraintes d’intégrité sont bien respectées (une application Symfony est typiquement multi-utilisateur, et il ne faut pas que les modifications concurrentes occasionnent des bugs)
      2. si tout va bien et qu’aucune autre exécution du code ne modifie la même table d’association, on peut alors créer le couple des identifiant de nos deux entités, via un INSERT dans la table d’association todo_tag.

On verra ultérieurement d’autres structures de données par exemple avec les associations 1-N OneToMany

Nous allons modifier l’affichage des tâches, qui existe déjà, pour ajouter aussi l’affichage des étiquettes de chaque tâche.

Comment allons-nous gérer cela en PHP ? En objet !

En base de données, les tâches et les étiquettes sont stockés dans des tables séparées (avec une table d’association pour matérialiser l’association M-N).

Comment se passe le chargement des données liées venant de tables séparées ? « Automagiquement » grâce à Doctrine.

Nous allons exploiter les méthodes d’accès aux propriétés multi-valuées, de type collection, fournies par l’API objet de Doctrine.

Si on accède à la propriété Todo::tags via $todo->getTags() (déjà introduit brièvement plus haut), on programme en objet tout naturellement… et Doctrine fera les chargements correspondants sous-le capot sans qu’on ait à s’en préoccuper (jointures, etc.).

Il n’est pas question d’avoir à coder par nous-même des choses affreuses comme : 1) charger en mémoire les tâches d’un côté, 2) puis les étiquettes de l’autre, 3) réconcilier ensuite « manuellement » quelles étiquettes correspondent à quel tâche… on n’est plus à l’ère préhistorique. L’ORM est là pour faire ça.

Mettons cela en pratique : vous allez ajoutez l’affichage des étiquettes de la tâche dans le code de la commande app:show-todo qui était fournie.

Pour réaliser l’affichage des étiquettes d’une tâche, vous pouvez vous inspirer du code ci-dessous. Observez la façon dont est écrit le foreach qui permet d’accéder aux données liées dans la collection des étiquettes de cette tâche :

protected function execute(InputInterface $input, OutputInterface $output)
{

    // [...]
    if ($todo) {
        dump($todo);
        $io->text($todo);

        $tags = $todo->getTags();
        if(count($tags)) {
            dump($tags);
            $io->text('tags:');
            foreach($tags as $tag) {
                $io->text('- '. $tag);
            }
        }
    }

    // [...]

À vous de jouer…

Normalement, c’est presque trop simple : tout est là.

Si ça fonctionne, vous verrez dans les logs les différentes requêtes SQL de chargement, dans les 3 tables concernées de la base de données.

Nous reviendrons dans une prochaine séquence de cours sur les aspects « automagiques » de ce chargement des données liées.

Dans la gestion des étiquettes, elles ont une seule propriété name dont on pourrait souhaiter que sa valeur soit unique (en effet, dans l’implémentation courante, rien n’empêche de stocker dans la base deux étiquettes de même nom).

On peut implémenter cette contrainte d’unicité à plusieurs niveaux :

• a minima dans la base de données (c’est le rôle du SGBD de garantir de façon ultime ce genre de contraines d’intégrité de notre modèle de données)

• de façon plus intéressante, via notre code applicatif.

  En effet, même si la base de données fait le job, on peut préférer détecter la violation de contrainte au plus tôt, en mémoire, dès la saisie des données entrantes dans l’application, sans attendre d’essayer de les sauver dans la base de données, et d’obtenir à ce moment là une erreur.

  Un mécanisme avancé de Symfony permet de faire cela : le Validator.

Examinons les deux options (qu’on peut combiner) :

Revenons à la modification du code de src/Repository/FilmRepository.php qu’on vous a proposée, pour ajouter une méthode findAll() en vue de modifier le tri effectué au chargement des données.