winzik/docs/ide/fr/doctrine.md

128 lines
11 KiB
Markdown

# Doctrine
La fenêtre **Doctrine** (barre d'outils du bas ; Search Everywhere : *Doctrine: …*) apparaît dans un projet dont le `composer.json`
requiert `doctrine/orm` ou `doctrine/doctrine-bundle` (ou qui a `config/doctrine/`). Elle lit le mapping depuis les sources, sans rien
exécuter : les attributs `#[ORM\...]` des classes des dossiers PSR-4 (propriétés et propriétés promues du constructeur) et les mappings
XML (`config/doctrine/*.orm.xml`). Quatre onglets ; la fenêtre peut prendre tout l'écran (son bouton ⤢, Échap la rend).
Ce qui est lu : les champs (leur type, écrit ou déduit du type PHP comme le fait l'ORM ; longueur, précision / échelle, nullable, unique,
id, valeur générée, type enum), les relations (`OneToOne`, `OneToMany`, `ManyToOne`, `ManyToMany` ; côté propriétaire / inverse,
`mappedBy` / `inversedBy`, cascade, orphanRemoval, colonnes de jointure et tables de jointure, avec les noms que donne la stratégie de
nommage underscore), les embeddables et `#[Embedded]` avec leur préfixe, l'héritage (table unique, jointe, superclasses mappées : les
champs hérités sont montrés comme tels, le discriminant et sa table de correspondance), les enums PHP avec leurs cas, les dépôts, les
ressources API Platform (`#[ApiResource]`).
![Le diagramme des entités](../images/doctrine-diagram.png)
## Diagram
- Une boîte par entité, superclasse mappée, embeddable et enum utilisé par un champ ; une arête par relation, tracée depuis son côté
propriétaire, avec ses multiplicités aux deux bouts (une flèche quand elle est à sens unique, le nom de la table de jointure sur un
ManyToMany) ; l'héritage en vert (triangle creux), les classes embarquées en jaune (losange), les enums en pointillés. Badges : `STI` /
`CTI` (héritage), `MS` (superclasse mappée), `EMB`, `API`, `repo` (un clic ouvre le dépôt).
- Faites glisser une boîte par son titre pour la déplacer (retenu pour le projet ; **Layout** les replace), faites glisser le fond pour
se déplacer, la molette zoome, **Fit** montre tout. Le filtre accepte une classe, une table ou un nom de champ, et `is:api`,
`is:embeddable`, `is:inheritance`.
- Un **clic** sur une boîte la montre avec ses seuls voisins (profondeur 1 à 3). Un clic sur une ligne de relation la **suit** : un pas de
plus, le chemin montré comme un fil d'Ariane qu'on peut remonter. **Show all** revient en arrière.
- Un double clic ouvre le fichier PHP à la classe ou à la propriété. Clic droit : modifier l'entité, ouvrir le dépôt, les données de la
table, comparer avec la table, une requête DQL à partir de là, DTO, copier le nom de la classe.
## Entity
![Un champ ajouté : le changement montré comme un diff avant d'être écrit](../images/doctrine-entity.png)
L'éditeur de l'entité choisie (dans la liste, ou par un clic dans le diagramme) :
- **Add a field** / modifier / supprimer : tous les types Doctrine (écrits avec leur constante `Types::` quand l'ORM ne peut pas les
déduire), un enum, `UuidType` ; la propriété, son `#[ORM\Column]` et son getter / setter dans le style de MakerBundle.
- **Add a relation**, écrite **des deux côtés** : les attributs, `@var Collection<int, X>`, la collection créée dans le constructeur (le
constructeur est ajouté s'il n'y en a pas), getters / setters, méthodes `add` / `remove` qui gardent l'autre côté synchronisé, le
setter d'un `OneToOne` inverse qui renseigne le côté propriétaire. Options : facultative ou non, ON DELETE, cascade persist / remove,
orphanRemoval, le nom de la table de jointure.
- **Rename everywhere** : la propriété, `$this->x`, ses accesseurs et leurs appels (quand aucune autre classe n'a de méthode de ce nom),
`mappedBy` / `inversedBy` de l'autre côté, les chaînes DQL (`alias.x` où l'alias est cette entité : `createQueryBuilder('p')` de son
dépôt, `FROM` / `JOIN` du DQL, `->join('p.rel', 'r')`), `findBy(['x' => …])` dans son dépôt, `{{ entity.x }}` dans Twig ; les autres
`.x` de Twig sont listés pour être vérifiés à la main.
- **Generate DTOs** : `<Entity>Input` (contraintes de validation, `applyTo()`) et `<Entity>Output` (readonly, `from<Entity>()`) des
champs choisis.
- **New entity…** : nom de la classe, table, dépôt (`ServiceEntityRepository`), `#[ApiResource]`, champs saisis comme des lignes
(`name string 120 ?`).
**Chaque changement est d'abord montré comme un diff** (un fichier ou plusieurs), et écrit par **Apply** seulement si les fichiers n'ont
pas changé depuis. Le code n'est analysé que pour les positions et modifié en y insérant du texte : tous les autres octets du fichier
restent tels quels. Après un changement, la notification propose **Make a migration**.
- **Show the table's data** l'ouvre dans SQL Results. **Compare with the table** met les colonnes que le mapping attend (champs,
champs embarqués avec leur préfixe, colonnes de jointure, le discriminant, les colonnes des sous-classes d'une table unique) à côté de
la vraie table : manquantes, en trop, un autre type, une autre longueur, précision ou nullabilité. La connexion utilisée est celle de la
fenêtre Database : celle choisie auparavant, celle dont la base est celle de `DATABASE_URL`, la seule, ou demandée (une connexion
trouvée dans le projet est proposée).
## DQL
![Le constructeur DQL : jointures le long des relations, conditions, le DQL et le code QueryBuilder](../images/doctrine-dql.png)
- **Complétion dans les chaînes PHP** : `createQuery('…')` et les méthodes du QueryBuilder (`select`, `from`, `join`, `where`, `orderBy`,
… et `$qb->expr()->…`). Après `FROM` / `JOIN` : les entités ; après `JOIN p.` : les relations ; après `alias.` : champs, relations,
objets embarqués (et `alias.embedded.`) ; ailleurs : les alias, fonctions DQL et mots-clés. Les alias viennent du DQL, de
`createQueryBuilder('p')` dans un dépôt, de `->from(X::class, 'x')` et de `->join('x.rel', 'y')`.
- **Le constructeur** : entité racine et alias, jointures le long des relations (INNER / LEFT, alias créés pour vous), alias ou champs à
sélectionner, conditions (une valeur saisie devient un paramètre ; `:name` est un paramètre sans valeur), tri, limite. Il écrit le DQL
et le code QueryBuilder (`$this->createQueryBuilder('p')` avec `setParameter()`), à copier ou à insérer au curseur.
- **Run** : `doctrine:query:dql --show-sql` via l'exécuteur de la fenêtre Console donne le SQL, exécuté sur la connexion dans SQL
Results ; **Objects (console)** montre ce que la console affiche.
## Migrations
![L'historique des migrations : exécutées, en attente, plus disponibles](../images/doctrine-migrations.png)
L'historique de `doctrine:migrations:list` : exécutées (date et heure), en attente, exécutées mais plus disponibles, la courante.
**Migrate to the latest**, **Roll back one** (`migrate prev`), **Go to this version** (vers le haut ou vers le bas), **Run up** / **Run
down** d'une migration, ouvrir son fichier, **Validate the mapping** (`doctrine:schema:validate`), **Make a migration** : le SQL dont
les entités ont besoin (`doctrine:schema:update --dump-sql`) est d'abord montré, puis `make:migration` (ou `doctrine:migrations:diff`)
écrit le fichier, qui s'ouvre. Tout passe par l'exécuteur de la fenêtre Console (le conteneur du site, ou le PHP local). Avant tout ce
qui modifie la base, une confirmation dit ce qui sera perdu ; quand la connexion est marquée **production**, son nom doit être tapé.
## Vérification du schéma de la base
Au démarrage du site (**Serve the site**, **Apply the Compose changes**), quand une entité ou une migration est enregistrée (ou écrite par l'IDE),
et quand la sortie du site (ou une réponse du client HTTP) contient une erreur Doctrine « table introuvable » / « base inconnue », l'IDE vérifie la
base en arrière-plan (jamais dans une frame) par le lanceur de la fenêtre Console : le serveur répond-il et la base existe-t-elle, des migrations
attendent-elles (`doctrine:migrations:list`), les entités et les tables diffèrent-elles sans migration (`doctrine:schema:update --dump-sql`).
Si quelque chose ne va pas, un bandeau au-dessus des éditeurs le dit en clair (« La base app n'existe pas. », « 2 migrations ne sont pas
appliquées. », « L'entité Xxxxa n'a pas de table : aucune migration ne la crée. »), avec un badge sur le widget Run et dans la barre d'état. Ses
boutons, chacun confirmé (le SQL d'abord pour une migration) avant de s'exécuter : **Créer la base** (`doctrine:database:create --if-not-exists`),
**Générer une migration**, **Appliquer les migrations**, **Ouvrir la fenêtre Doctrine**, et **Tout corriger** (créer la base, générer une migration,
l'appliquer : les étapes sont listées dans la confirmation, chacune seulement si la précédente a réussi, puis la vérification se relance).
Sur une connexion **production** (fenêtre Database, ou `APP_ENV=prod`) rien ne s'exécute tout seul, pas de « Tout corriger », et chaque correction
demande le nom de la connexion. Réglages > « Vérifier le schéma de la base tout seul » coupe la vérification automatique ; l'action
**Vérifier le schéma de la base** (Search Everywhere, l'en-tête de la fenêtre Doctrine, le badge de la barre d'état) la lance à la demande.
## Visual SQL builder (fenêtre Database)
![Le constructeur SQL visuel : des tables jointes par leur clé étrangère, un agrégat, le SQL relu](../images/sql-builder.png)
Depuis la barre d'outils de la fenêtre Database, ou le menu d'une base ou d'une table : les tables du schéma réel choisies dans une
liste, jointes par leurs clés étrangères au fur et à mesure de leur ajout (ou en faisant glisser une colonne sur la colonne d'une autre
table), des colonnes cochées dans les boîtes des tables, des agrégats (`COUNT`, `COUNT DISTINCT`, `SUM`, `AVG`, `MIN`, `MAX`) avec
alias, `WHERE` / `GROUP BY` / `HAVING` / `ORDER BY` / `LIMIT` sous forme de lignes. Le SQL s'écrit en direct et peut être modifié : un
`SELECT` simple (jointures, conditions `AND`, `IN`, `BETWEEN`, `IS NULL`…) est relu dans les lignes, tout le reste (`OR`,
sous-requêtes, fonctions) est gardé tel qu'écrit. **Run** (SQL Results ; la protection production comme dans une console), **Open in a
SQL console**, **Copy**.
## Limites
- Les annotations (docblocks `@ORM\Entity`) et les mappings YAML ne sont pas lus ; les attributs et le XML le sont.
- Rename trouve les appels par nom de méthode (ignoré quand une autre classe a une méthode du même nom) et les usages Twig par la
variable nommée d'après l'entité : l'aperçu liste ce qu'il a trouvé ; vérifiez-le.
- Les exécutions DQL et les migrations nécessitent la console du projet (`bin/console`) et sa base accessible depuis là où elle
s'exécute.
Code : `ide/src/Doctrine/` (`MappingReader`, `EntityWriter` + `PhpSource`, `Rename`, `Dql`, `MappingCompare`, `Migrations`,
`DoctrineCommands`), `ide/ui/js/doctrine.js`, `doctrine-layout.js`, `dql-model.js`, `sql-model.js`, `sql-builder.js`,
`ide/ui/css/doctrine.css`. Tests : `ide/tests/DoctrineTest.php` (fixtures `ide/tests/fixtures/doctrine/`, le code exact attendu dans
`fixtures/doctrine-expected/` — rafraîchi avec `DOCTRINE_EXPECTED_WRITE=1` —, de vraies sorties de console dans
`fixtures/doctrine-console/`), `ide/ui/js/doctrine-models.test.mjs` ; captures : `games/ide/tools/ui-doctrine-check.sh <project>`.