TR

Interactive tutorial

The IDE teaches itself: an interactive tutorial walks you through its tools on a real Symfony project, step by step. A guide panel explains each step and a ghost mouse (an extra pointer drawn over the IDE, never your real cursor) flies to the button, tab or window to look at, lights it and shows where to click.

Start it

  • Help > Symfony tutorial;
  • the Welcome screen, section Learn: "Learn the IDE with a Symfony project";
  • Search Everywhere (double Shift): "Symfony tutorial";
  • the link at the top of the documentation's index.

When you make a new Symfony project (New Project > Web site > Symfony) the IDE offers the tutorial once, right after it opens: Start the Symfony tutorial, Later, or tick Don't offer it again. That choice belongs to you, not to the project; undo it in Settings > Offer the Symfony tutorial after a new Symfony project. The tutorial stays in the Help menu anyway.

Starting it asks whether to create the test project (a fresh Symfony skeleton with the web app packages, made in Docker like New Project, in your projects folder under symfony-tutorial) or to use the open Symfony project. An existing test project is reused.

The panel

  • Contents: chapters and steps with a tick on the done ones; click a step to jump to it.
  • The step's text: what to do, why, what to look at, tips and shortcuts.
  • Previous / Next (or Alt+Shift+Left / Alt+Shift+Right).
  • Do it for me: the IDE does the step through its own commands (opens the window, creates the controller...), so you can follow.
  • Show me: the ghost mouse replays where to look and click, with a spotlight and a pulse. Nothing is clicked for real.
  • Drag the panel by its title, collapse it with the small arrow, close it with the cross. Restart the tutorial forgets the progress.

One step, one precise action

Every step points at the real control you must use, inside the tool windows (the Run button of the Console form, "+" of the Doctrine window, the blue Apply button of a dialog, "Refresh from the API" of the HTTP Client...), says exactly what to click or type and where, why, and what you should see afterwards. Long procedures are split (create an entity = open the dialog, name it, add a field, choose its type, show the change, apply).

  • Show me first opens the window or dialog the step needs, waits until the control is on screen, scrolls it into view, then flies the ghost to it with a spotlight and a click ripple. The control is looked up again at every frame while the ghost moves; the panel steps aside so that it never hides the control. If the control cannot be found the panel says so.
  • The tutorial verifies the real result before it ticks a step and moves on: the file exists (src/Controller/HomeController.php, src/Entity/Product.php), the route is declared in the controller (the routes panel), the migration file appeared, the database check says the schema matches, the HTTP request got a 2xx answer, the field you typed contains what was asked.
  • If you do something else (close a window, open another one), the panel shows a note: press Show me, the IDE reopens what is needed and points at it again. You can always press Next.

Your progress is remembered per project: close the IDE and come back, the tutorial resumes where you left.

The chapters

  1. The IDE tour: project tree, editor, tool windows, Re-index, Search Everywhere, the Doc button.
  2. Run the site (Run, Docker).
  3. The New… hub (Alt+N), the Symfony console, a controller (command wizards), the controller routes panel and completion with automatic import.
  4. Twig templates and the Twig preview ("Layout + CSS").
  5. CSS and Bootstrap editors.
  6. Doctrine entities and the diagram.
  7. The .env editor and its DSN builder.
  8. The database schema check (status bar badge, banner, "Fix everything") and migrations.
  9. The Database window: tables, SQL console, visual SQL builder.
  10. DQL in a repository.
  11. Symfony forms.
  12. Validation and 12. Security (validation and security).
  13. Events and Messenger.
  14. Installing API Platform (New… > Install API Platform), the HTTP client, OpenAPI of the local site and "Refresh from the API".
  15. Tests and coverage.
  16. Translations.
  17. Scripts and the Security audit.
  18. Where to go next: the documentation, the Board, Git.

Languages

The panel's buttons and titles are translated in the 14 languages of the IDE. The texts of the steps exist in English and French: the other languages show the English text. The panel's own messages (control not found, how to come back) are in all 14.

For authors of other tutorials

A tutorial is data: ide/ui/js/tutorial/symfony-steps.js (chapters, steps, targets, what a step waits for, "Do it for me" commands) walked by the engine tour.js. Targets are data-tour="name" attributes on the IDE's elements, including the controls inside the tool windows and dialogs (tool-<id> for the tool window buttons; a dialog button gets one with tour: 'name' in dialog({ buttons })). A step may have: before (commands that open the window or dialog when the target is not on screen), ready (what must be visible before the ghost moves), ghost (the route: [{ target, click }]), back (what to do when the user went elsewhere) and a wait that checks the real result: {exists: path}, {check: 'route:<controller file>' | 'migration' | 'schema-ok' | 'http-2xx' | 'visible:<target>' | 'text:<selector>~<regex>'}, {value: {target, match}} (a field the user types into), {click: target}, {tool}, {action}, {opened}, {saved}. "Do it for me" commands add {click: target} and {fill: {target, value}}. A test checks that every target, command, precondition and wait of a tutorial exists in the UI code.

To try the whole path in the real IDE on a Symfony project (a copy of yours), on a virtual screen: games/ide/tools/ui-tour-check.sh <project> <out dir> <step id>... (one screenshot per step, with where the ghost points). The steps that need Docker (the running site, MariaDB, API Platform's HTTP answers) are not exercised by that container: try them on your computer.