FR

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

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

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

  • 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

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

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