128 lines
11 KiB
Markdown
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]`).
|
|
|
|

|
|
|
|
## 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
|
|
|
|

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

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

|
|
|
|
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>`.
|