11 KiB
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éthodesadd/removequi gardent l'autre côté synchronisé, le setter d'unOneToOneinverse 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/inversedByde l'autre côté, les chaînes DQL (alias.xoù l'alias est cette entité :createQueryBuilder('p')de son dépôt,FROM/JOINdu DQL,->join('p.rel', 'r')),findBy(['x' => …])dans son dépôt,{{ entity.x }}dans Twig ; les autres.xde 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èsFROM/JOIN: les entités ; aprèsJOIN p.: les relations ; aprèsalias.: champs, relations, objets embarqués (etalias.embedded.) ; ailleurs : les alias, fonctions DQL et mots-clés. Les alias viennent du DQL, decreateQueryBuilder('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 ;
:nameest un paramètre sans valeur), tri, limite. Il écrit le DQL et le code QueryBuilder ($this->createQueryBuilder('p')avecsetParameter()), à copier ou à insérer au curseur. - Run :
doctrine:query:dql --show-sqlvia 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>.




