Écriture d’une application avec interface ligne de commande « mini-allociné »
Application PHP en ligne de commande « Mini-Allociné »

Les étudiants vont enchaîner une vingtaine d’opérations permettant de se familiariser avec les outils du quadriciel Symfony et les fonctionnalités du composant Doctrine.

N’hésitez pas à prendre des notes dans un fichier que vous conservez d’une séance à l’autre.

Cette séquence de travail permet de travailler sur 4 grands domaines :

1. Création d’un projet Symfony
2. Mise en place d’un modèle de données objet via des classes PHP basées sur Doctrine
3. Chargement des données de la base
4. Gestion de la persistence des objets dans la base de données

Les composants liés au Web seront abordés par la suite. Pour l’instant en reste encore en local en ligne de commande.

On considère que vous avez acquis les notions de base sur la syntaxe du langage PHP, dans la séquence de Travail en Autonomie qui précède cette séance.

Du point de vue théorique, cette séance revisite principalement les acquis des cours d’informatique de l’année passée, sur le modèle objet et les bases de données relationnelles.

Le présent support de séance de TP est consultable via une mise en forme avec l’habillage org-html-themes, qui permet de masquer/révéler les différentes sections du support.

Des raccourcis clavier (indiqués dans un cartouche en bas à droite) permettent de naviguer directement dans les différentes tâches (TODO) à réaliser, pour aider à se concentrer sur l’avancement pas-à-pas.

On verra plus tard dans le cours comment les technologies autour de CSS et Javascript permettent de faire fonctionner ce genre de changements d’aspect dans un document HTML.

Vous allez utiliser la commande new de l’outil Symfony en ligne de commande (Symfony CLI), qui va créer le répertoire de développement d’une application Symfony et y télécharger le code source d’un squelette d’application.

Sous le capot, cette commande s’appuie sur le gestionnaire de paquetages PHP Composer.

Exécutez les commandes suivantes :

mkdir $HOME/CSC4101/tp-mini-allocine/
cd $HOME/CSC4101/tp-mini-allocine/
symfony --debug new --no-git miniallocine --version=lts

Creating a new Symfony 6.4 project with Composer

...

 [OK] Your project is now ready in /.../tp-mini-allocine/miniallocine

Vérifiez le contenu du répertoire miniallocine du projet Symfony qui vient d’être créé.

ls miniallocine/

Pour l’instant, repérez les éléments principaux qui vont nous intéresser :

bin/  composer.json  composer.lock  config/  public/  src/  symfony.lock  var/  vendor/

composer.json

descriptif du projet Composer de l’application Symfony. Il référence notamment les bibliothèques PHP utilisées;

Vous pouvez consulter son contenu dans un éditeur de textes (format JSON). Au cours de la vie du projet Symfony on pourra utiliser Composer pour y ajouter des dépendances du projet pour effectuer le téléchargement des bibliothèques de développement additionnelles dont on aura besoin.

bin/console

script exécutable PHP présent dans le sous-répertoire bin/, utilisé en ligne de commande pour le développement Symfony derrière les appels à symfony console;

src/

sources du squelette d’application Symfony. Il contient le code PHP de base de l’application sur laquelle vous travaillerez par la suite;

var/

répertoire dans lequel Symfony gère une partie de sa machinerie, avec notamment le cache de pré-compilation des bibliothèques PHP

vendor/

contient le code de toutes les bibliothèques PHP du framework Symfony qui seront utilisées. Elles ont été téléchargées par composer.

Nous aurons besoin de différents modules pour permettre à l’application de fonctionner, ou pour nous aider dans le prototypage de cette application :

Doctrine

le composant d’accès à la base de données via des objets PHP

le « Maker bundle »

qui va nous permettre de générer du code PHP plutôt que d’avoir à tout coder à la main

les « DataFixtures »

qui permettent de charger automatiquement des données de test dans la base de données

Procédez à l’installation avec les commandes suivantes à l’intérieur du répertoire miniallocine :

cd miniallocine/

• Gestionnaire de logs monolog

  symfony composer require symfony/monolog-bundle
  

• ORM Doctrine :

  symfony composer require symfony/orm-pack
  

  Validez l’exécution à la question posée par l’assistant (« y »)

• « Maker bundle » :

  symfony composer require --dev symfony/maker-bundle
  

• DataFixtures :

  symfony composer require --dev doctrine/doctrine-fixtures-bundle
  

Composer a téléchargé et extrait les différentes bibliothèques PHP pour Symfony. On va donc pouvoir les utiliser dans notre code.

Vous pouvez alors charger les sources du projet dans votre IDE PHP (que vous avez installé dans la séquence de travail hors-présentiel précédente).

Comme dans l’application Java du Mini-Allociné de CSC3101, on souhaite gérer des Films et leurs Recommendations.

Dans notre application, on va gérer ces éléments aussi bien dans la base de données relationnelle, qui stockera les données entre deux exécutions de notre programme, qu’en mémoire durant l’exécution du programme PHP objet.

On va donc gérer les structures de données en s’appuyant :

• sur le modèle relationnel (étudié en CSC3601), pour le stockage dans la base de données.
• sur le modèle objet (étudié en CSC3101), pour la représentation en mémoire.

En base de données, on aura donc deux relations :

• Film
• Recommendation

Les deux seront liées par une association 1-n : « un film a plusieurs recommendations / une recommendation porte sur un film ». Une clé étrangère permettra donc d’enregistrer, dans la table des recommendations, l’identifiant du film sur lequel elle porte.

Du côté objet en mémoire, on utilisera ici la bibliothèque PHP Doctrine, qui est un ORM (Object Relational Mapper).

Le rôle de l’ORM (Object Relational Mapper) est de permettre la gestion de collections d’objets, d’associations entre entités, et de fournir le chargement/sauvegarde des objets depuis la base de données.

On reviendra plus en détail sur Doctrine dans les séquences de cours qui suivent.

Pour faire court, le principe de l’ORM est de convertir chaque instance d’une relation (chaque ligne d’une table de la base de données) en instance d’une classe PHP en mémoire, et inversement. Doctrine appelle Entité ces classes d’objets.

Le programmeur peut ainsi écrire des classes PHP utilisant les fonctionnalités de Doctrine, et ainsi gérer des instances des entités, ou des collections d’entités. Quand deux entités sont liées (association 1-n, par exemple), des fonctions permettent de gérer cette association « OneToMany » et d’accéder à la collection des entités liées facilement.

Pour nous faciliter la tâche, nous allons utiliser un assistant de génération de code (du Maker bundler Symfony). Il va nous permettre d’ajouter dans le code source PHP une entité au modèle des données de l’application, en répondant simplement à une série de questions. Cela va nous éviter d’avoir à écrire le code PHP correspondant (mais on pourra toujours le modifier plus tard, comme si c’est nous qui l’avions écrit « à la main »).

Symfony gère la notion d’environnements ayant différentes configurations au sein d’un même projet : développement, tests, production.

Nous sommes actuellement en phase de développement, en local sur notre machine, avec déjà pas mal d’outils pour tester notre code. Dans l’environnement de développement et de mise au point correspondant (dev), vous utiliserez le SGBD SQLite qui sera suffisant pour nos besoins (SQLite stocke une base de données dans un fichier et permet de faire des requêtes SQL sur son contenu).

Modifiez le fichier (caché) .env présent à la racine du projet, qui définit des variables d’environnement, comme les paramètres d’accès à la base de données.

1. Chargez le le fichier .env dans l’IDE

   Attention, c’est un fichier caché… il faut éventuellement le faire apparaître dans l’IDE.

2. Dans ce fichier .env, modifiez la valeur de la variable DATABASE_URL pour prendre la valeur :

   DATABASE_URL=sqlite:///%kernel.project_dir%/var/data.db
   

   a priori, il suffit de commenter la ligne présente par défaut (qui propose d’utiliser PostGreSQL), et de décommenter celle pour SQLite, un peu au-dessus.

Ainsi, la base de données SQLite pourra être créée dans le fichier local $HOME/CSC4101/tp-mini-allocine/miniallocine/var/data.db.

Commençons par l’ajout de l’entité Film ayant deux propriétés title (titre du film) et year (année de sortie).

On va utiliser l’assistant Symfony make:entity, dans le terminal, depuis l’intérieur du projet Symfony. Il va nous servir à générer le code d’une classe PHP pour gérer notre entité « Film ».

Lancez la commande suivante, et 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. TinyElephant):
 > Film

 created: src/Entity/Film.php
 created: src/Repository/FilmRepository.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):
 > title

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

 Field length [255]:
 > 

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

 updated: src/Entity/Film.php

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

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

Main types
  * string
  * text
  * boolean
  * integer (or smallint, bigint)
  * float

Relationships / Associations
  * relation (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
  * json_array
  * decimal
  * guid


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

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

 updated: src/Entity/Film.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 make:migration

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

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

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

De façon similaire, on peut utiliser le générateur de code make:entity pour ajouter une entité Recommendation, qui ne comporte qu’une propriété recommendation pour le moment.

Mais cette fois, l’assistant va nous permettre de déclarer qu’on souhaite ajouter également la gestion d’une association entre notre entité Recommendation et l’entité Film existante.

Cette association sera matérialisée par la propriété film de la classe Recommendation (Recommendation::film), de type relation et de multiplicité ManyToOne. Recommendation::film sera une référence au film sur lequel porte une recommendation (plusieurs recommendations portent sur le même film : « many recommendations to one film »).

Lancez à nouveau la commande suivante, et 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. BraveKangaroo):
 > Recommendation

 created: src/Entity/Recommendation.php
 created: src/Repository/RecommendationRepository.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):
 > recommendation

 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/Recommendation.php

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

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

Main types
  * string
  * text
  * boolean
  * integer (or smallint, bigint)
  * float

Relationships / Associations
  * relation (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
  * json_array
  * decimal
  * guid


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

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

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

  OneToMany    Each Recommendation can relate to (can have) many Film objects.           
               Each Film relates to (has) one Recommendation                             

  ManyToMany   Each Recommendation can relate to (can have) many Film objects.           
               Each Film can also relate to (can also have) many Recommendation objects  

  OneToOne     Each Recommendation relates to (has) exactly one Film.                    
               Each Film also relates to (has) exactly one Recommendation.               
 ------------ -------------------------------------------------------------------------- 

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

 Is the Recommendation.film property allowed to be null (nullable)? (yes/no) [yes]:
 > no	

 Do you want to add a new property to Film so that you can access/update Recommendation objects from it
  - e.g. $film->getRecommendations()? (yes/no) [yes]:
 > 

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

 New field name inside Film [recommendations]:
 > 

 Do you want to activate orphanRemoval on your relationship?
 A Recommendation is "orphaned" when it is removed from its related Film.
 e.g. $film->removeRecommendation($recommendation)

 NOTE: If a Recommendation may *change* from one Film to another, answer "no".

 Do you want to automatically delete orphaned App\Entity\Recommendation objects (orphanRemoval)? (yes/no) [no]:
 > yes

 updated: src/Entity/Recommendation.php
 updated: src/Entity/Film.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 make:migration

Notez que l’assistant nous demande Do you want to add a new property to Film so that you can access/update Recommendation objects from it. Comme nous avons validé l’option par défaut yes, il génère une propriété « inverse » pour notre association ManyToOne, dans la classe Film, qu’il nomme recommendations (notez le « s » à la fin). Elle permettra d’accéder à la collection des recommendations d’un film.

Quant à la déclaration du paramètre orphanRemoval, elle permet de gérer le fait qu’un film est une entité maître dans la relation, et que les recommendations sans film n’ont pas lieu d’exister (on reverra cela plus tard).

Rechargez si nécessaire le projet dans l’IDE pour voir apparaître le code des nouvelles classes PHP :

• src/Entity/Recommendation.php
• src/Repository/RecommendationRepository.php

mais aussi les modifications effectuées dans src/Entity/Film.php

Sans surprise, la classe Film du modèle de données comporte deux propriétés primaires (mono-valuées) : title et year (et leurs getters et setters), mais aussi une propriété id nécessaire au mapping avec les entités de la base de données (la valeur de la clé primaire de la table SQL).

Procédez maintenant à la cré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

Le schéma de notre base de données a été créé par Doctrine à partir des directives de notre code PHP objet.

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.

Le module DataFixtures de Symfony permet d’utiliser dans le code des mécanismes chargement de données de test. Cela permet aux développeurs de tester le code de leur modèle de données, en local, en chargeant des données dans la base SQLite.

On va donc l’utiliser pour peupler la base de données avec des données de films ou de recommendations (qui vous rappelleront quelques souvenirs).

Une classe AppFixtures a été générée par Composer au moment de l’ajout du module DataFixtures au projet. Nous n’avons plus qu’à compléter le code de cette classe.

Copiez-collez le code ci-dessous de façon à remplacer le contenu du fichier source src/DataFixtures/AppFixtures.php.

Les commentaires dans le source devraient vous permettre de facilement identifier la nature des données chargées dans la base, même si on utilise des mécanismes pas forcément limpides aujourd’hui (générateurs avec l’instruction PHP yield).

Le cœur de l’opération se passe dans les instructions suivantes (de façon similaire à ce qu’on aurait fait en Java) :

1. création d’instances en mémoire (crées avec new Film(), ou new Recommendation())
2. appels aux méthodes setters des propriétés pour initialiser les données mono-valuées
3. ajout des nouvelles instances de Recommendation dans la collection des recommendations du film correspondant.

On étudiera plus tard persist() et flush() sont des méthodes du gestionnaire de données Doctrine, et qui ont pour effet de sauvegarder les données présentes en mémoire dans la base.

<?php

namespace App\DataFixtures;

use App\Entity\Film;
use App\Repository\FilmRepository;
use Doctrine\Bundle\FixturesBundle\Fixture;
use Doctrine\Persistence\ObjectManager;
use App\Entity\Recommendation;

class AppFixtures extends Fixture
{
        /**
         * Generates initialization data for films : [title, year]
         * @return \\Generator
         */
        private static function filmsDataGenerator()
        {
                yield ["Evil Dead", 1981];
                yield ["Evil Dead", 2013];
                yield ["Fanfan la Tulipe", 2003];
                yield ["Fanfan la Tulipe", 1952];
                yield ["Mary a tout prix", 1998];
                yield ["Black Sheep", 2008];
                yield ["Le Monde de Nemo", 2003];
        }

        /**
         * Generates initialization data for film recommendations:
         *  [film_title, film_year, recommendation]
         * @return \\Generator
         */
        private static function filmRecommendationsGenerator()
        {
                yield ["Evil Dead", 1981, "Ouh ! Mais ça fait peur !"];
                yield ["Evil Dead", 2013, "Même pas peur !"];
                yield ["Evil Dead", 2013, "Insipide et sans saveur"];
                yield ["Fanfan la Tulipe", 1952, "Manque de couleurs"];
                yield ["Fanfan la Tulipe", 1952, "Super scènes de combat"];
                yield ["Fanfan la Tulipe", 2003, "Mais pourquoi ???"];
                yield ["Mary a tout prix", 1998, "Le meilleur film de tous les temps"];
                yield ["Black Sheep", 2008, "Un scenario de génie"];
                yield ["Black Sheep", 2008, "Une réalisation parfaite"];
                yield ["Black Sheep", 2008, "À quand Black Goat ?"];  
        }

        public function load(ObjectManager $manager)
        {
                $filmRepo = $manager->getRepository(Film::class);

                foreach (self::filmsDataGenerator() as [$title, $year] ) {
                        $film = new Film();
                        $film->setTitle($title);
                        $film->setYear($year);
                        $manager->persist($film);          
                }
                $manager->flush();

                foreach (self::filmRecommendationsGenerator() as [$title, $year, $recommendation])
                {
                        $film = $filmRepo->findOneBy(['title' => $title, 'year' => $year]);
                        $reco = new Recommendation();
                        $reco->setRecommendation($recommendation);
                        $film->addRecommendation($reco);
                        // there's a cascade persist on film-recommendations which avoids persisting down the relation
                        $manager->persist($film);
                }
                $manager->flush();
        }
}

Sauvegardez cette modification, et testez l’exécution du chargement des données de test :

symfony console doctrine:fixtures:load -n

En principe, à ce stade, la commande affiche des erreurs (attendues) du type :

In ORMInvalidArgumentException.php line 105:

  Multiple non-persisted new entities were found through the given
  association graph:

  * A new entity was found through the relationship
  'App\Entity\Film#recommendations' that was not configured to cascade
  persist operations for entity:
  App\Entity\Recommendation@000000003e5fd2a800000 0003284ac56.

  To solve this issue: Either explicitly call EntityManager#persist() on
  this unknown entity or configure cascade persist this association in
  the mapping for example @ManyToOne(..,cascade ={"persist"}).

  If you cannot find out which entity causes the problem implement
  'App\Entity\Recommendation#__toString()' to get a clue.

Les assistants générateur de code nous facilitent beaucoup le travail, mais ils ne font quand même pas tout à notre place.

Le problème qui se pose est que l’assistant générateur de code make:entity n’a pas pu prendre toutes les décisions nécessaires, pour l’association 1-N qui lie les entités Film et Recommendation comme nous le souhaiterions. Il y a un problème de propagation en cascade des ajouts de données.

On va corriger ce problème dans l’étape suivante.

Ne vous inquiétez pas, nous reverrons en détail tous ces éléments dans les séquences suivantes du cours, mais pour l’instant, suivez le présent support : on n’est plus très loin du but !

Appliquons la suggestion donnée par le message d’erreur ci-dessus.

Ajoutez cascade: ["persist"] dans les options de l’attribut PHP #[ORM\OneToMany] qui décore Film::recommendations, dans le fichier source src/Entity/Film.php. Le code devient :

#[ORM\OneToMany(targetEntity: Recommendation::class, mappedBy: 'film', orphanRemoval: true, cascade: ["persist"])]
private Collection $recommendations;

Relancez le chargement des données de test, qui va marcher, cette fois :

symfony console doctrine:fixtures:load -n

   > purging database
   > loading App\DataFixtures\AppFixtures

Il n’y a plus qu’à vérifier le contenu de la base de données SQLite présente dans notre projet (dans var/data.db), avec un peu de SQL :

symfony console dbal:run-sql 'SELECT * FROM film'

Idem pour la table recommendation :

symfony console dbal:run-sql 'SELECT * FROM recommendation where film_id=2'

Cette fois encore, utilisons un assistant générateur de code pour nous faciliter le travail :

symfony console make:command

Choose a command name (e.g. app:orange-pizza):
> app:list-films

created: src/Command/ListFilmsCommand.php


 Success! 


Next: open your new command class and customize it!
Find the documentation at https://symfony.com/doc/current/console.html

Consultez le résultat généré dans src/Command/ListFilmsCommand.php

Vérifiez que la commande est bien disponible via :

symfony console list app

et :

symfony console app:list-films --help

Et enfin qu’elle répond quand on l’invoque :

$ symfony console app:list-films

                                                                                                                        
 [OK] You have a new command! Now make it your own! Pass --help to see your options.                                    
                                                                                                                        

Pour que notre commande puisse afficher la liste des films on va devoir réaliser quelques branchements utiles.

Modifiez le code de src/Command/ListFilmsCommand.php, pour ajouter une propriété filmRepository dans la classe ListFilmsCommand, permettant de gérer l’accès à la base de données via le composant Doctrine, et son initialisation.

Copiez-collez les éléments ci-dessous pour ajouter la propriété et le constructeur dans ListFilmsCommand (attention à ne pas dupliquer la déclaration de la classe, et à ne pas oublier les use) :

// ...

use App\Entity\Film;
use App\Repository\FilmRepository;
use Doctrine\Persistence\ManagerRegistry;

// ...

class ListFilmsCommand extends Command
{
    private ?FilmRepository $filmRepository;

    public function __construct(ManagerRegistry $doctrineManager)
    {
        $this->filmRepository = $doctrineManager->getRepository(Film::class);

        parent::__construct();
    }

    //...

Ce repository $filmRepository permet désormais de charger des instances d’objets de Film à partir de la base de données.

C’est le repository Doctrine pour la classe Film obtenu via getRepository(Film::class). Ce repository est en fait une classe qui a été générée par l’asssistant make:entity que nous avions lancée un peu plus tôt (« created: src/Repository/FilmRepository.php »)

Ajoutons maintenant dans la commande le code permettant de charger tous les films présents dans la base de données.

On utilise la méthode findAll() du repository Doctrine des films, qui renvoie un tableau de films. On peut manipuler ce tableau comme un tableau PHP ordinaire, par exemple avec foreach.

Modifiez la méthode execute() de ListFilmsCommand :

protected function execute(InputInterface $input, OutputInterface $output): int
{
    $io = new SymfonyStyle($input, $output);

    $films = $this->filmRepository->findAll();
    if (! $films) {
        $io->error('no films found!');
        return Command::FAILURE;
    } else {
        $io->title('list of films:');

        foreach ($films as $film) {
            $io->text($film);
        }

        return Command::SUCCESS;
    }
}

Testez avec :

symfony console app:list-films

Le programme échoue avec une erreur (attendue) du type :

$ symfony console app:list-films

list of films:
==============


In SymfonyStyle.php line 116:

  Symfony\Component\Console\Style\SymfonyStyle::text(): Argument #1 ($message) must be of type array|string,
  App\Entity\Film given,
  called in /.../miniallocine/src/Command/ListFilmsCommand.php on line 51                                                                                                                    


app:list-films [--option1] [--] [<arg1>]

Ce genre de chose devrait vous paraître cohérent avec ce qui a été vu l’année passée en programmation orientée objet.

La méthode text() essaie d’afficher une chaîne de caractères sur la console… mais une instance de la classe Film peut-elle être convertie en chaîne de caractères ? Pas de base, en PHP.

Réglons cela.

Ajoutez dans src/Entity/Film.php la méthode de conversion de film en chaîne de caractère qui nous manque : Film::__toString(), par exemple :

public function __toString() {
    return $this->getTitle() . " (" . $this->getYear() . ")";
}

Ré-essayez le lancement de notre commande :

$ symfony console app:list-films

list of films:
==============

 Evil Dead (1981)
 Evil Dead (2013)
 Fanfan la Tulipe (2003)
 Fanfan la Tulipe (1952)
 Mary a tout prix (1998)
 Black Sheep (2008)
 Le Monde de Nemo (2003)

Vous pouvez éventuellement l’améliorer encore un peu, en remplaçant l’itération sur les éléments de la collection des films, par un affichage sous forme de tableau, directement :

Remplacez :

foreach ($films as $film) {
    $io->text($film);
}

directement par $io->listing($films); (le module d’affichage fourni par Symfony propose directement ce qu’il nous faut avec une mise en forme standard) :

$ symfony console app:list-films

list of todos:
==============

 * Evil Dead (1981)
 * Evil Dead (2013)
 * Fanfan la Tulipe (2003)
 * Fanfan la Tulipe (1952)
 * Mary a tout prix (1998)
 * Black Sheep (2008)
 * Le Monde de Nemo (2003)

Pas beau ? !

En base de données, les films et les recommendations sont stockés dans des tables séparées (avec une clé étrangère migrée de films vers recommendations pour matérialiser l’association 1-N).

Comment allons-nous gérer cela en PHP ?

Plutôt que de charger en mémoire les films, d’un côté, puis les recommendations de l’autre, et de « réconcilier » ensuite manuellement quelles recommendations correspondent à quel film, nous allons exploiter les méthodes de parcours des propriétés de type collection offertes par l’ORM Doctrine.

Si on accède à la propriété Film::recommendations via $film->getRecommendations() (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.).

Mettons cela en pratique :

1. ajoutez, comme précédemment, une nouvelle commande app:show-film qui affiche un film et ses recommendations, en utilisant le générateur make:command.
2. Modifiez le code généré pour :
   1. brancher la base de données (comme ci-dessus, pour le repository des films)
   2. gérer le passage d’arguments à la commande : cette commande attend deux arguments : titre et année du film recherché (cf. configure() ci-dessous).
   3. afficher les données sur la console

Vous pouvez vous inspirer du code ci-dessous pour l’affichage des recommendations d’un film :

<?php

// [...]
#[AsCommand(
    name: 'app:show-film',
    description: 'Show recommendations for a film',
)]
class ShowFilmCommand extends Command
{
        //...

        protected function configure()
        {
                $this
                    ->addArgument('title', InputArgument::REQUIRED, 'Title of the film (spaces must be quoted)')
                    ->addArgument('year', InputArgument::REQUIRED, 'Year of the film')
                ;
        }

        protected function execute(InputInterface $input, OutputInterface $output)
        {
            $io = new SymfonyStyle($input, $output);
            $title = $input->getArgument('title');
            $year = $input->getArgument('year');

            if ($year && ! preg_match('/^\d+$/', $year)) {
                $io->error('second argument must be integer');
                return Command::FAILURE;
            }
            $film = $this->filmRepository->findOneBy([
                'year' => $year,
                'title' => $title]);
            if(!$film) {
                $io->error('unknown film: ' . $title . ' (' . $year .')');
                return Command::FAILURE;
            }
            $io->title($film . ':');

            $io->listing($film->getRecommendations()->getValues());

            return Command::SUCCESS;
        }

        // [...]
}

Testez :

symfony console app:show-film coin 42

Si vous avez une erreur par rapport à l’absence de ShowFilmCommand::$filmRepository, c’est que vous êtes allés un peu vite en besogne (lisez précisément les consignes ci-dessus). Recopiez, depuis le code existant dans ListFilmsCommand.php, les éléments correspondant à la propriété filmRepository, et à son initialisation dans le constructeur (cf. code de src/Command/ListFilmsCommand.php vu plus haut).

Re-testez :

$ symfony console app:show-film coin 42

[ERROR] unknown film: coin (42)

Bravo !

Attention à bien protéger les arguments passés à la commande par le shell, via des quotes :

symfony console app:show-film "Black Sheep" 2008

Ça ne marche toujours pas ?

Peut-être faut-il modifier Recommendation pour ajouter la méthode __toString() manquante, comme on l’avait fait pour src/Entity/Film.php. La méthode devrait être triviale à écrire en objet.

Finalement, ça doit marcher :

$ symfony console app:show-film "Black Sheep" 2008

Black Sheep (2008):
===================

 * Un scenario de génie
 * Une réalisation parfaite
 * À quand Black Goat ?

On va re-créer la base de données de l’application miniallocine qui nous sert à effectuer des tests pendant le développement et la mise au point du code. On travaillera toujours en ligne de commande depuis l’intérieur du projet Symfony de l’application miniallocine.

Effectuez les opérations suivantes :

1. Supprimez le fichier de base de données SQLite existant :

   cd miniallocine/
   rm -f var/data.db
   

2. Créez un fichier de base de données SQLite (vide), en exécutant la commande suivante :

   symfony console doctrine:database:create
   ls -l var/data.db
   

   En fait, il se trouve que cette commande se contente de créer un fichier vide, ce qui correspond au comportement nécessaire pour une base de données légère comme SQLite. Mais dans le cas où on utiliserait un autre SGBD, ceci peut s’avérer nécessaire.

3. Créez le schéma de la base SQLite (tables, index, etc.), en utilisant la sous-commande doctrine:schema:create :

   1. Commencez-donc par vérifier ce qui serait fait :

      symfony console doctrine:schema:create --dump-sql
      

      
      The following SQL statements will be executed:
      
      CREATE TABLE recommendation (id INTEGER PRIMARY KEY AUTOINCREMENT NOT
      NULL, film_id INTEGER NOT NULL, recommendation VARCHAR(255) NOT NULL);
      
      CREATE INDEX IDX_433224D2567F5183 ON recommendation (film_id);
      
      CREATE TABLE film (id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
      title VARCHAR(255) NOT NULL, year INTEGER NOT NULL);
      

   2. Comparez avec les éléments dans la classe PHP présente dans le module src/Entity/ de notre application. Est-ce que cela correspond au modèle des données souhaité (défini dans les attributs #[ORM... de nos classes PHP) ?

      Le code SQL affiché devrait vous sembler assez clair, même si certains identifiants (clés étrangères, index) sont nommés de façon arbitraire par Doctrine. Pour le reste : classes, propriétés mono-valuées, ça correspond normalement aux noms présents dans le code.

   3. Essayez de créer le schéma pour de bon, avec :

      symfony console doctrine:schema:create
      

      Symfony est très prudent, car il ne le fait pas : trop dangereux… vous devez confirmer explicitement cette opération potentiellement destructrice.

   4. Forcez explicitement la création du schéma pour de bon (vraiment, cette fois).

Si vous consultez le contenu de la base présent dans var/data.db, avec sqlite3 (ligne de commande) ou sqlitebrowser (interface graphique), vous pourrez afficher le schéma de la base :

$ sqlite3 var/data.db
SQLite version 3.27.2 2019-02-25 16:06:06
Enter ".help" for usage hints.
sqlite> .schema
CREATE TABLE recommendation (id INTEGER PRIMARY KEY AUTOINCREMENT NOT
NULL, film_id INTEGER NOT NULL, recommendation VARCHAR(255) NOT NULL);
CREATE TABLE sqlite_sequence(name,seq);
CREATE INDEX IDX_433224D2567F5183 ON recommendation (film_id);
CREATE TABLE film (id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
title VARCHAR(255) NOT NULL, year INTEGER NOT NULL);
sqlite> .exit

On pourrait injecter des données dans la base via un script SQL, mais cela nécessiterait d’avoir préalablement bien compris comment gérer les différentes clés étrangères, par exemple. Il y aurait des chances que les données injectées soient difficiles à générer « à la main » en écrivant le code SQL directement (erreurs d’identifiants, violations de contraintes, etc.)

Contrairement à cette approche, le module Data Fixtures permet d’écrire ce chargement des données en PHP, en utilisant les méthodes des classes du modèle de données basé sur Doctrine.

Cela nous assure qu’on exécute bien le code PHP du modèle de notre application. Cela permet de tester par là-même que le code de l’application fonctionne bien.

Les manipulations d’identifiants sont évitées, en utilisant à la place des alias mnémotechniques, ce qui rend bien plus simple la mise au point des jeux de données, et diminue les bugs : une seule référence : le code PHP. Ici on n’aura pas à avoir de doutes entre qui a raison : le code PHP ou le code SQL.

Revoyons plus en détails comment marchent les Data Fixtures :

1. Chargez les données de tests :

   symfony console doctrine:fixture:load
   

   Cette commande vous indique qu’elle charge les données à partir du module PHP dont le namespace est « App\DataFixtures\AppFixtures ».

2. Vérifiez le contenu de la base de données (sqlite3 ou sqlitebrowser). Par exemple, la commande suivante affiche un « dump » du contenu de la base :

   sqlite3 var/data.db .dump
   

   Vous avez normalement récupéré les mêmes données qu’une fois les données de test chargées dans la base.

3. Consultez le code des fixtures dans la classes PHP présente dans src/DataFixtures/AppFixtures.php (on vous avait fait ajouter ce code par copier/coller).

Quelle version vous semble-t-elle plus lisible / compréhensible : le dump SQL ou le code objet PHP s’appuyant sur les Fixtures de Doctrine ?

Observez le code de load( ) : il utilise les données brutes pour instancier en mémoire des objets PHP de notre modèle de données (instances de App\Entity\Film), appeler leurs setters pour initialiser les valeurs des attributs, et enfin, demander à Doctrine de sauvegarder ces objets ($manager->persist()). On voit bien comment ce code teste effectivement le modèle des données, tout en remplissant la base. Si les setters sont incorrects, cela sera détecté.

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

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

   symfony console app:list-films
   

Regardez les traces apparaissant dans le fichier var/log/dev.log au fur et à mesure des commandes (ouvrez par exemple un autre terminal et exécutez-y : tail -f $HOME/CSC4101/tp-mini-allocine/miniallocine/var/log/dev.log)

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

2019-07-22T16:54:46+02:00 [debug] SELECT t0.id AS id_1, t0.title AS title_2, t0.year AS year_3 FROM film t0

On verra plus tard, quand on sera en mode Web, qu’on aura à notre disposition des traces de ces requêtes dans la barre d’outils de mise au point de Symfony.

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

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

Il suffit de modifier pour cela la classe FilmRepository, qui a été générée dans src/Repository/FilmRepository.php, pour surcharger la méthode findAll() qu’elle hérite d’une classe parente.

Vous pouvez par exemple coder ceci, pour surcharger la méthode par défaut findAll() en utilisant une méthode plus flexible (findBy()) en lui spécifiant les arguments de tri :

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

Testez que cela change bien la requête effectuée dans symfony console app:list-films.

Mais comment savoir comment on peut écrire ce bout de code, sans passer des semaines à lire la doc (ou bien comprendre quelle est la meilleure façon de faire à la lecture des dizaines de messages sur des forums répondant plus ou moins à cette question…) ?

Examinons la documentation

Ça a l’air trivial (et un truc de boomer) d’apprendre à lire la doc… pourtant le temps passé à lire la documentation est souvent profitable par rapport au temps passé à faire le tri dans les réponses de StackExchange (sans parler de demander à une IA).

Sur le modèle de la portion de code précédente, écrivez enfin une commande app:add-recommendation permettant d’ajouter une recommendation à un film existant.

C’est l’étape la plus difficile de cette séquence.

Vous pourrez utiliser les éléments suivants pour mettre en œuvre ce code (un peu plus compliqué que les précédents, mais notez que l’on avait déjà vu des choses de ce genre dans le code des Fixtures) :

// Chargement en mémoire d'un film existant dans la base
$film = $this->filmRepository->findOneBy(
        ['year' => $year,
         'title' => $title]);

// Création d'une instance en mémoire
$recommendation = new Recommendation();
$recommendation->setRecommendation($recotext);

// Ajout en mémoire dans la collection des recommendations de ce film
$film->addRecommendation($recommendation);

Pour le reste, ça ressemble beaucoup à la commande précédente (appel à $this->filmRepository->save($film, true), etc.).

Testez de-même en ligne de commande :

symfony console app:add-recommendation "Mon film préféré" 2023 "Un beau nanard !"

Vérifiez que cela fonctionne, et que les requêtes SQL INSERT sont bien transmises à la base SQLite.

Vérifiez avec symfony console app:show-film que vous retrouvez bien les recommendations pour leur film.

Nous reviendrons plus tard dans le cours sur les détails d’utilisation de Doctrine pour la sauvegarde des données dans la base, mais notez déjà quelques éléments clé.

Cela nous permet de revenir sur la conception en base de données d’associations 1-N / OneToMany, vue l’année dernière.

Le comportement de l’ORM Doctrine a été défini tout d’abord en fonction de nos réponses lors de l’utilisation de l’assistant générateur de code, dans une séquence précédente :

• nous avions créé la classe Recommendations liée à Films par une « relation » OneToMany (« association 1-N », en vocabulaire Entités-Associations). Dans src/Entity/Film.php on retrouve donc l’attribut de type Collection Film::recommendations avec un annotation Doctrine #[ORM\OneToMany]
• puis nous avions configuré explicitement l’option cascade: ["persist"] (« Ajout de la persistence en cascade »).

Cela signifie qu’on souhaite la génération d’ajouts automatique en base (en cascade), dans la table « fille » de cette relation OneToMany (ici Recommendation), si un élément a été ajouté à la collection en mémoire, au moment où on invoque persist sur l’entité « mère » (Film), via l’appel à save() du Repository.

Le fait qu’on ait utilisé Film::addRecommendation($recommendation) sur $film, puis FilmRepository::save() entraine donc une insertion dans la table qui stocke cette entité liée. La table films n’a pas changé, en base : c’est une nouvelle ligne dans recommendations qui référence films, qu’il faut ajouter.

L’ORM Doctrine fait le job. Vous voyez que l’INSERT transporte bien le film_id dans la valeur de la clé étrangère, comme prévu.

Dans les codes proposés ci-dessus, vous aurez peut-être remarqué qu’on n’a pas traité les cas d’erreur, et seulement supposé que tout se passe bien, pour simplifier les exemples.

Ainsi, dans l’ajout d’une recommendation avec app:add-recommendation, on suppose que le film pour lequel on ajoute la recommendation a bien été trouvé par l’appel findOneBy(). Bien évidemment, si l’utilisateur saisit des informations ne correspondant à aucun film, ce code va sûrement moins bien marcher…

Nous verrons plus tard comment gérer les erreurs au mieux, mais vous pouvez éventuellement réfléchir au sujet, et examinant le rôle du code de retour de la méthode execute().

La gestion des cas d’erreur sera abordée plus tard dans le contexte Web, avec la notion d’exceptions.

Proposition d’implémentation de AddRecommendationCommand::execute() pour l’ajout des entités liées dans une relation OneToMany :

// [...]

class AddRecommendatioCommand extends Command
{
    // [...]

    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $io = new SymfonyStyle($input, $output);
        $title = $input->getArgument('title');
        $year = $input->getArgument('year');
        $recotext = $input->getArgument('recotext');

        if ($year && ! preg_match('/^\d+$/', $year)) {
            $io->error('second argument must be integer');
            return Command::FAILURE;
        }
        $film = $this->filmRepository->findOneBy([
            'year' => $year,
            'title' => $title]);
        if(!$film) {
            $io->error('unknown film: ' . $title . ' (' . $year .')');
            return Command::FAILURE;
        }

        // Création d'une instance en mémoire
        $recommendation = new Recommendation();
        $recommendation->setRecommendation($recotext);

        // Ajout en mémoire dans la collection des recommendations de ce film
        $film->addRecommendation($recommendation);

        $this->filmRepository->save($film, true);

        return Command::SUCCESS;
    }