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

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.

Dans ce qui suit, on supposera que vous travaillez connecté dans un terminal, sur la machine que vous allez utiliser pour le reste des séances de TP et de travail hors-présentiel (y compris le projet).

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.

Cette commande s’appuie sur le gestionnaire de paquetages PHP Composer, en appelant la commande create-project de composer.

Téléchargez et installez le squelette d’application sur lequel vous allez travailler dans la suite de la séance :

cd $HOME/CSC4101/tp-mini-allocine/
symfony new miniallocine --version=stable

Cette commande affiche plusieurs infos intéressantes pour comprendre ce qui se passe :

Creating a new Symfony 6.3 project with Composer
  (running /usr/bin/composer create-project symfony/skeleton /.../miniallocine 6.3.* --no-interaction)

* Setting up the project under Git version control
  (running git init /.../miniallocine)

 [OK] Your project is now ready in /...//miniallocine                                  

• on voit ce qui a été invoqué via Composer : composer create-project symfony/skeleton miniallocine 6.3.* --no-interaction
• Symfony initialise un référentiel Git local pour le projet, automatiquement. Il sera plus facile de faire des copies de sauvegardes des incréments pendant un projet Symfony, si l’IDE qu’on utilise gère Git.

Pour info, voici la signification des arguments de l’invocation de Composer:

create-project

commande create-project de composer (cf. documentation composer)

symfony/skeleton

référence du squelette d’application standard d’application Web pour la version de Symfony sur laquelle on se base

miniallocine

le nom du répertoire qui va être créé pour contenir le projet Symfony

6.3.*

téléchargement du squelette pour une version précise de Symfony, ici la 6.3. C’est celle qui correspond (au moment où on exécute la commande symfony new --version=stable) à la version stable de Symfony.

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;

Vous le trouverez via :

ls -l miniallocine/bin/

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.

La commande bin/console fournie propose d’accéder en ligne de commande à différentes fonctionnalités du cadriciel Symfony, notamment des utilitaires intéressants pour les phases de développement et de tests.

Essayez les commandes suivantes dans un terminal, depuis l’intérieur du répertoire du projet Symfony :

1. Vérifiez la version de Symfony utilisée dans le projet

   cd $HOME/CSC4101/tp-mini-allocine/miniallocine/
   symfony console -V
   

   Symfony 6.3.1 (env: dev, debug: true) #StandWithUkraine https://sf.to/ukraine
   

   Vous êtes en environnement de développement dev (pas encore prêts pour la prod !)

2. Affichez la liste des sous-commandes disponibles (avec la sous-commande list, ou directement sans argument passé à symfony console) :

   symfony console list
   

3. Consultez l’aide en ligne avec la sous-commande help. Par exemple :

   symfony console help about
   

4. Et consultez donc également la sortie fournie par cette sous-commande about :

   symfony console about
   

   Cette commande donne différentes informations sur l’environnement de développement et de mise au point.

Comme dans l’application Java du Mini-Allociné, 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.

On va 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 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). Son rôle 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 une entité au modèle des données de l’application, en répondant simplement à une série de questions, en évitant ainsi d’écrire le code PHP correspondant.

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

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é « Film ».

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 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 une association avec l’entité Film, matérialisée par la propriété Recommendation::film, de type relation et de cardinalité ManyToOne, qui sera une référence au film sur lequel porte la recommendation (plusieurs recommendations portent sur le même film).

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

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

Rechargez 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 comporte deux propriétés primaires : 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)

Remarquez que le code de ces propriétés de classes du modèle de données est « décoré » par des attributs PHP préfixés par ORM (#[ORM\...]). Les attributs permettant d’enrichir la sémantique du langage PHP « de base », en ajoutant des méta-données aux classes ou à leurs propriétés, méthodes, etc. Ainsi, pour cette propriété $id identifiant les instances, on précise à Doctrine qu’il s’agit de gérer une clé primaire dans la base de données, en lui ajoutant l’attribut ORM\Id

La classe Film comporte aussi une propriété multi-valuée recommendations qui agit comme une collection des instances de Recommendation relatives à une instance de Film. Remarquez que l’assistant générateur de code nous a proposé de le nommer ainsi, en ajoutant un « s » au nom de la classe, pour bien matérialiser le pluriel. Cette propriété comporte l’attribut ORM\OneToMany qui définit en particulier l’entité cible de l’association 1-n (targetEntity: Recommendation::class"). Elle se manipule en PHP avec une interface Collection semblable aux tableaux PHP classiques (Array).

$recommendations = $film->getRecommendations();

if (count($recommendations))
{
        foreach($recommendations as $recommendation)
        {
                print $recommendation;
        }
}

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

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 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 de films ou de recommendations (qui vous rappelleront quelques souvenirs).

Nous allons compléter le code de la classe qui a été générée par Composer au moment de l’initialisation du projet.

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

Le cœur de l’opération se passe dans les appels aux méthodes setters des propriétés des instances (crées avec new) des classes Film ou Recommendation, de façon similaire à ce qu’on fait en Java.

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

<?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 fim-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

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 le code généré par l’assistant pour l’association 1-N qui lie les entités Film et Recommendation n’a pas pu prendre toutes les décisions nécessaires. Si vous lisez attentivement le message d’erreur ci-dessus, Symfony nous donne quand même des recommendations utile.

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 #[ORM\OneToMany] de Film::recommendations, dans le fichier source src/Entity/Film.php :

#[ORM\OneToMany(mappedBy: 'film', targetEntity: Recommendation::class, 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) :

// ...

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();
    }

        //...

Ajoutons maintenant 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 FilmRepository, qui a été généré par l’asssistant, et 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 (attentue) 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 writeln() 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 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->year . ")";
}

Réessayez le lancement de notre application :

$ 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 quelles recommendations correspondent à quel film manuellement, nous allons exploiter les méthodes de parcours des propriétés de type collection.

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 capôt sans qu’on ait à s’en préoccuper (jointures, etc.).

Mettons cela en pratique : 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. Cette commande attend cette fois deux arguments : titre et année du film recherché.

Vous pouvez vous inspirer du code ci-dessous pour l’affichage des recommendations d’un film. Observez la façon dont est écrit le foreach qui permet d’accéder aux données liées dans la collection des recommendations de ce 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

Vous devriez avoir une erreur par rapport à l’absence de ShowFilmCommand::$filmRepository. Recopiez, depuis le code existant dans ListFilmsCommand.php, les éléments correspondant à la propriété et à son initialisation dans le constructeur (cf. ci-dessus).

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 ?

Modifiez Recommendation pour ajouter la méthode __toString() triviale manquante.

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

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

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

On peut souhaiter tester différentes améliorations du code, que nous listons ici, mais qui sont optionnelles, pour aller plus loin, si vous avez terminé le reste du travail.

Cela permet de revoir quelques notions liées aux requêtes dans les bases de données relationnelles, comme la sélection, et le tri.

Mais au fait… et le Web ?

Le TP en Java avait comporté une interface Web, accessible en HTTP… alors, on est dans le cours sur le Web, et on s’arrête à la ligne de commande ?

Patience.

Nous passerons à l’étude des contrôleurs pour la gestion d’HTTP dans Symfony dans les prochaines séquences du cours.

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.

Effectuez les opérations suivantes pour dupliquer le dossier :

cd $HOME/CSC4101
cp -r tp-01 tp-03
cd tp-03
cd miniallocine

Ensuite, dans le projet, on va réinitialiser les rouages du projet avec Composer :

cd $HOME/CSC4101/tp-03/miniallocine
rm -fr composer.lock symfony.lock var/cache/ vendor/
symfony composer install

Cette étape est nécessaire car Symfony s’appuie sur une mécanique sophistiquée de mise en cache (dans var/cache/) du code de l’application, pour assurer des performances maximales. Malheureusement, si on duplique un projet, une partie de ce cache a tendance à devenir incohérente (présence de chemins d’accès « en dur », etc.).

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

Pour les utilisateurs de l’IDE Eclipse, supprimez les anciennes infos du projet Eclipse avant de refaire un import :

cd $HOME/CSC4101/tp-03/miniallocine
rm -fr .project .settings/

Chargez maintenant dans votre IDE cette nouvelle version du projet Symfony « mini-allociné » sur laquelle vous allez travailler.

Dans Eclipse vous pouvez importer le nouveau projet dans le même workspace que le précédent, et fermer le projet précédent (menu Project / Close …).

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

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

      symfony console doctrine:schema:update --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 annotations @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 générés de façon arbitraire. Pour le reste : classes, attributs, ça correspond normalement aux noms de vos classes ou méthodes PHP.

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

      symfony console doctrine:schema:update
      

      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.

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

Doctrine permet donc de générer complètement la base de données, de façon assez transparente pour le programmeur PHP (notamment sans avoir à se soucier des spécificités de chaque SGBD : MariaDB vs PostgreSQL vs …). Le développeur se concentre sur son modèle objet, sur le code PHP et ses annotations/attributs Doctrine, sans avoir besoin d’apprendre SQL (la chance ?).

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

Nous disposons maintenant d’une base de données pour tester l’application. L’application fonctionne (symfony console app:list-films), même si comme la base est encore vide, il ne se passe pas grand chose d’intéressant.

Voyons maintenant comment ajouter des données de tests dans la base SQLite.

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.

Vous allez utiliser ce module de Symfony couplé à Doctrine, gérant des 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 que dans l’état initial de la base, que vous aviez utilisée pendant le TP précédent.

3. Consultez le code des fixtures dans les classes PHP présentes dans src/DataFixtures/AppFixtures.php. On vous avait fait ajouter ce code par copier/coller dans la séance précédente.

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-03/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 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…) ?

Commençons par examiner 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.

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

Vous pouvez parcourir rapidement cette documentation.

Mais vous devriez néanmoins repérer du code similaire à celui de notre application « mini-allociné », 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 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

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…

Examinons alors comment se référer à la documentation ultime : le code des composants qu’on utilise.

Revenons à la modification du code de src/Repository/FilmRepository.php qu’on vous a proposée pour modifier le tri effectué au de chargement des données.

Ici on développe en objet, et le principe des classes Repository de notre modèle de données dans src/Repository/ est de surcharger celui par défaut de Doctrine.

Pour modifier le comportement, il faut d’abord penser objet : surcharger le comportement par défaut en spécialisant le comportement de notre repository, par rapport au repository générique de la classe de base.

Mais encore faut-il trouver la documentation de l’API (Application Programming Interface) de Doctrine qui codifie ce comportement par défaut…

En fait, en l’occurrence, ici, les développeurs de Doctrine ne publient malheureusement pas sur le Web une documentation spécifique de l’API.

Mais dans ce cas, on doit se référer au code. Et ça tombe bien, car ce code contient des commentaires (docstrings) que l’IDE peut exploiter pour nos guider dans l’utilisation des API des bibliothèques comme Doctrine.

public function findAll()
{
        return $this->findBy([]);
}

/**
 * Finds entities by a set of criteria.
 *
 * @param int|null $limit
 * @param int|null $offset
 * @psalm-param array<string, mixed> $criteria
 * @psalm-param array<string, string>|null $orderBy
 *
 * @return object[] The objects.
 * @psalm-return list<T>
 */
public function findBy(array $criteria, ?array $orderBy = null, $limit = null, $offset = null)
[...]

Vous comprenez donc mieux le rôle des arguments qu’on passe à findBy() dans FilmRepository::findAll() :

1. array() : premier tableau attendu, $criteria (le critère filtre du WHERE de la requête SQL), ici un tableau vide, donc pas de filtre à appliquer;
2. array('year'=>'ASC', 'title'=>'ASC') deuxième tableau (optionnel) $orderBy, pour les critères de tri (par year puis par title).

Sur le modèle des ajouts de commandes effectués dans la séance précédente, ajoutez une commande app:add-film qui prend deux arguments (titre, année) et va ajouter le film correspondant à la base de données.

symfony console make:command

Voici un squelette de code à adapter, qui permet d’ajouter des données dans la base via Doctrine :

use Symfony\Component\DependencyInjection\ContainerInterface;
use Doctrine\ORM\EntityManager;
use App\Entity\Film;

//...
class AddFilmCommand //...
{
        //...

        protected function execute(InputInterface $input, OutputInterface $output): int
        {
                //...

                // crée une instance en mémoire
                $film = new Film();
                $film->setTitle($title);
                $film->setYear($year);

        // sauve l'instance dans la base de données
        $this->filmRepository->save($film, true);

        // si tout va bien, on récupère un identifiant
        if($film->getId()) {
            $io->text('Created: '. $film);

            return Command::SUCCESS;
        }
        else {
            $io->error('could not create film!');
            return Command::FAILURE;
        }
        }
}

Examinez les commentaires du code ci-dessus, qui devraient déjà vous donner suffisamment d’informations pour arriver à faire marcher cette commande.

Une fois codé la méthode AddFilmCommand::execute(), testez là pour voir passer les requêtes SQL générées par Doctrine dans le fichier de logs :

symfony console app:add-film "Mon film préféré" 2023

Vérifiez-bien que vous avez bien obtenu les requêtes SQL INSERT désirées.

symfony console cache:clear

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

// 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 la séance 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 attribut/annotation Doctrine =#[ORM\OneToMany]
• puis nous avions configuré explicitement l’option cascade: ["persist"] (« Étape 2-g : 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;
    }