# Programmation PHP avec Symfony/Doctrine

* Introduction
* Service
** Contrôleur
** Commande
* Composant
** HttpClient
** Évènement
** Formulaire
** Mailer
** Stimulus
* Bundle
** Twig
** Doctrine
** API
* Introduction
* Service
** Contrôleur
** Commande
* Composant
** HttpClient
** Évènement
** Formulaire
** Mailer
** Stimulus
* Bundle
** Twig
** Doctrine
** API
[ Modifier le sommaire ]

## Installation

Doctrine est l'ORM par défaut de Symfony. Il utilise PDO. Son langage PHP traduit en SQL est appelé DQL, et utilise le principe de la chaîne de responsabilité.
Installation en SF4 :
Renseigner l'accès au SGBD dans le .env :
Ensuite la base de données doit être créée avec :
* doctrine/doctrine-bundle
* doctrine/doctrine-migrations-bundle
* doctrine/orm
* symfony/proxy-manager-bridge

## Commandes Doctrine

Exemples de commandes :

## Entity

Une entité est une classe PHP associée à une table de la base de données. Elle est composée d'un attribut par colonne, et de leurs getters et setters respectifs. Pour en générer une :
Cette association est définie par des annotations Doctrine. Pour vérifier les annotations :

### Exemple

Voici par exemple plusieurs types d'attributs :
Exemple avec annotation (avant PHP 8)
Et leurs modificateurs (getters et setters) :
On voit ici que la table "word" possède trois champs : "id" (clé primaire), "pronunciation" (chaine de caractère) et "language_id" (clé étrangère vers la table "language"). Doctrine stockera automatiquement l'id de la table "language" dans la troisième colonne quand on associera une entité "Language" à une "Word" avec $word->setLanguage($language).
Le quatrième attribut permet juste de récupérer les enregistrements de la table "homophon" ayant une clé étrangère pointant vers "word".
Par ailleurs, en relation "OneToMany", c'est toujours l'entité ciblée par le "Many" qui définit la relation car elle contient la clé étrangère. Elle contient donc l'attribut "inversedBy=", alors que celle ciblée par "One" contient "mappedBy=". Elle contient aussi un deuxième attribut #[ORM\JoinColumn (anciennement @ORM\JoinColumn) mentionnant la clé étrangère en base de données (et pas en PHP).

### Bonnes pratiques

L'attribut #[ORM\Table(name: 'word')] était facultatif dans cet exemple, car le nom de la table peut être déduit du nom de l'entité.
Avant PHP 8, les contraintes d'unicité (utiles entre autres pour les clés composites) étaient encapsulées dans l'annotation Table, mais ce n'est plus le cas avec les attributs :
Exemple avec annotation (avant PHP 8)
Dans les relations *toMany :
* il faut initialiser l'attribut dans le constructeur en ArrayCollection.
* on peut avoir une méthode ->set(ArrayCollection) mais le plus souvent on utilise ->add(un seul élément)
* cette méthode add doit idéalement contenir le set de l'entité cible vers la courante (pour ne pas avoir à l'ajouter après chaque appel).
Il faut ajouter le #[ORM\JoinColumn( dans les deux entités liées, car :
* dans aucune cela renvoie Could not resolve type of column "id"
* dans une seule cela provoque un problème N+1 (celle qui ne l'a pas appelle celle qui l'a pour chacun de ses enregistrements, même si celle qui l'a n'est pas utilisée ensuite).
NB : par défaut la longueur des types "string" est 255, on peut l'écraser ou la retirer avec length=0. Le type "text" par contre n'a pas de limite.

### ArrayCollection

Cet objet itérable peut être converti en tableau avec ->toArray.
Pour le trier :
* Dans une entité : #[ORM\OrderBy(['sort_order' => 'ASC'])] (anciennement @ORM\OrderBy({"sort_order" = "ASC"})).
* Sinon, instancier un critère :

### GeneratedValue

L'annotation GeneratedValue peut valoir "AUTO", "SEQUENCE", "TABLE", "IDENTITY", "NONE", "UUID", "CUSTOM".
Dans le cas du CUSTOM, un setId réaliser avant le persist sera écrasé par la génération d'un nouvel ID. Ce nouvel ID peut être écrasé à son tour, mais si l'entité possède des liens vers d'autres, c'est l'ID custom qui est utilisé comme clé (on a alors une erreur Integrity constraint violation puisque la clé générée n'est pas retenue). Pour éviter cela (par exemple dans des tests automatiques), il faut désactiver la génération à la volée :

### Triggers

Les opérations en cascade sont définies sous deux formes d'attributs :
* #[ORM\OneToMany(cascade: ['persist', 'remove'])] : au niveau ORM.
* #[ORM\JoinColumn(onDelete: 'CASCADE')] : au niveau base de données.
Ainsi, quand on supprime l'entité contenant un cascade remove, cela supprime aussi ses entités liées par cette relation.

### Concepts avancés

Pour utiliser une entité depuis une autre, alors qu'elles n'ont pas de liaison SQL, il existe l'interface ObjectManagerAware.
Les types des attributs peuvent être quelque peu différents du SGBD.
Dans le cas de jointure vers une entité d'un autre espace de nom (par exemple une table d'une autre base), il faut indiquer son namespace complet dans l'annotation Doctrine (car elle ne tient pas compte des "use").
L'autojointure est appelé self-referencing association mapping par Doctrine).

### Héritage

Une entité peut hériter d'une classe si celle-ci contient l'annotation suivante :

### Tables sans classe

Doctrine peut créer des tables de mapping sans entité, si on précise son nom dans les deux tables reliées :

## EntityManager

L'EntityManager (em) est l'objet qui synchronise les entités avec la base de données. Une application doit en avoir un par base de données, définis dans doctrine.yaml.
Il possède trois méthodes pour cela :
* persist : prépare un INSERT SQL (rattache une entité à un entity manager).
* remove : prépare un DELETE SQL.
* flush : exécute le code SQL préparé.
Il existe aussi les méthodes suivantes :
* merge : fusionne une entité absent de l'em dedans.
* refresh : rafraichit l'entité PHP à partir de la base de données. C'est utile par exemple pour tenir compte des résultats d'un trigger after insert sur le SGBD. Exemple si le trigger ajoute une date de création après le persist, à écraser par $createdDate :

## Repository

On appelle "repository" les classes PHP qui contiennent les requêtes pour la base de données. Elles héritent de Doctrine\ORM\EntityRepository. Chacune permet de récupérer une entité associée en base de données. Les repo doivent donc être nommés NomDeLEntitéRepository.
Exemple avec annotation (avant PHP 8)

### SQL
#### Sans Doctrine

Pour exécuter du SQL natif dans Symfony sans Doctrine, il faut créer un service de connexion, par exemple qui appelle PDO en utilisant les identifiants du .env, puis l'injecter dans les repos (dans chaque constructeur ou par une classe mère commune) :
Depuis un repository Doctrine, tout ceci est déjà fait et les deux techniques sont disponibles :
1. Par l'attribut entity manager (em, ou _em pour les anciennes versions) hérité de la classe mère (le "use" permettra ici d'appeler des constantes pour paramétrer le résultat) :
2. En injectant le service de connexion dans le constructeur ('@database_connection') :

### DQL
#### Méthodes magiques

Doctrine peut ensuite générer des requêtes SQL à partir du nom d'une méthode PHP appelée mais non écrite dans les repository (car ils en héritent). Ex :
* $repo->find($id) : cherche par la clé primaire définie dans l'entité.
* $repo->findAll : récupère tous les enregistrements (sans clause WHERE).
* $repo->findById($id) : engendre automatiquement un SELECT * WHERE id = $id dans la table associée au repo.
* $repo->findBy(['lastname' => $lastname, 'firstname' => $firstname]) engendre automatiquement un SELECT * WHERE lastname = $lastname AND firstname = $firstname.
* $repo->findOneById($id) : engendre automatiquement un SELECT * WHERE id = $id LIMIT 1.
* $repo->findOneBy(['lastname' => $lastname, 'firstname' => $firstname]) : engendre automatiquement un SELECT * WHERE lastname = $lastname AND firstname = $firstname LIMIT 1.
Lors des tests unitaires PHPUnit, il est probable qu'une erreur survienne sur l'inexistence de méthode "findById" pour le mock du repository (du fait qu'elle est magique). Il vaut donc mieux utiliser findBy.
Par ailleurs, on peut compléter les requêtes avec des paramètres supplémentaires. Ex :

#### createQuery

DQL possède une syntaxe proche du SQL, si ce n'est qu'il faut convertir les entités jointes en ID avec IDENTITY pour les jointures. Ex :

#### createQueryBuilder

L'autre syntaxe du DQL est en POO. Les méthodes des repos font appel createQueryBuilder :
Pour éviter le SELECT * dans cet exemple, on peut y ajouter la méthode ->select.
Pour afficher la requête SQL générée par le DQL, remplacer "->getResult" par "->getQuery".

##### Jointures

Quand deux entités ne sont pas reliées entre elles, on peut tout de même lancer une jointure en DQL :

##### Résultats

Doctrine peut renvoyer avec :
* getResult : un objet ArrayCollection (iterable, pour rechercher dedans : ->contains), d'objets (du type de l'entité) avec leurs méthodes get (pas set) ;
* getArrayResult ou getScalarResult : un tableau de tableaux (entité normalisée) ;
* getSingleColumnResult : un tableau unidimensionnel.

##### Cache
###### Configuration globale

Doctrine propose trois caches pour ses requêtes : celui de métadonnées, de requête et de résultats. Il faut d'abord définir les pools dans cache.yaml :
Puis dans doctrine.yaml, les utiliser :
À partir de là le cache des métadonnées est utilisé partout.

###### Configuration par entité

Par contre pour ceux de requêtes et de résultats, il faut les définir pour chaque entité, soit :
* Dans l'entité, avec un attribut #[ORM\Cache(usage: 'READ_ONLY', region: 'write_rare')] (anciennement @ORM\Cache(usage="READ_ONLY", region="write_rare")), utilisant la configuration doctrine.yaml :
* Dans le repository :
Dans cet exemple, on n'utilise pas cache.system pour le cache de résultats pour ne pas saturer le serveur qui héberge le code. cache.app pointe donc vers une autre machine, par exemple Redis, ce qui nécessite un appel réseau supplémentaire, et n'améliore donc pas forcément les performances selon la requête.

#### Expressions

Pour ajouter une expression en DQL, utilise $qb->expr. Ex :
* $qb->expr->count('u.id')
* $qb->expr->between('u.id', 2, 10) (entre 2 et 10)
* $qb->expr->gte('u.id', 2) (plus grand ou égal à 2)
* $qb->expr->like('u.name', '%son')
* $qb->expr->lower('u.name')
* $qb->expr->substring('u.name', 0, 1)

#### Injection de dépendances

Les repository DQL deoivent ServiceEntityRepository :
Mais parfois on souhaite injecter un service dans un repository. Pour ce faire il y a plusieurs solutions :
* Étendre une classe qui étend ServiceEntityRepository.
* Le redéfinir dans services.yaml.
* Utiliser un trait.

## Transactions

Pour garantir d'intégrité d'une transaction :
Il existe aussi une syntaxe alternative :

## Évènements

Pour ajouter des triggers sur la mise à jour d'une table, il y a deux solutions :
* ajouter dans son entité l'attribut #[ORM\HasLifecycleCallbacks], et à ses méthodes l'attribut de l'évènement concerné. Ex :
* ajouter des tags dans services.yaml. Ex :
Voici les évènements utilisables ensuite (dans les listeners / subscribers) :

### prePersist

Se produit avant la persistance d'une entité (paramètre : PrePersistEventArgs $args).

### postPersist

Se produit après la persistance d'une entité (PostPersistEventArgs $args).

### preUpdate

Se produit avant l'update d'une entité (PreUpdateEventArgs $args).

### postUpdate

Se produit après l'update d'une entité (PostUpdateEventArgs $args).

### preRemove

Se produit avant l'update d'une entité (PreRemoveEventArgs $args).

### postRemove

Se produit après l'update d'une entité (PostRemoveEventArgs $args).

### preFlush

Se produit avant la sauvegarde d'une entité (PreFlushEventArgs $args).
* Dans cet évènement, les attributs en lazy loading de l'entité flushée s'ils sont appelés, sont issus de la base de données et donc correspondent aux données écrasées (et pas aux nouvelles flushées).
* Si on flush l'entité qui déclenche cet évènement il faut penser à un dispositif anti-boucle infinie (ex : variable d'instance).
* Dans le cas d'un new sur une entité, le persist ne suffit pas pour préparer sa sauvegarde. Il faut alors appeler $unitOfWork->computeChangeSet($classMetadata, $entity).
Ex :
Parfois le $object::class peut renvoyer Proxies\__CG__\App\Entity\MyEntity au lieu de App\Entity\MyEntity, selon le cache utilisé.

### postFlush

Se produit après la sauvegarde d'une entité (PostFlushEventArgs $args).

## Migrations

Pour modifier la base de données avec une commande, par exemple pour ajouter une colonne à une table ou modifier une procédure stockée, il existe une bibliothèque qui s'installe comme suit :

### Création

Ensuite, on peut créer un squelette de "migration" :
Cette classe comporte une méthode "up" qui réalise la modification en SQL ou DQL, et une "down" censée faire l'inverse à des fins de rollback. De plus, on ne peut pas lancer deux fois de suite le "up" sans un "down" entre les deux (une table nommée migration_versions enregistre leur succession).

#### Exemple PHP

Cette technique est déconseillée car les entités peuvent évoluer indépendamment de la migration. Mais elle peut s'avérer utile pour stocker des données dépendantes de l'environnement.
$this->containergetParameter ne fonctionne pas sur la valeur du paramètre quand elle doit être remplacée par une variable d'environnement. Par exemple $_SERVER['SUBAPI_URI'] renvoie la variable d'environnement et $this->containergetParameter('env(SUBAPI_URI)') sa valeur par défaut (définie dans services.yaml).

### Exécution

La commande suivante exécute toutes les migrations qui n'ont pas encore été lancées dans une base :
Sinon, on peut les exécuter une par une selon le paramètre, avec la partie variable du nom du fichier de la classe (timestamp) :
Pour le rollback :
Pour éviter que Doctrine pose des questions durant les migrations, ajouter --no-interaction (ou -n).
Pour voir le code SQL au lieu de l'exécuter : --write-sql.

#### Sur plusieurs bases de données

Pour exécuter sur plusieurs bases :
Avec des migrations.yaml de type :

### Synchronisation
#### Vers le code
##### Vers les entités

Ce script ne fonctionne pas avec les attributs PHP8. Donc pour créer une nouvelle entité à partir d'une table, utiliser un filtre et passer Rector pour convertir les annotations. Ex :

##### Vers les migrations

Pour créer la migration permettant de parvenir à la base de données actuelle :

#### Vers la base

À contrario, pour mettre à jour la BDD à partir des entités :
Pour le prévoir dans une migration :

## Fixtures

Il existe plusieurs bibliothèques pour créer des fixtures, dont une de Doctrine :
Pour charger les fixtures du code dans la base :

## Types de champ

La liste des types de champ Doctrine se trouve dans Doctrine\DBAL\Types. Toutefois, il est possible d'en créer des nouveaux pour définir des comportements particuliers quand on lit ou écrit en base.
Par exemple on peut étendre JsonType pour surcharger le type JSON par défaut afin de lui faire faire json_encode($value, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) automatiquement.
Ou encore, pour y stocker du code de configuration désérialisé dans une colonne.

## Réplication SQL

Anciennement appelée MasterSlaveConnection, la réplication entre une base de données accessible en écriture et ses réplicas accessibles en lecture par l'application, est prise en charge par Doctrine qui effectuera automatiquement les SELECT vers les réplicas pour soulager la base principale. Il suffit juste d'indiquer les adresses des réplicas dans doctrine.yml. Ex :

## Critique

* Il faut revenir en SQL si les performances sont limites (ex : un million de lignes avec jointures) ou si on veut tronquer une table.
* Si les valeurs d'une table jointe n'apparaissent pas tout le temps, vérifier que le lazy loading est contourné par au choix :
** Avant l'appel null, un ObjetJoint->get.
** Dans l'entité, un @ManyToOne(…, fetch="EAGER").
** Dans le repository, un $this->queryBuilder->addSelect.
* Pas de HAVING MAX car il n'est pas connu lors de la construction dans la chaine de responsabilité
* Pas de FULL OUTER JOIN ou RIGHT JOIN (que "leftJoin" et "innerJoin")
* Attention aux $this->queryBuilder->setMaxResults et $this->queryBuilder->setFirstResult en cas de jointure, car elles ne conservent que le nombre d'enregistrements de la première table (à l'instar du LIMIT SQL). La solution consiste à ajouter un paginateur.
* L'annotation @ORM/JOIN TABLE crée une table vide et ne permet pas d'y placer des fixtures lors de sa construction.
* Pas de hints.
* Bug des UNION ALL quand on joint deux entités non liées dans le repo.
* Connexion à chaque SGBD Doctrine : MSSQL + GUI Linux, MariaDB, Webdis, MySQL (patrons à copier-coller ?)
* Problème N+1 avec addSelect & que faire si ça rajoute une requête par ligne au lieu d'en retirer une ?

## Références

* ↑ https://symfony.com/doc/current/doctrine.html
* ↑ https://www.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/types.html#string
* ↑ https://stackoverflow.com/questions/31594338/overriding-default-identifier-generation-strategy-has-no-effect-on-associations
* ↑ https://www.doctrine-project.org/api/persistence/1.0/Doctrine/Common/Persistence/ObjectManagerAware.html
* ↑ https://www.doctrine-project.org/projects/doctrine-dbal/en/2.8/reference/types.html#mapping-matrix
* ↑ https://www.doctrine-project.org/projects/doctrine-orm/en/2.8/reference/association-mapping.html#many-to-many-self-referencing
* ↑ https://www.doctrine-project.org/projects/doctrine-orm/en/2.8/reference/inheritance-mapping.html
* ↑ https://medium.com/@dotcom.software/using-doctrines-l2-cache-in-symfony-eba300ab1e6
* ↑ https://www.doctrine-project.org/projects/doctrine-orm/en/2.12/reference/query-builder.html#the-expr-class
* ↑ https://www.doctrine-project.org/projects/doctrine-orm/en/2.7/reference/transactions-and-concurrency.html#approach-2-explicitly
* ↑ https://stackoverflow.com/questions/37831828/symfony-onflush-doctrine-listener
* ↑ https://stackoverflow.com/questions/10800178/how-to-check-if-entity-changed-in-doctrine-2
* ↑ https://symfony.com/doc/current/bundles/DoctrineFixturesBundle/index.html
* ↑ https://speakerdeck.com/lyrixx/doctrine-objet-type-et-colonne-json?slide=23
* ↑ https://medium.com/@dominykasmurauskas1/how-to-add-read-write-replicas-on-symfony-6-using-doctrine-bundle-a46447449f35
* ↑ https://stackoverflow.com/questions/50199102/setmaxresults-does-not-works-fine-when-doctrine-query-has-join/50203939