Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01JkYTqsvYu6AYr9yQ3Q4Nt6
946 lines
111 KiB
Markdown
946 lines
111 KiB
Markdown
# JumPHP IDE
|
||
|
||
[Français](ide.fr.md)
|
||
|
||
**Using the IDE**: one page per feature, with screenshots, in [docs/ide/](ide/index.md) (French: [docs/ide/fr/](ide/fr/index.md)); inside the IDE, the **Doc** button
|
||
at the top right (Help > Documentation). This page is the overview for the IDE's developers.
|
||
|
||
An IDE for JumPHP projects (games, desktop apps, hybrid games, Amstrad CPC remakes, ports), **written in PHP**, that
|
||
works the same way **as a native app on your computer** and **on the web** (`jumphp.net/ide`). It edits your real
|
||
projects: you sign in with jumphp.net, it lists your projects (your Git repositories), clones them, and pushes your
|
||
commits.
|
||
|
||
```
|
||
ide/ the package jumphp/ide: the PHP core + the interface (HTML / CSS / JS, Monaco)
|
||
src/ JumPHP\Ide\: Workspace, Php (index, code intelligence), Search, Git, Run, Project, Ide (commands)
|
||
ui/ index.html, css/, js/ (app, editor, tree, search, git, run, welcome, designer, backend), img/
|
||
tools/ fetch-vendor.sh (Monaco and xterm.js into ui/vendor/, not in git), icon.php
|
||
tests/ PHPUnit (the core: completion, definition, usages, rename, problems, search, Git, workspaces)
|
||
games/ide/ the desktop app (Tauri, docs/tauri.md): Main (session, projects, dispatch), Playground (API),
|
||
Loopback (sign-in), Creator (New Project); pages = vendor/jumphp/ide/ui
|
||
```
|
||
|
||
## Features
|
||
|
||
| | |
|
||
|---|---|
|
||
| **Editor** | Monaco (the editor of VS Code): tabs, preview tabs, split right, sticky scroll, multi-cursor, minimap (option), diff, autosave, dark / light themes |
|
||
| **Config completion** | `config/project.yaml` (every key with what it does, scenes of the project, languages, key names...) `config/input.yaml` (actions, key / pad / touch / mouse names) `config/services.yaml` (`_defaults`, a service's keys, the project's classes), `config/lang.yaml` (the languages, then the texts another language has and this one not yet) and the forms (`*.form.yaml`: a widget's settings, their values, its events); in PHP, the game's texts in `t('…')` (config/lang.yaml) and its actions in `isPressed('…')`, `isHeld('…')`... |
|
||
| **PHP code intelligence** | completion that follows types (`$this->engine->config->`, return types, `@var`, `@property`, `@method`, generics: `list<Foo>`, `@template` classes `Box<Foo>` and their `@extends`, `class-string<T>` factories, `foreach` over collections, array shapes `array{hero: Foo}` and their keys), the libraries' classes, functions (`use function` added) and classmaps (Composer's vendor/), the extensions' stubs, auto-import (`use`), parameter hints, go to declaration / implementation, find usages, rename (classes, methods, properties, constants, variables; a class renames its file), quick documentation, file structure, problems (syntax errors, unknown classes / methods / functions), breadcrumbs, highlight of the symbol under the cursor |
|
||
| **Navigation** | Search Everywhere (Double Shift: classes, files, symbols, actions, `:line`), Run Anything (Ctrl twice: a `bin/jumphp` command, its commands and the project's games completed, Enter runs it), go to file / class / symbol, recent files, find / replace in files (case, words, regex, file masks), back / forward (also the mouse's back / forward buttons) |
|
||
| **Git** | Commit tool window (changes, unversioned files, check boxes, amend), diff with HEAD, commit and push, update (pull), branches (checkout, new, merge, delete), stash, log with the files of each commit and their diff, annotate (blame), rollback; **log menu** (right click a commit: new branch, tag, cherry-pick, revert, reset soft / mixed / hard), **Git Remotes…** (add, change, remove), **Git Tags…** (make, push, delete), **Git Stashes…** (apply, pop, drop), branch rename and delete on the server, push with `--force-with-lease`, **Git Credentials…** (desktop: a user and a token for any https host, GitLab or a company's server; GitHub comes from the jumphp.net sign-in, one account per project), and a message saying what to do when git cannot sign in; the log draws the branches' **graph**, **Stage by Change…** (a file's hunks one at a time), **By block…** in a merge (each conflict: ours, theirs or both), **Git Submodules…**, **SSH Keys…** (desktop: the keys of ~/.ssh, generate an ed25519 key, copy the public key, test `ssh -T`) |
|
||
| **Run** | the run configurations of the project (`bin/jumphp run / test / shot / build / webshot / serve / export / lint`, per game or app, plus `.jumphp/run.json`), Run tool window with live output, clickable `file:line`, test results (PHPUnit testdox) as a tree, screenshots opened in a tab |
|
||
| **Tests** (bottom) | the project's tests as a tree, found by reading the files (PHPUnit suites, files, classes, methods, data sets; Pest; JumPHP game tests; `*.test.mjs` with node --test, Vitest, Jest), run all / a suite / a file / a class / a method / a data set / the failed ones / the test at the cursor (`Ctrl+Shift+F10`), ▶ in the editor's gutter coloured by the last result, live results, expected / actual side by side, the stack's links, the test's output, a game test's filmed frames, the last runs, code coverage in the gutter. See [Tests](#tests) |
|
||
| **Scripts** (desktop, right tool bar) | the project's own scripts (a shell body with `${file}`, `${selection}`, `${input:Label}`…, an icon, a shortcut; `.jumphp/scripts.json`, or `.jumphp/scripts.local.json` for this computer only) and the tasks it already has (Makefile targets, Castor tasks, composer.json / package.json scripts, justfile, Taskfile); each one pinned to the tool bar, bound to a key, a run configuration, run on save / on open / before a run (once the project is trusted); Castor installed after a yes and checked against its release's SHA256SUMS, Castor tasks written into castor.php. See [Scripts](#scripts) |
|
||
| **Symfony Events, Messenger** (desktop, right tool bar, Symfony projects) | **Events**: the event picked from a searchable list (the framework's: kernel, security, forms, console, Messenger workers, Mailer, Doctrine lifecycle, with their event class and constant; the project's own: event classes of `src/` and what it dispatches), then an EventSubscriber, an `#[AsEventListener]` listener, a Doctrine `#[AsDoctrineListener]` / `#[AsEntityListener]` listener written (or a method added to an existing class), a new project event with its dispatch inserted in a method; who listens to what in which order, from the code or from `debug:event-dispatcher`. **Messenger**: workers started / stopped / restarted with their live output, queues (`messenger:stats`, failed messages retried / removed, Scheduler), transports and routing of `messenger.yaml`, messages and handlers. Every change a diff first. See [Symfony Events and Messenger](#symfony-events-and-messenger) |
|
||
| **Terminal** (desktop) | `Alt+F12` (View > Terminal): shells in the project's folder, one tab each (`+`). Linux / macOS: your shell (`$SHELL`) in a pseudo-terminal: colours, prompts, Ctrl+C, full-screen programs, its size follows the window; the keys go to the shell (only `Alt+…` reaches the IDE), copy / paste with `Ctrl+Shift+C / V`. Windows: `cmd.exe` (`JUMPHP_IDE_SHELL=powershell` for PowerShell) on pipes: the line is edited in the IDE, then sent |
|
||
| **SSH** (desktop, right tool bar) | your servers with the computer's own `ssh` / `scp` (your `~/.ssh/config`, keys, agent, `known_hosts`): add / edit / remove, import the hosts of `~/.ssh/config`, test the connection; **a session** in a Terminal tab (prompts, passwords, vim, colours; Windows: a console window), **the files**: browse, new folder, rename / move, copy, delete, upload (a file, a folder, files dragged from the Project view or the file manager) and download with scp and its progress (or drag remote files to the file manager / the Project view), a remote file opened in the editor and saved back. See [SSH](#ssh) |
|
||
| **Database** (desktop, right tool bar) | the project's MySQL / MariaDB and SQLite databases (after jumphpsql): connections saved in `.jumphp/databases.json` (never a password), found in one click from `.env` `DATABASE_URL`, Laravel `DB_*`, Docker Compose services and the JumPHP web site; a tree of databases, tables, views, routines, columns, indexes and foreign keys; **SQL consoles** in the editor (Ctrl+Enter runs the statement under the cursor, completion of tables and columns from the live schema), results with pages, sort, filter, export (CSV / JSON / SQL); a table's rows edited in place (UPDATE / DELETE / INSERT shown, then run in one transaction); SSH tunnels through the SSH window's servers; a **production** connection is red and asks before any write. See [Database](#database) |
|
||
| **Doctrine** (bottom tool bar, Doctrine projects) | the entities read from their attributes / XML: a **diagram** (relations with their sides and cardinalities, inheritance, embeddables, enums; pan / zoom, filter, focus and follow the relations, double click opens the code), an **entity editor** (fields of every type, relations written on both sides, rename everywhere with a preview, DTOs; every change a diff first), **DQL** (completion in PHP strings, a visual builder writing DQL or QueryBuilder code, run into SQL Results), the mapping **compared with the real table**, **migrations** (history, migrate / roll back / one up or down, diff with its SQL shown first, production guard). The Database window gets a **visual SQL builder**. See [Doctrine](ide/doctrine.md) |
|
||
| **API Platform** (bottom tool bar, projects requiring `api-platform/core`) | the API read from the attributes: `#[ApiResource]` **on / off** and its options in forms (short name, operations with their own options, subresources with `uriTemplate` + `uriVariables`, formats, pagination, order, security, validation / serialization groups, provider / processor / input / output), a **property grid** (serialization groups as read / write columns, `#[ApiProperty]`, `#[ApiFilter]` with the strategy), **State Providers / Processors** made from templates and wired, the **routes** from the code compared with `debug:router`, and the **HTTP Client requests** of every resource made and refreshed (one `.http` per operation, example bodies, filters, JWT login; a request you edited is never overwritten). Every change a diff first, only the touched arguments edited. See [API Platform](ide/api-platform.md) |
|
||
| **Local History** (desktop) | File › Show Local History (also the right click of an editor tab or of a file in the Project view): the versions of a file the IDE kept on this computer, without git: one at each save, and one when the file changed outside the IDE (Claude Code, a terminal, git) before the IDE saves or opens it again. **Compare** (a diff whose right side is the file, editable) or **Revert** (one change in the editor: Ctrl+Z takes it back). Kept in `.jumphp/history/files/` (not in git): the 60 newest versions of each file, 60 days at most, text files up to 1 MB |
|
||
| **Debugger** (desktop) | Xdebug: click in the gutter left of a line of PHP for a breakpoint (right click: a condition, `Ctrl+F8` at the caret), **Debug** (`Shift+F9`, the bug beside Run) runs the selected configuration with `JUMPHP_XDEBUG=<port>` (`bin/jumphp` then starts PHP in the desktop image with Xdebug, which connects back to the IDE; phpstan, `php -l` and composer run without it). Where it stops: the line marked, the **Debug** tool window with the stack (click a frame), the variables as a tree (read lazily), watches, an expression evaluated there, a variable given a new value (double click or `F2`: a PHP expression); Resume `F9`, Step Over `F8`, Into `F7`, Out `Shift+F8`, **Run to Cursor** `Alt+F9`, Stop. **Stop at Exceptions…** (the ⚠ of the Debug window): `*` or class names, it stops where one is thrown, caught or not, and says which with its message. Breakpoints are kept per project and follow their lines as you edit. Best with headless runs (`shot`, `test`): a game stopped in a window freezes until you resume. **Two engines**, Xdebug by default and [PHP Debugger](https://php-debugger.dev) (DBGp too, near-zero overhead, much faster): **Debug with…** (right click on the Debug button, or the action) picks one for that run and can make it the default; from a terminal `JUMPHP_DEBUGGER=php-debugger` (PHP 8.2-8.5; the async runtime keeps Xdebug) |
|
||
| **Visual HTML / CSS editor** | `.html` files: Code / Split / Design. Components (drag and drop), layers, inspector (attributes, classes, inline styles), the CSS rules of the linked stylesheets (edited in place), devices (desktop, tablet, phone), undo / redo; the HTML is kept as written (scripts, head, comments). For desktop apps' pages (`games/<app>/ui/`) and game sites (`games/<id>/site/`) |
|
||
| **Visual CSS / SCSS editor** | `.css` / `.scss` files: Code / Split / Design / Preview (the buttons at the bottom right). **Design**: the rules of the file on the left (a tree: `@media` / `@supports` / `@container` / `@layer` groups, `@font-face`, `@keyframes` and their frames, SCSS nesting, `%placeholders`, `@use` / `@forward` / `@include` / `@mixin`; filter, add, duplicate, delete, move up / down with Alt+↑ / ↓), the file's `--custom-properties` and `$variables` with their colour; an **inspector** of the selected rule, grouped like a design tool: Layout (display, flex direction / wrap / justify / align drawn as small pictures, grid columns with presets and their tracks drawn, gap), Box (a box-model widget for margin / border / padding, corner radius), Size, Position, Typography (family, size, weight, line-height, letter-spacing… and a preview in that font, `@font-face` of the file loaded), Colours & backgrounds (colour pickers: hex / rgb / hsl / oklch / named, alpha, the project's colours, the colour variables, the 148 named colours; a gradient editor), Effects (shadow editor, opacity, filter, transform, transition), Other declarations (free name / value with completion); numbers change with the arrows or by dragging their label (Shift ×10, Alt ×0.1), `!` toggles `!important`, ✕ removes. Each change rewrites only that declaration (one edit of the text: Ctrl+Z takes it back, comments and formatting stay); the text stays the source: typing in the code redraws the panels (Split also follows the cursor). The **preview** (the sample page or a page of the project) outlines what the selected rule matches; a click on an element lists the rules that apply to it, the strongest first, with their specificity. **SCSS** is compiled by a real dart-sass (the project's `var/dart-sass/sass`, else `sass` on the computer, else the `sass` npm package in Docker `node:22-alpine`, cached in the volume `jumphp-sass`): its errors at their line (in the panel and as markers in the code) and the compiled CSS in the preview; the editor edits the SCSS itself. **In the code**: a colour swatch beside every colour (named ones and `var(--x)` / `$x` holding a colour, also from the project's other stylesheets), a click opens Monaco's picker (a variable's swatch changes its definition). `ide/ui/js/css-model.js` (parser and edits, `node --test ide/ui/js/css-model.test.mjs`), `css-designer.js`, `css-colors.js`, `ide/src/Css/SassCompiler.php` (`css.sass.compile`); `games/ide/tools/ui-css-designer-check.sh` checks it in the real IDE |
|
||
| **Bootstrap editor** | `.html` / `.twig` files of a page or project that uses Bootstrap (detected from the page's links and `data-bs-*`, `package.json`, `importmap.php`, the base template): in **every mode** the code gets Bootstrap checks (col outside row, row outside container, parts outside their component, unknown / misspelled classes with a suggestion, Bootstrap 4 classes and `data-toggle`... with quick fixes and **Convert the whole page to Bootstrap 5**, `data-bs-target` without id, duplicate ids, accessibility, nested interactive elements) as markers and in Problems, class completion in `class="…"` (HTML and Twig) and hover docs; the **Bootstrap** mode shows the page with Bootstrap's CSS (click an element to select it) with a **Components** palette (navbar, grid, card, forms, modal, offcanvas, accordion, carousel, tabs, toast... ids / aria / data-bs wired; click or drag onto the page), a **Utilities** inspector (spacing box, grid sizes per breakpoint, display, flex, text, colours, borders, shadow, position, sizes: each change is one edit of the class attribute, Twig kept, one undo), **Problems** and **Ask the AI** (hero, contact page, convert, make responsive: Claude / OpenCode / chat model through `bootstrap.ai`, shown as a diff to accept). `ide/ui/js/bootstrap-*.js` (`node --test ide/ui/js/bootstrap.test.mjs`), `tools/bootstrap-catalog.mjs` (class lists from the real stylesheets), `ide/src/Bootstrap/Assistant.php`; `games/ide/tools/ui-bootstrap-check.sh` checks it in the real IDE; docs/ide/bootstrap.md |
|
||
| **Play** | green Play in the editor's and the Project view's context menus (`Ctrl+Shift+F10`): a `src/Scene/*.php` starts the game in that scene, a `tests/*Test.php` runs only its tests (results as a tree in Run), else the whole game. Web: the **Game** window (right or bottom) with ⚡ Live reload and the game's console |
|
||
| **YAML, Docker Compose** | every `.yaml` / `.yml` coloured as YAML is (keys, anchors / aliases / `<<`, tags `!php/const` `!tagged_iterator`, block scalars, `${VAR:-default}`), its problems as one types (syntax with line and column; compose files: unknown keys, a service without image nor build, ports / volumes / environment / restart, `depends_on` / networks / named volumes nobody declares; Symfony's `config/services.yaml`), completion (Compose keys and values, ready-made services under `services:`, `image:` names and tags from Docker Hub), hover on `image:` (Docker Hub's description, stars, pulls), folding, outline (Structure, `Ctrl+F12`). Docker window > **Compose**: the project's compose files per folder, create the override, Add a service (templates), Check (`docker compose config`, errors in Problems), Apply; Docker Hub tags "Insert into the editor". docs/web.md "Customising the stack" |
|
||
| **YAML navigation** | in any `.yaml` / `.yml`: `Ctrl+click` / `F12` goes to the definition, `Shift+F12` / `Alt+F7` lists the usages (on a declaration, Ctrl+click lists them too), hover shows the definition, values that lead to one file are underlined links, `Shift+F6` renames. YAML itself: an alias `*x` → its anchor `&x` (per document of a multi-document file), the hover of `<<: *x` shows the merged keys, an anchor renamed with its aliases. Symfony's `config/`: `imports` / `resource` / `exclude` (globs, `{a,b}`, `%kernel.project_dir%`) → the files (a folder: its files), a class (service key, `class:`, `controller: App\Controller\X::method`, messenger routing...) → the class or method, `@service` / `!service` / `alias:` → its definition (`config/**.yaml`, `#[AsAlias]`), `%parameter%` → `parameters:`, `%env(X)%` → the `.env*` lines, `!tagged_iterator tag` → the tagged services, `factory: ['@x', 'm']` / `calls: - method:` → the PHP method, `!php/const` / `!php/enum` → the constant or case, security `provider:` → `providers:`; `translations/*.yaml` keys ↔ `'key'\|trans` / `->trans('key')` in Twig and PHP, both ways. Compose: `extends` (file, service), `env_file`, `build` context / dockerfile, volume host paths, `configs` / `secrets` files, `depends_on` / `links` / `networks` / named volumes / configs / secrets ↔ their declarations (the compose files of the folder; renamed together). JumPHP: `start_scene` / `smoke.scene` / `main` → the class, asset paths → the files, `config/input.yaml` actions ↔ `isPressed('…')`, `config/lang.yaml` keys ↔ `Lang::t('…')`, menu labels and form texts, a form's `events: {click: onX}` → the method of `src/Form/<Name>.php`; workflows' `uses: ./…` → the local action. From PHP / Twig, Ctrl+click on such a string opens its YAML. `JumPHP\Ide\Yaml\YamlNavigation` (commands `yaml.definition`, `yaml.references`, `yaml.hover`, `yaml.links`, `yaml.rename`), `ide/ui/js/yaml-nav.js` |
|
||
| **Symfony Forms** (desktop and web, right tool bar, projects with `symfony/form`) | the project's FormTypes in a **form builder**: fields added from Symfony's types and the project's own (sub-forms), dragged to reorder, removed; each type's options edited by kind (label, required, help, attr, constraints with their options, choices, an EntityType's class and query_builder, a CollectionType's entry_type / allow_add / allow_delete / by_reference / prototype, dates' widget / html5…), configureOptions, form events (listener methods made), data transformers (classes made); **Add fields from the class** (Doctrine mapping, PHP types, relations → EntityType); a **preview** without PHP in the project's page with the default, table, Bootstrap 5 or Tailwind 2 theme and **Show errors**; Save writes back only what changed; **Generate** the controller action and its Twig template; twig.yaml's form_themes. Every change a diff first. See [Symfony forms](ide/symfony-forms.md) |
|
||
| **Symfony Validation, Security** (desktop and web, right tool bar, Symfony projects) | **Validation**: the constraints of an entity / DTO as chips per property (attributes, and config/validator YAML / XML beside, read-only), added / edited / removed / reordered from Symfony's whole catalogue with their options by kind, Doctrine suggestions, groups and GroupSequence, a custom constraint wizard, "Test a value" through the project's validator. **Security**: security.yaml as forms (firewalls, authenticators, providers, hashers, role graph, access_control with a tester), routes x roles, `#[IsGranted]`, generators (user, login form, registration, reset password, voter, authenticator, JWT), `debug:firewall`, warnings. Every change a diff first. See [Symfony Validation and Security](ide/validation-security.md) |
|
||
| **Hierarchy, libraries** | Hierarchy tool window (`Ctrl+H`): the class's ancestors as a tree, the classes under it; External Libraries in the Project view (the engine, vendor packages), read only |
|
||
| **Plugins** (desktop) | PHP plugins (docs/ide-plugins.md): actions (menus, Find Action, shortcuts), tool windows, run configurations, completion and problems for the files they choose, listeners, timers, **tools for Claude** on the IDE's MCP server (`mcp__jumphp-ide__plugin_<id>_<name>`); Tools › Plugins… installs (a folder, the project's own plugins, [jumphp.net/ide-plugins](https://jumphp.net/ide-plugins); publishes there too), enables, removes them; `bin/jumphp plugin:new` makes one, tested without a window (PluginTestCase) |
|
||
| **Claude** | desktop: the Claude tool window (`Alt+8`) talks to the Claude Code of your computer (`claude -p` in the project's folder): its answers, the files it reads and edits (click to open), the commands it runs, as they come; the conversation goes on; what it may do (a selector, Shift+Tab in the box changes it): auto mode, edit files, plan only, ask, full auto; when it asks for a permission, a dialog lets you allow it once, for 5 / 15 minutes, 1 hour, the session or always, for that kind of command or for everything (⚙ > Forget the permissions given). "Ask Claude about the Selection" in the editor's menu. A context 80 % full is compacted (`/compact`) by itself; the Context / 5 h / Week gauges follow in real time. Each turn of Claude or OpenCode is also written in the project's `IA/HISTORY/<CLAUDE\|OPEN CODE>/<model>/<dd-mm-YYYY HH-MM-SS>/<request>.md` (`IA/` goes into `.gitignore`: never sent to git, so it is lost with the computer). OpenCode's permissions follow the mode (it cannot ask). A missing git / Docker / Claude Code / OpenCode: the error notification has an **Install** button (winget, Homebrew, pkexec + the package manager, else the download page). Create its Git repository: on "Bad credentials" a **Sign in again** button signs in and retries |
|
||
| **Claude: tabs, windows, history** | a tab per conversation: `+` starts another one and the others go on (each its own Claude Code process); right click on a tab: **Open in a Window** (the conversation goes on in a window of its own; closing that window brings it back as a tab), Rename, Copy as Markdown, Close. Every conversation is kept in the project, `.jumphp/history/claude/<id>.json` (a `.gitignore` keeps `.jumphp/history/` out of git): the **History** tab lists them, newest first; one clicked opens again in a tab and goes on where it was (`--resume`) |
|
||
| **Claude, seen working** | the eye of the Claude window (**Follow**, on by default): the IDE shows what Claude does as it does it. The file it reads opens at the lines it reads (blue), what an edit replaces is marked before (orange) and what it wrote after (green), its commands appear in the Run window with their output, its searches in Find, its plan (TodoWrite) above the conversation, the file in the Project view. The keyboard stays in the Claude window and nothing moves while you type in an editor |
|
||
| **Step by step** | the Claude window's mode **Step by step** (Shift+Tab, or the ⚙ menu): Claude Code asks the IDE before every Edit / MultiEdit / Write and nothing is written until you answer. The file opens at the change, what Claude removes in **red**, what it adds in **green** under it, each block with its own tick. The step's card in the conversation shows the request that led to it, a message field ("not that way: ...", sent to Claude with a refusal) and **Accept** / **Decline** (**Apply the ticked blocks** when a MultiEdit has several). You can also write to Claude while it waits. An accepted step stays in the conversation with **See the diff** and **Roll back**: each step is undone on its own, what came after it stays (if the file changed in the same place, the IDE says so and touches nothing). Commands and web pages still ask in their own dialog |
|
||
| **Claude and jumphp.net** | the Claude window checks that Claude Code has jumphp.net's MCP server (`jumphp`: your projects, publishing, tests on jumphp.net, players' feedback, notes); when it is missing, a banner connects it in one click (`claude mcp add --scope user jumphp https://jumphp.net/mcp`, with the IDE's own sign-in as the token: signing in first if needed). Also Find Action › Connect Claude to jumphp.net |
|
||
| **Claude drives the IDE** | the IDE gives the Claude it starts its own tools (an MCP server, `jumphp-ide`, see below): open a file, point at lines with a note, show a diff or a tool window, run a run configuration in the Run window and read its result, play a scene, the problems of a file, what you are looking at (open files, cursor, selection), ask you a question in a dialog, a notification |
|
||
| **Claude on the web** | jumphp.net/ide uses the Claude Code of your computer: `bin/jumphp claude:connect` (or the account menu › Claude for jumphp.net) opens the JumPHP IDE, authorized once in the browser; it takes the web IDE's messages, runs Claude on a copy of the project with your drafts (`~/.cache/jumphp/claude-bridge/`), streams the answer back, and the files Claude changed become drafts |
|
||
| **Language** (selector at the bottom of the welcome screen, in the News tab and in Settings) | the welcome screen and the news change language at once (the 13 languages besides English: `ide/ui/js/i18n/<code>.js`, `t()` in ui.js); the rest of the IDE is English for now |
|
||
| **News** (welcome screen) | the latest news of JumPHP (jumphp.net/nouveautes, in the user's language: the system's by default, or the one chosen in Settings / on the tab, among jumphp.net's 14) and the IDE's own updates: its version, Check for updates, Download and install, Restart now |
|
||
| **Projects** | sign in with jumphp.net, your projects, clone, open a folder, clone any repository, New Project: game, graphic / mobile / desktop / CLI app, IDE plugin, hybrid game, Amstrad CPC remake (`.dsk` kept local), port of an open-source game — a game or an application is made **on this computer only** (the template cloned, the skeleton of its kind, one commit; no account needed, nothing created on GitHub or jumphp.net: a project made to try the IDE leaves no trace online); a project of the welcome list has a trash (its folder; an unchecked box also deletes its GitHub repository and jumphp.net project); `.md` files open rendered (View / Edit / Edit + View, the project's pictures included); several GitHub accounts (account menu > Add another GitHub account…, one assigned to each project); **Publish** (or **Create its GitHub repository…**) then makes the public repository on the user's account, commits and pushes everything and puts the project on jumphp.net; an **engine extension** is made on this computer too (the package `extensions/<id>` and its example game `games/<id>-demo`), and **Publish extension** (with a Packagist user name and API token it also makes / updates the Packagist package and tells jumphp.net to refresh its directory) puts the package, under `<your login>/<id>`, in its own GitHub repository `jumphp-<id>` (made the first time, tagged `v<version>`) for Packagist (submit once; jumphp.net's "My extensions" page and directory list it); an IDE plugin gets its repository at once; JumPHP stays the `jumphp` remote, fetch-only |
|
||
| **JumPHP kept up to date** | when a JumPHP project opens, the IDE brings its JumPHP files (bin/jumphp, the engine, tools, docker, skeletons, docs) to JumPHP's newest, never `games/` nor `README.md`: at once when you did not change them, else it asks (the files named; keep your changes or replace them). The commit they come from is kept in `.jumphp/jumphp.json` (commit it). `bin/jumphp update` does the same from a terminal for projects with their own history |
|
||
| **Games kept alone** | a repository holding only the game (`config/project.yaml` at its root, `composer.json` → `../../engine`) runs too: the IDE keeps its own JumPHP clone (the toolkit, in its data folder), links the game into it as `games/<id>` and runs `bin/jumphp` there |
|
||
| **jumphp.net** (`Alt+J`, desktop) | the game's project on jumphp.net: publish (push + sync), its settings (title, descriptions, category, listed), statistics and players' messages, make its web site (`bin/jumphp site:new`), build the executables (Windows, Linux, macOS, Android) and put them on its page, the installer hosted on jumphp.net (it installs the newest version sent, with shortcuts and updates), or **Run > Create an Installer…** (also in Find Action): choose the systems (Windows, Linux, macOS) and where it goes — jumphp.net, a GitHub release of the project's repository, another web site (a `dist/installer/` folder to upload at the address given; `bin/jumphp installer`), or standalone (the game inside each installer: no site, no network; `bin/jumphp installer --standalone`) — then the links to give, the Android and Apple apps with the store steps one by one (links to Play Console, App Store Connect…) |
|
||
|
||
PhpStorm's keyboard shortcuts: Double Shift, Ctrl twice, `Ctrl+N`, `Ctrl+Shift+N`, `Ctrl+E`, `Ctrl+B`, `Ctrl+Alt+B`, `Alt+F7`, `Shift+F6`,
|
||
`Ctrl+F12`, `Ctrl+P`, `Ctrl+Q`, `Ctrl+Shift+F` / `R`, `Ctrl+K`, `Ctrl+Shift+K`, `Ctrl+T`, `Shift+F10`, `Ctrl+Shift+F10`, `Ctrl+F2`, `Shift+F9`, `F7` / `F8` / `F9`, `Ctrl+F8`,
|
||
`Ctrl+D`, `Ctrl+Y`, `Ctrl+W`, `Ctrl+Alt+L`, `Alt+1/0/3/4/6/7/9`, `Ctrl+Alt+Left/Right`, `Alt+Insert`… (Help > Keyboard Shortcuts).
|
||
|
||
**Cryo window** (right stripe, snowflake; ext-cryo, [cryo.md](cryo.md)): *Live*: turn on "Run with memory metrics" and run
|
||
the game or app (bin/jumphp passes `JUMPHP_CRYO_METRICS=47830`, the engine serves ext-cryo's metrics there): memory over
|
||
time, live objects, GC, and a **Snapshot** of the running program into `var/cryo/`. *Files*: the project's `.cryo`
|
||
snapshots (what retains memory per class, allocation sites, biggest retainers, duplicates, objects kept by cycles, leak
|
||
heuristics; tick two of them to compare: what grew, and the line that keeps it), `.cryf` freeze files (header, can it be
|
||
thawed here) and `.cryom` series; click a class or a node: *why is it alive* (the paths from a root); *Explain* a growing
|
||
site: its code and the line that keeps its objects. *Save points* (Live): **Freeze here** freezes the **whole program**
|
||
with ext-cryo (`JumPHP\Cryo\ProcessFreeze`: every object reachable from the globals and statics, the game loop and
|
||
its timers, the level, the player...; whatever the game, no code of it involved) into `var/cryo/savepoints/`;
|
||
**Resume here** runs it again exactly there (`JUMPHP_CRYO_THAW`): the window, the SDL renderer, the textures (made
|
||
again from their recipe: file or picture; render targets come back blank and are redrawn), the fonts, the sounds and
|
||
the music playing, the gamepads are made again; other resources (files, sockets) come back closed. The scene alone is
|
||
frozen next to it (`hotState()` of a `HotReloadable` scene, else its plain properties): it is resumed when the whole
|
||
program can not be (the code changed since, the game uses OpenGL). Each save point says which (*whole program* /
|
||
*scene only*).
|
||
Runs with metrics also record allocation sites (`cryo.track_alloc=site`) and live class counts. *Sandbox*: PHP run in an isolated `Cryo\Sandbox` (timeout, memory limit). Files are read
|
||
and sandboxes run by the IDE's `cryo-tool.php` (copied into `var/cryo/`) in the desktop runtime; Live and save points need the
|
||
project's JumPHP 0.5.68 or newer. Claude has the same as tools: `cryo_inspect`,
|
||
`cryo_diff`, `cryo_why`, `cryo_live`, `cryo_freeze`, `cryo_sandbox`.
|
||
|
||
Windows without Docker Desktop: the IDE finds Docker Engine inside WSL and runs bin/jumphp there
|
||
([windows-wsl.md](windows-wsl.md)).
|
||
|
||
## Tests
|
||
|
||
The **Tests** tool window (`ide/ui/js/tests.js`, the PHP side `ide/src/UnitTests/`) shows the tests of the project without running
|
||
anything: `TestDiscovery` reads `phpunit.xml` / `phpunit.xml.dist` / `phpunit.dist.xml` (its `<testsuite>`s: folders, suffix, files,
|
||
exclusions), the test classes with nikic/php-parser (`test*`, `#[Test]`, `@test`, `#[DataProvider]` / `@dataProvider`, `#[TestWith]`,
|
||
a parent chain reaching `GameTestCase` = a game test), Pest's `test()` / `it()` / `describe()`, and JavaScript tests (`*.test.mjs`...: Vitest or Jest when
|
||
`package.json` names them, else `node --test`). A JumPHP game / app with a `tests/` folder, a folder of the repository with its own
|
||
configuration (`engine`, `ide`) and the root project are each a scope.
|
||
|
||
Running (`TestCommand`), the project's way:
|
||
|
||
| Project | Command |
|
||
|---|---|
|
||
| a JumPHP game / app, `engine`, `ide` | `bin/jumphp test <id or folder> --phpunit <args>` (only PHPUnit, in the runtime image; game tests filmed with `JUMPHP_FILM`); a game in its own repository through the IDE's copy of JumPHP |
|
||
| a web site / any PHP project, runner Docker (default) | `bin/jumphp web:composer <root> exec -- php vendor/bin/phpunit …` (tools/web.sh: the site's running PHP container, else a throwaway one of its PHP image) |
|
||
| the same, runner Local (`.jumphp/web.json` `"runner": "local"`, `"local_php"`) | the computer's PHP |
|
||
| JavaScript | `node --test` with the IDE's reporter `node-teamcity.mjs` (the computer's node, else `node:22-alpine` in Docker), `npx vitest run` (JUnit), `npx jest --json` |
|
||
|
||
PHPUnit / Pest print TeamCity messages (`--teamcity`, read live: the tree turns green / red as the tests end) and write a JUnit
|
||
report (the output each test printed) into `<scope>/var/ide-tests/` (a `.gitignore` there keeps it out of Git). A failed
|
||
comparison shows expected and actual side by side; the stack's `file:line` open the file. **Coverage** (the ✓ button, or a
|
||
row's menu): Xdebug in coverage mode (JumPHP projects: the Xdebug image through `JUMPHP_PROFILE_MODE=coverage`; web sites: the
|
||
web image's Xdebug with `XDEBUG_MODE=coverage`), a Clover report read into green / red bars in the editor's gutter, the
|
||
percentage per file in the tree. A game test's frames (`var/ide-tests/film`, one picture every 4 frames) and its last frame
|
||
(`var/screenshots/tests/`) are played in the window. The summary bar shows passed / failed / skipped, the time, the coverage and
|
||
the last 10 runs (click one to see its results again). Filters: failed, slow (≥ 500 ms). The clock button reruns the last tests
|
||
whenever a file is saved. Tests: `ide/tests/UnitTestsWindowTest.php`, `ide/ui/js/tests-model.test.mjs`.
|
||
|
||
Limits: Pest's test names are guessed from the code (`it ...`, `` `describe` → ``) and not tried on a real Pest project; JavaScript
|
||
has no coverage; PHPUnit 12+ ignores `@test` (such a method stays "not run").
|
||
|
||
## Scripts
|
||
|
||
The **Scripts** window (right tool bar, the ⚡; also Tools › Scripts, New Script…, New Castor Task…) lists, per project:
|
||
|
||
- **The project's own scripts**, a little like a Makefile or [Castor](https://castor.jolicode.com) made in the IDE. Each one: a
|
||
name, an icon (one of the IDE's or an emoji), its commands (a shell script, several lines, edited with Monaco), where it runs
|
||
(a **Terminal** tab: interactive; the **Run** window; or **in the background** with a notification at the end), a working folder
|
||
in the project, an environment (`NAME=value` lines, taken literally), **Ask before running**, and for the sites of
|
||
`bin/jumphp web:*` **Run in the site's PHP container** (`docker exec` into its `app` service; paths become `/app/...`; the site must
|
||
be running). Variables: `${file}` (the file of the editor), `${dir}`, `${project}`, `${selection}`, `${line}`, `${fileName}`,
|
||
`${relativeFile}`, and `${input:Label}` (asked in a dialog at each run). They are exported as `JUMPHP_*` environment variables and
|
||
each `${…}` becomes a reference to its variable quoted for where it stands (outside quotes, inside `"…"`, inside `'…'`): a selection
|
||
holding `$(…)`, backquotes or quotes is never run. Saved in **`.jumphp/scripts.json`** (committed: the team shares them), or, when
|
||
ticked **On this computer only**, in `.jumphp/scripts.local.json` (git-ignored by `.jumphp/.gitignore`, with `.jumphp/run/`, where
|
||
each run writes its shell file).
|
||
- **The tasks the project already has**, found without running anything: **Makefile** targets (and their `## help`, at the end of the
|
||
line or on the line above), **Castor** tasks (`castor.php` and `.castor/*.php`: the `#[AsTask]` functions read with php-parser, named as
|
||
Castor names them; in a trusted project with castor installed, `castor list --format=json` is asked instead), **composer.json** and
|
||
**package.json** scripts (npm, pnpm, yarn or bun after the lock file; composer / the package manager in Docker — `composer:2`,
|
||
`node:22-alpine` — when the computer has none), **justfile** recipes and **Taskfile** tasks. Right click: run here or elsewhere,
|
||
**Make a Script from It…** (a home-made script prefilled with its command), open the Makefile / castor.php.
|
||
- **Castor**: a `castor.php` without castor installed offers **Install Castor…**: after your yes, the static `castor` program of the
|
||
newest release (`github.com/jolicode/castor/releases/latest/download/castor.<os>-<arch>`) is downloaded with curl, checked against the
|
||
release's `SHA256SUMS` (nothing is installed when it differs) and put in `~/.jumphp/bin/castor`. The IDE also finds `castor` in the PATH
|
||
or a `castor.phar` of the project (with the computer's php). **New Castor Task…** opens the Castor wizard (see
|
||
[Command wizards](#command-wizards-symfony-commands-castor-tasks)): a task, a context or a listener written into `castor.php` or `.castor/`.
|
||
|
||
Every script and every task can be:
|
||
|
||
- **pinned** to the main tool bar (the ☆ of its row: an icon button beside Run; right click it for its menu);
|
||
- given a **keyboard shortcut** (Shortcut, Icon and Events…: press the keys; a key the IDE already uses stays the IDE's). Each script
|
||
is an action (**Run Script: …**): Search Everywhere / Find Action, the Tools menu;
|
||
- a **run configuration**: home-made scripts and the pinned / bound tasks join the run widget's list (group *Scripts*);
|
||
- **run on events**: when a saved file matches a glob (`*.scss`, `src/**/*.php`, several separated by commas), when the project opens,
|
||
or **before** chosen run configurations (it must end with code 0, or the run does not start; a Terminal script runs in the background
|
||
there). The bindings of detected tasks are kept in `.jumphp/scripts.local.json`.
|
||
|
||
**Trust**: a project's scripts never run by themselves, and `castor list` (which runs `castor.php`) is never called, until you trust
|
||
the project once (the banner of the window, or its ⋯ menu: Trust This Project…). The answer is kept per project folder in
|
||
`~/.jumphp/ide/trusted-projects.json`, never in the project: a freshly cloned repository with a committed `.jumphp/scripts.json`
|
||
cannot run anything on open. The PHP side refuses an event run of an untrusted project too. A click, a pinned button or a shortcut
|
||
always runs (you asked for it).
|
||
|
||
Code: `ide/src/Scripts/` (`TaskDetector`: the runners' tasks; `ScriptShell`: variables, quoting, the run file; `ScriptStore`:
|
||
scripts.json; `ScriptTrust`; `Castor`: the program, its install, castor.php; `ScriptCommands`: the `scripts.*` commands),
|
||
`ide/ui/js/scripts.js`. Tests: `ide/tests/ScriptsTest.php` (parsing, quoting with a hostile selection, the trust rule, a real Makefile
|
||
run, and a real castor phar when it can be fetched).
|
||
|
||
## Command wizards (Symfony commands, Castor tasks)
|
||
|
||
Two wizards make a console command or a Castor task from a form, read an existing one back to edit it, and run it from a form
|
||
(`ide/ui/js/command-wizard.js`, the PHP side `ide/src/Wizard/`, commands `wizard.*`):
|
||
|
||
- **Symfony command** (Tools › New Symfony Command…, the **+** of the Console window; **Edit in the wizard** on a command of the
|
||
Console window): name (`app:…`), class, description, aliases, hidden, help; arguments (required / optional, several values, type,
|
||
default, description) and options (flag, value required, value optional, several values, `--x / --no-x`, shortcut, type, default);
|
||
**injected services** (a class or interface found by the PHP index, put in the constructor as `private readonly`); a **body** made
|
||
of steps picked in a palette (SymfonyStyle title, section, text, ask, confirm, choice, a progress bar, a table, success / note /
|
||
warning / error, lines of PHP) and what it returns (`Command::SUCCESS / FAILURE / INVALID`). Two styles: **attributes** (Symfony
|
||
7.3+: `#[AsCommand]` on a class with `__invoke()`, its parameters `#[Argument]` / `#[Option]`) or **classic** (`configure()` with
|
||
`addArgument()` / `addOption()`, `execute()`); the default follows `symfony/console` in `composer.lock`. Written to
|
||
`src/Command/<Class>.php` in the namespace composer.json's psr-4 gives.
|
||
- **Castor** (Tools › New Castor Task…, the Scripts window's menu; **Edit in the Wizard…** / **Run with Arguments…** on a Castor task):
|
||
a **task** (`#[AsTask]`: name, namespace, description, aliases, default task; its parameters `#[AsArgument]` / `#[AsOption]` with mode,
|
||
shortcut, type, default — the attribute left out when Castor guesses the same), a **context** (`#[AsContext]`: working folder,
|
||
environment, data, TTY, timeout, allow failure, quiet) or a **listener** (`#[AsListener]` on a Castor event). Body steps: `run()` and
|
||
`capture()` with a context (`context()->withWorkingDirectory()->withEnvironment()->withTty()->withTimeout()->withAllowFailure()`),
|
||
`io()` output and questions, `fs()` operations, `http_request()`, `watch()`, `notify()`, `variable()`, lines of PHP. Written into
|
||
castor.php (made when missing) or a file of `.castor/` (the root file gets its `import(__DIR__ . '/.castor/x.php')`), the use lines
|
||
added in their alphabetical place; a function name PHP already has (`reset`, `copy`...) is avoided (`db:reset` → `dbReset()`).
|
||
- **Round trip**: an existing command (both styles, and the older `setDescription()` / `'name|alias'` forms) or task is read with
|
||
php-parser into the form. Applying an edit rewrites only what changed: new arguments / options / attribute keys / services are
|
||
inserted as text in the list's own layout (one per line or not), changed ones are written anew in their place, removed ones go
|
||
away through php-parser's **format-preserving printer**, so every other byte of the file stays as it was. A renamed argument's
|
||
variable follows in the body (attributes style, Castor) or its `getArgument('old')` line (classic); a removed classic option takes its
|
||
`$x = $input->getOption('x');` line with it. The body is never touched by an edit.
|
||
- Every change is shown **as a diff** (Monaco, the files it touches: a new `.castor/` file and the root file importing it) before it
|
||
is written, and refused if a file changed since the preview.
|
||
- **Run form**: a field per argument and option, the command line it makes; a Symfony command runs through the Console window's
|
||
runner (a Terminal tab, or **Run here** without questions), a Castor task through the Scripts window's (its arguments quoted after
|
||
the task, `scripts.prepare`'s `args`).
|
||
|
||
Tests: `ide/tests/CommandWizardTest.php` (the exact PHP of both styles, `ide/tests/fixtures/wizard/`; both read back to the same model;
|
||
an unchanged model leaves the file byte for byte; edits change only the expected lines; Castor tasks, contexts, listeners, the
|
||
`.castor/` import; a real castor phar lists and runs the generated tasks; with `JUMPHP_WIZARD_SYMFONY=<a Symfony project>` a real
|
||
`bin/console list` and run of both styles). Limits: the body of an existing command / task is not read back into steps; services are
|
||
only added by an edit (removing one is done in the editor); a Castor context or listener is made, not edited, by the wizard;
|
||
`help:` of `#[AsCommand]` needs Symfony 7.3 (the classic style uses `setHelp()`).
|
||
|
||
## Symfony Events and Messenger
|
||
|
||
Two windows of a Symfony project (it has `bin/console`; Messenger when `symfony/messenger` is there), on the right tool bar and in
|
||
Tools. Every change they make is shown first as diffs (one editor tab per file), then written by **Write the files** (refused if a
|
||
file changed meanwhile: preview again). PHP files are edited with php-parser: what changes is printed again (format-preserving
|
||
printing), a `use`, a method or an array item is inserted where a person would write it; the rest of the file stays byte for byte.
|
||
|
||
**Events** (`ide/ui/js/symfony-events.js`):
|
||
- **The picker**: a searchable list (name, constant, class) of the framework's events — kernel (`KernelEvents::*`), security
|
||
(`SecurityEvents`, `LoginSuccessEvent`, `CheckPassportEvent`…), forms (`FormEvents`), console (`ConsoleEvents`), Messenger workers
|
||
(`WorkerMessageFailedEvent`…), Mailer, Doctrine (`Events::prePersist`…) — only those of the packages in `vendor/`, each with the
|
||
class of its event object (the method written gets the right type: `RequestEvent $event`, `PreUpdateEventArgs $args`), and the
|
||
project's own: classes of `src/` extending `Event` and what `src/` dispatches (`->dispatch(new X)`, `->dispatch($e, X::NAME)`;
|
||
the Messenger bus's `dispatch` is not an event), with the places they are dispatched (a click opens them).
|
||
- **For the event chosen**: its listeners in the code in the order they are called, and a form: a new EventSubscriber
|
||
(`getSubscribedEvents()` with priorities, several methods for one event: `[['a', 10], ['b', -5]]`), a new listener with
|
||
`#[AsEventListener]` on its methods or on the class, a Doctrine `#[AsDoctrineListener(event: Events::postPersist)]` or
|
||
`#[AsEntityListener(event:, method:, entity:)]` listener, or a method added to an existing subscriber / listener. **One more event
|
||
in this class** collects several events into the class being written.
|
||
- **New event**: the event class (properties as readonly constructor parameters, an optional `NAME`), its dispatch inserted at the
|
||
end of a method of a class (before its last `return`; `EventDispatcherInterface` injected in the constructor when the class has
|
||
none, a constructor written when it has none), and optionally a listener of it.
|
||
- **Listeners**: who listens to what in which order, **from the code** (priorities editable in place, a subscription removed: the
|
||
method stays) or **from the application**: `debug:event-dispatcher --format=json` run through the Console window's runner (the
|
||
site's container or the computer's PHP), vendors included, located by Composer's PSR-4 (a click opens the method).
|
||
|
||
**Messenger** (`ide/ui/js/messenger.js`):
|
||
- **Workers**: `messenger:consume <transports> --limit --time-limit --memory-limit -vv` started from the IDE, several at once, each
|
||
with its live output, Stop / Restart, and **Restart when it ends** (not after 3 quick failures in a row). Where it runs follows the
|
||
Console window's runner: in the site's running PHP container (`docker exec … sh -c 'echo $$ > /tmp/jumphp-worker-<id>.pid; exec php
|
||
bin/console …'`, stopped by a `kill -TERM` of that pid inside the container), in a temporary container of the site's image
|
||
(`bin/jumphp web:console`, `docker run` passes the stop signal on), or with the computer's PHP (its process group).
|
||
**Stop every worker** = `messenger:stop-workers`; **Set up the transports** = `messenger:setup-transports`.
|
||
- **Queues**: the messages waiting per transport (`messenger:stats --format=json`, the table of older versions), the failed messages
|
||
(`messenger:failed:show`: id, class, date, error) retried or removed one by one or all, the Scheduler's recurring messages and next
|
||
runs (`debug:scheduler`, when `symfony/scheduler` is installed).
|
||
- **Transports**: `config/packages/messenger.yaml` as a form: each transport's dsn (an `%env()%` one shows the value the `.env` files
|
||
give it), retry strategy, failure transport; the global failure transport; the routing (message → transports). Written by
|
||
symfony/yaml: the file's other keys and `when@env` sections are kept, its comments are not (the diff shows it).
|
||
- **Messages**: each message (handled, routed, `#[AsMessage]`, or in `src/Message/`) with its handlers (`#[AsMessageHandler]` on a
|
||
class or methods, `bus`, `fromTransport`) and transports (a message routed by a parent class or `*` too); a message without handler
|
||
is pointed out. **New message**: the class, its routing (messenger.yaml, or `#[AsMessage]`), its handler; **Handler** adds one.
|
||
|
||
The PHP side: `ide/src/Symfony/` — `EventCatalog` (framework and project events, dispatches), `EventListeners` (from the code, from
|
||
`debug:event-dispatcher`), `EventCode` (the code written), `PhpEdit` / `PhpSources` (php-parser), `MessengerConfig`, `MessengerCode`,
|
||
`MessengerWorkers` (command lines, workers, parsing of the console's tables), `CodeChanges` (preview / write), `EventCommands`
|
||
(`events.*`), `MessengerCommands` (`messenger.*`; console commands through `console.run`). Tests: `ide/tests/SymfonyEventsTest.php`,
|
||
`ide/tests/SymfonyMessengerTest.php` (exact generated code, format-preserving edits, messenger.yaml read / written, worker command
|
||
lines per runner, the console's answers); `games/ide/tools/ui-symfony-check.sh <a copy of a Symfony project>` (screenshots).
|
||
Limits: the event list of a project is read from `src/` only (services.yaml `kernel.event_listener` tags are not read); a worker
|
||
started in the site's container keeps running if the IDE quits (Stop it first, or `messenger:stop-workers`); messenger.yaml loses its
|
||
comments when the window writes it.
|
||
|
||
## SSH
|
||
|
||
The **SSH** window (right tool bar, desktop only) works with the servers you reach by SSH, through the programs of
|
||
this computer: `ssh` and `scp` from the PATH (Linux, macOS; Windows: its OpenSSH client, `ssh.exe` / `scp.exe`,
|
||
Settings › Optional features). The IDE never speaks SSH itself and never keeps a password: your `~/.ssh/config`, keys,
|
||
agent (`ssh-agent`, Pageant through OpenSSH) and `known_hosts` apply as in a terminal.
|
||
|
||
- **Servers**: name, host (or an alias of `~/.ssh/config`), port, user, key file, jump host (`-J`), start folder. They are
|
||
the IDE's settings on this computer (`~/.jumphp/ide-ssh.json`, 0600), never in a project. **Import from ~/.ssh/config**
|
||
lists its named hosts (`Include` followed); an imported server keeps its alias as host, so ssh applies the whole file.
|
||
**Test the connection** runs `ssh -o BatchMode=yes … exit 0`: no question can be asked there, so a host key never seen
|
||
or a password-only server says so (open a terminal once).
|
||
- **A session**: a new tab of the Terminal runs `ssh -t` (in the server's start folder): password and passphrase prompts,
|
||
host keys, colours, full-screen programs work as in your own terminal; several at once. Windows: the IDE's terminal has no
|
||
pseudo-terminal there, so the session opens in a console window of its own.
|
||
- **Files** (the folder button): the remote folder (`cd … && pwd && LC_ALL=C ls -lA`: GNU, BSD and BusyBox servers), double
|
||
click to go in or to open a file in the editor (read with ssh, saved back with ssh in its own encoding and line endings; 5 MB at
|
||
most), the path field, Up; new folder, rename, copy / move to a folder, delete (asked first), upload a file or a folder (or drop a
|
||
file of the Project view on the list), download the selection into a folder you choose. Transfers are `scp -r -p` with their
|
||
progress (scp's meter, read through `script` on Linux / macOS), stoppable. Everything runs as processes of their own: the IDE never
|
||
waits.
|
||
- **Drag and drop** (desktop): files and folders of the **file manager** (Nautilus, Dolphin, Explorer, Finder) dropped on the list
|
||
are uploaded into the folder shown, dropped on a remote folder row into that folder (the runtime gives their real paths:
|
||
`native:drag`, docs/tauri.md); Project view files too. **Remote rows dragged out**: inside the IDE, onto a folder of the Project
|
||
view (or a file: its folder; the project's row: its root), they are downloaded there; out of the window, they are first downloaded
|
||
to a folder of their own (`<temp>/jumphp-ssh-drag/<key>/<name>`, a key per server, path, size and date: kept a day, not downloaded
|
||
again), which starts as soon as the drag begins, then a native drag hands the copy to the file manager. A large file still
|
||
downloading when the pointer leaves: the drag starts once it is there if the button is still down, else "Downloaded: drag again"
|
||
(the next drag is immediate). A name already in the target folder: **Overwrite** (folders merged), **Skip** or **Rename**
|
||
(`name (2).ext`), asked once per drop. Linux: X11 and Wayland (GTK's drag); Windows / macOS: built, not tried on those systems yet.
|
||
- **Shared connection** (Linux, macOS): a terminal session is the master of an OpenSSH shared connection
|
||
(`ControlMaster=auto`, `ControlPath=~/.ssh/jumphp-%C`); while it is open, the file panel and transfers go through it without asking
|
||
again, so servers with a password or a one-time code work too. Without a session they need a key or the agent (`BatchMode=yes`).
|
||
- Remote paths: single quotes for the remote shell; scp's remote paths escaped for both of its protocols (the legacy one hands
|
||
them to the remote shell, SFTP — OpenSSH 9 and newer — to glob; an upload's destination is taken as it is with SFTP).
|
||
|
||
Code: `ide/src/Ssh/` (`SshCli`: the command lines and listings, pure; `SshConfig`: `~/.ssh/config`; `SshServers`: the settings;
|
||
`SshCommands`: the `ssh.*` commands; `SshTransfers`: drag and drop's conflicts and drag copies, pure), `ide/ui/js/ssh.js`; remote files open as `ssh://<server>/<path>` tabs (`editor.js`).
|
||
Tests: `ide/tests/SshTest.php`, `ide/tests/SshDragDropTest.php` (a stand-in ssh / scp; `JUMPHP_SSH_E2E=host:port:user:keyfile` also runs them against a real sshd,
|
||
e.g. a throwaway `lscr.io/linuxserver/openssh-server` container). Why built in rather than a plugin: the plugin API has no
|
||
terminal tab, no drag and drop from the Project view, no streamed process with progress and no editor tab backed by a remote file.
|
||
|
||
## Database
|
||
|
||
The **Database** window (right tool bar, desktop only) and **SQL Results** (bottom) work with the project's databases:
|
||
MySQL / MariaDB (MySQL 5.7 / 8.x, MariaDB: `mysql_native_password`, `caching_sha2_password`) and SQLite files (when the IDE's
|
||
PHP has `pdo_sqlite`). PostgreSQL is not supported yet: a PostgreSQL database found in the project is listed as such.
|
||
|
||
- **Connections** are the project's: `.jumphp/databases.json` (commit it: the team shares them) holds name, driver, host,
|
||
port, user, default database (or the SQLite file), an SSH tunnel, a colour and the **production** flag. **Never a
|
||
password**: a password is kept by the IDE on this computer when you ask (`~/.jumphp/ide-db-secrets.json`, readable by you
|
||
only, keyed by the project's folder and the connection), else asked at each connection.
|
||
- **Found in this project**: Symfony `DATABASE_URL` (`.env`, `.env.local`, `.env.dev`...), Laravel `DB_*`, the MariaDB /
|
||
MySQL / PostgreSQL services of `compose.yaml` / `docker-compose.yml` (and overrides; their published port, user, password
|
||
and database from their environment, `${VAR:-default}` resolved) and the JumPHP web site's stack (`.jumphp/compose.yaml`
|
||
of `bin/jumphp web:serve`). A URL whose host is a compose service (`db`, `database`) is reached through that service's
|
||
published port. **Add** makes it a connection, its password kept by the IDE.
|
||
- **The tree**: databases (the default one first) › tables, views, routines › columns (type, NOT NULL, key), indexes,
|
||
foreign keys. Double click a table: its data; right click: structure (columns, indexes, foreign keys, the `CREATE`
|
||
statement), a `SELECT` in a console, copy the name.
|
||
- **SQL consoles**: `.jumphp/consoles/<name>-<id>.sql`, files of the project kept out of git (their own `.gitignore`), opened
|
||
in the editor. **Ctrl+Enter** runs the selection, else the statement under the cursor (`;` outside quotes and comments,
|
||
`DELIMITER` understood); the editor's menu also has *Run the whole SQL file*, *Explain Plan* and *Choose the Database
|
||
Connection…*, which attaches **any `.sql` file** of the project to a connection. Tables, views, routines and columns (of
|
||
`table.` and of aliases: `FROM customers c` › `c.`) are completed from the live schema. Each statement gives a result tab;
|
||
the next run replaces the previous ones unless pinned (☆). History: the statements run per connection.
|
||
- **The console's database**: its bar has the list of the connection's databases (`USE`), remembered per console. Completion uses
|
||
the tree's data: the database names at once (after `FROM` / `JOIN` / `USE` too, so a connection without a default database
|
||
proposes them), `db.` that database's tables, `db.table.` and aliases (`FROM customers c` › `c.`) their columns, then keywords
|
||
and functions; a database's tables are read only when needed (a *Loading the tables…* item meanwhile). Hovers show a table's
|
||
columns and a column's type.
|
||
- **SQL inside other files**: PHP heredocs / nowdocs labelled `SQL` (`<<<SQL`, `<<<'SQL'`, `MYSQL`, `SQLITE`...; `DQL` is left
|
||
to Doctrine), the string given to an obvious SQL call (`->query('…')`, `->prepare("…")`, `->executeQuery()`,
|
||
`->executeStatement()`, `->fetchAllAssociative()`...) when it starts like SQL, and Markdown ```` ```sql ```` / ```` ```mysql ````
|
||
blocks get SQL colours (Monaco's SQL tokenizer as decorations, painted again 350 ms after a change, only in files that hold
|
||
such SQL), the same completion and hovers, and a lens **▶ Run in <connection> | Explain Plan | Connection…** above each block.
|
||
Its PHP variables (`{$x['a']}`, `$id`) and placeholders (`:name`, `?`) are never run as written: a form asks a value for each
|
||
first (quoted as SQL text unless a number or NULL; "as is" gives SQL itself). The production guard applies; the results go
|
||
to SQL Results. Ranges: `ide/ui/js/sql-ranges.js` (comments, other strings and heredocs skipped), completion:
|
||
`ide/ui/js/sql-complete.js`, both tested with `node --test`.
|
||
- **Results**: up to 10 000 rows kept per statement, shown 100 at a time; a click on a header sorts, the filter keeps the
|
||
rows containing a text; **Export**: copy or save as CSV, JSON or SQL INSERTs (every kept row, not only the page).
|
||
- **A table's data**: its rows from the server (`LIMIT` / `OFFSET`, `ORDER BY` a clicked column, a `WHERE` you type), the
|
||
total counted. Double click a cell to edit it (Enter keeps it, Escape cancels), right click a row to delete it or set a cell to
|
||
NULL, **+ Row** adds one; **Save changes…** shows the `UPDATE` / `DELETE` / `INSERT` statements, then runs them **in one
|
||
transaction** (one fails: none is kept). A row is found again by its primary key (else a unique key of NOT NULL columns,
|
||
else all its values as read, `LIMIT 1`); binary columns are shown as `0x…` and edited with SQL only.
|
||
- **SSH tunnel**: through a server of the SSH window (its host or `~/.ssh/config` alias, port, user, key, **jump host**):
|
||
`ssh -N -L 127.0.0.1:<free port>:<db host>:<db port>` with the computer's own ssh, without question (`BatchMode`: a key or
|
||
the agent) and without the shared connection. A teammate without that server in their SSH window uses the `user@host` (and
|
||
jump host) also saved with the connection.
|
||
- **Production**: a connection marked *production* has a red bar in the tree, over its consoles and over its results; a
|
||
statement that writes (`INSERT`, `UPDATE`, `DELETE`, `REPLACE`, `DROP`, `ALTER`, `TRUNCATE`, `CREATE`, `RENAME`, `GRANT`,
|
||
`CALL`, `WITH … DELETE`, `SELECT … INTO OUTFILE`...) never runs before you confirm it in a dialog that shows it; the PHP
|
||
side refuses it without that confirmation.
|
||
|
||
Code: `ide/src/Database/` (`DatabaseCommands`: the `db.*` commands; `DatabaseConfig`, `DatabaseSecrets`, `DatabaseDetector`,
|
||
`SqlText`: statements, the production guard, the UPDATE of an edited row, exports; `MysqlDriver`, `SqliteDriver`, `SshTunnel`),
|
||
`ide/ui/js/db.js`, `ide/ui/css/db.css`. The MySQL protocol is **jumphpsql's** (https://git.jumphp.net/jumphp/jumphpsql,
|
||
`apps/jumphpsql/src/Db`): `ide/src/Database/Mysql/` is a copy of its `MysqlConnection`, `Promise`, `ResultSet`, `MysqlError`
|
||
and `Sql`, only the namespace changed (a fix goes into both, until they become one Composer package); pure PHP on a
|
||
non-blocking socket, polled by the IDE's frame like its processes: the IDE never waits for the server. Tests:
|
||
`ide/tests/DatabaseTest.php` (no server: configuration, detection, statements, the guard, edits, SQLite) and
|
||
`ide/tests/DatabaseMariadbTest.php` (a throwaway `mariadb:11.4` on port 3398, started by the test when docker is there, skipped
|
||
otherwise); screenshots: `games/ide/tools/ui-db-check.sh`.
|
||
|
||
## HTTP Client and OpenAPI
|
||
|
||
**HTTP Client** (bottom tool window, globe icon) sends the project's API requests, in the spirit of request collection tools:
|
||
collections, environments, auth, scripts and tests, history. **OpenAPI** (right) shows the project's API description and opens
|
||
any operation in the HTTP Client. The PHP side: `ide/src/HttpClient`; the interface: `ide/ui/js/http-client.js`, `openapi.js`
|
||
(loaded the first time they are shown), `http-model.js` (JSONPath, curl, the scripts' API), `http-script-worker.js`.
|
||
|
||
**Files** (plain text, committed with the project, reviewed like code):
|
||
|
||
```
|
||
http-requests/<collection>/collection.json {"name", "auth": {...}, "headers": [[name, value]], "share": {"project": slug}}
|
||
http-requests/<collection>/http-client.env.json {"local": {"baseUrl": "http://localhost:8000", "username": "admin", "$secrets": ["password"]}}
|
||
http-requests/<collection>/<folder>/<request>.http
|
||
```
|
||
|
||
A request file is the `.http` format other editors read (request line, headers, blank line, body; `< {% %}` script before,
|
||
`> {% %}` script after), with the HTTP Client's settings in `# @` comments those tools skip:
|
||
|
||
```http
|
||
# @name Create a book
|
||
# @seq 2
|
||
# @auth jwt login=auth/login.http path=$.token var=token
|
||
# @no-redirect
|
||
# @insecure
|
||
# @timeout 30
|
||
POST {{baseUrl}}/api/books
|
||
Content-Type: application/ld+json
|
||
|
||
{"title": "Dune"}
|
||
|
||
> {%
|
||
client.test("created", () => client.assert(response.status === 201));
|
||
client.global.set("bookId", response.body.id);
|
||
%}
|
||
```
|
||
|
||
`# @auth`: `inherit` (the collection's; the default), `none`, `bearer token=`, `basic username= password=`,
|
||
`apikey in=header|query name= value=`, `oauth2 grant=client_credentials|password tokenUrl= clientId= clientSecret= scope=
|
||
[username= password=] [clientAuth=basic]`, `jwt login=<request of the collection> path=<JSONPath> var=<variable> [header=] [prefix=]`.
|
||
|
||
**Variables**: `{{name}}` from the environment, its secrets, the values scripts and logins set, the file's `@name = value` lines;
|
||
dynamic ones `{{$uuid}}`, `{{$timestamp}}`, `{{$isoTimestamp}}`, `{{$randomInt}}`, `{{$random.integer(1, 10)}}`,
|
||
`{{$random.alphanumeric(8)}}`, `{{$random.email}}`. **Secrets** (a variable marked secret in Environments…), the tokens
|
||
and the values scripts set are kept on this computer only, in `~/.jumphp/ide-http-secrets.json` (0600): never in the project,
|
||
never sent to jumphp.net, masked in the history (`~/.jumphp/ide-http-history/`).
|
||
|
||
**JWT**: the login request is sent when there is no token, when its `exp` is less than 30 s away, or once when the API answers
|
||
401; the token is read with the JSONPath and kept in the variable (`{{token}}`). **OAuth2**: client credentials or password,
|
||
the token kept until `expires_in`.
|
||
|
||
**Scripts** run in a Web Worker without network, stopped after 3 s: `client.global.set/get`, `client.test(name, fn)`,
|
||
`client.assert(cond, message)`, `request.variables.set` (this request only), `req.setHeader / setBody / setUrl` (pre-request),
|
||
`response.status / body / headers.valueOf() / contentType.mimeType / responseTime`, `expect(x).to.equal / eql / have.property /
|
||
include / match / above / below / lengthOf / be.a`, `.not`, `jsonpath(data, path)`, `console.log`; Bruno's `bru`, `res`, `req`,
|
||
`test()` work too.
|
||
|
||
**Sending**: the IDE's PHP sends it (non-blocking sockets polled by the frame; HTTP/1.1, gzip, chunked, cookies kept per site
|
||
until the IDE closes), follows redirects or not (the chain is in Timeline), checks TLS or not (a local site's self-signed
|
||
certificate), a timeout; `User-Agent: jumphp-ide` unless the request sets one, nothing else about the user. The answer: status,
|
||
time (connect / TLS / wait / download), size, headers, cookies, body pretty (JSON / XML / HTML), raw, as a table (a JSON array, an
|
||
API Platform `member`), HTML preview (sandboxed), pictures; a JSONPath filter; Ctrl+F in the body; Copy as curl.
|
||
Ctrl+Enter sends, Ctrl+S saves.
|
||
|
||
**Import / export**: `.http` files (several requests separated by `###`, continuation lines, `@var` lines), Bruno `.bru` files
|
||
and folders (their `environments/*.bru`, `vars:secret` names), pasted text; export of a request, a folder or a collection as
|
||
`.http` or `.bru`.
|
||
|
||
**OpenAPI**: a file of the project (`openapi.yaml|json`, `swagger.*` in the usual folders) or an address (API Platform's
|
||
`/api/docs.jsonopenapi`, `/api/docs.json`, NelmioApiDocBundle's `/api/doc.json`, on the site's address: `bin/jumphp web:serve`'s
|
||
port, `.env` `DEFAULT_URI` / `APP_URL`). OpenAPI 3.x and Swagger 2.0, JSON or YAML; `$ref` resolved (cycles cut), `allOf`
|
||
merged, an example made from each schema. **Try it** opens the operation filled (path parameters, required query ones, Accept,
|
||
Content-Type, an example body, the auth of its security scheme: the collection's when it has a bearer / JWT / OAuth2 auth);
|
||
**Add All to the Collection** writes a request file for each operation, a folder per tag.
|
||
|
||
**Sharing** with a jumphp.net project's members (Share with the Project's Members…, then Sync Now): the files go to
|
||
`/api/ide/projects/{slug}/http/{collection}` with the IDE's token, read for the members, write for the owner and the write
|
||
members. Each sync compares both sides with the last sync (kept in `~/.jumphp/ide-http-sync.json`): a change on one side goes
|
||
to the other; a file changed on both sides keeps this computer's version and writes theirs beside it as `<name>.theirs.http`
|
||
(never shared). Environments travel without secret values (the IDE removes them; the site refuses a file that holds one).
|
||
|
||
Check of the interface: `games/ide/tools/ui-http-check.sh <API address seen from Docker>` (an API Platform site with
|
||
lexik/jwt): `http-openapi.png`, `http-request.png`, `http-auth-env.png`, `http-auth.png`.
|
||
|
||
## .env files
|
||
|
||
`.env`, `.env.local`, `.env.<env>`, `.env.<env>.local`, `.env.dist`, Laravel's `.env` / `.env.example` and Docker Compose
|
||
`env_file` files (`*.env`) open in the **.env editor** (the buttons at the bottom right; the choice is remembered):
|
||
|
||
- **Code**: Monaco with a dotenv colouring (names, values, comments, `${REFS}`, quotes, escapes, `export`), completion of the
|
||
variables Symfony and Laravel know (at the start of a line), of `${REFS}` (the file's names first) and of DSN examples after
|
||
`DATABASE_URL=` / `MAILER_DSN=` / `MESSENGER_TRANSPORT_DSN=` / `REDIS_URL=`; **markers** for invalid names, spaces before `=`,
|
||
unclosed quotes, unquoted spaces, a name defined twice (the first value is not used) and a secret in a file git tracks.
|
||
- **Table** (and **Split**: the code beside it): the file's variables (name, value, effective value for dev / test / prod, comment)
|
||
with the folder's files on top (git badge: tracked; local: ignored; **+** creates `.env.local`, `.env.<env>`...). Rename, change
|
||
a value, a comment, add, delete (with the comment lines just above), **Move to** another file (to keep a value out of git),
|
||
**Copy to** an environment's file or to every one. Values are edited by kind: booleans (a box, `true/false`, `1/0`, `yes/no`
|
||
kept), numbers, multi-line values (a text area, written in double quotes), DSNs with a **DSN builder** (driver, user, password,
|
||
host, port, database / path, options such as `serverVersion` / `charset`; presets for `DATABASE_URL`, `MAILER_DSN`,
|
||
`MESSENGER_TRANSPORT_DSN`, `REDIS_URL`, `LOCK_DSN`, any `*_DSN`). A value that another file overrides for the chosen
|
||
environment is struck through, with the file and line that win. Each edit rewrites only the lines of that variable (one undo
|
||
takes it back; comments, blank lines, order and quotes stay); typing in the code redraws the table.
|
||
- **Variables**: the folder's files merged in the application's load order for an environment, with the file each value comes
|
||
from and the values it overrides (struck through). Symfony (`Dotenv::loadEnv`): `.env` (else `.env.dist`), `.env.local` (not
|
||
for test), `.env.<env>`, `.env.<env>.local`, the later wins; a `.env.local.php` (composer dump-env) is said to win over them.
|
||
Laravel: `.env.<env>` when it exists, else `.env`. `${X}`, `$X`, `${X:-default}`, `${X-default}` resolved; `'single quotes'`
|
||
are literal. The compose files' `env_file` entries are listed with their services.
|
||
- **Secrets**: a name with PASSWORD, PASSWD, PASSPHRASE, SECRET, TOKEN, KEY, PRIVATE, CREDENTIAL, AUTH, SALT (not PUBLIC) or a
|
||
DSN with a password is masked (an eye shows it; a DSN only hides its password). A secret with a real value (not a recipe
|
||
placeholder such as `!ChangeMe!`, not a `${REF}`) in a file git tracks is a warning, with **Move them to .env.local** in one
|
||
click (the lines and their comments move; `.gitignore` gets `/.env.local`, `/.env.local.php`, `/.env.*.local` when it lacks
|
||
them). `.env.local` not ignored, or tracked, is said too.
|
||
- **Vault** (Symfony projects): the secrets of `config/secrets/<env>/` (their names read from `<env>.list.php`, nothing
|
||
decrypted), **Reveal the values** (`secrets:list --reveal`, on demand, masked per row), add / change (`secrets:set NAME -`:
|
||
the value goes on the command's **standard input**, never on a command line, which the process log shows), delete
|
||
(`secrets:remove`), generate / rotate the keys (`secrets:generate-keys [--rotate]`, then the decrypt key is added to
|
||
`.gitignore`). A decrypt key that git tracks is a danger banner, one that is not ignored a warning. The commands go through
|
||
the Console window's `console.run` (its runner: the site's Docker container or the computer's PHP). No value is written to a
|
||
log, a notification or a command line.
|
||
|
||
Code: `ide/src/Dotenv/` (`DotenvFile`: the parser with the byte offsets of every name and value, and the edits that splice
|
||
them; `DotenvSet`: the folder's files, load orders, merge, references; `Dsn`; `Secrets`; `DotenvCommands`: the `dotenv.*`
|
||
commands), `ide/ui/js/dotenv.js` (the views), `dotenv-lang.js` (Monaco language), `dotenv-model.js` (pure helpers),
|
||
`ide/ui/css/dotenv.css`. Tests: `ide/tests/DotenvTest.php` (byte-identical round trips with LF / CRLF / BOM, every kind of
|
||
value, edits, problems, load orders, merge, DSNs, secrets, git, the vault's stdin), `node --test ide/ui/js/dotenv-model.test.mjs`;
|
||
in the real IDE: `games/ide/tools/ui-dotenv-check.sh` (`DOTENV_SHOTS=<dir>` keeps the screenshots).
|
||
|
||
## Translations
|
||
|
||
The **Translations** window (Tools > Translations, at the bottom) shows the project's translation catalogues as a grid of
|
||
keys × languages, one translation domain at a time:
|
||
|
||
- **Catalogues**: Symfony `translations/<domain>[+intl-icu].<locale>.{yaml,yml,xlf,xliff,json,php}` (any folder named
|
||
`translations/`; nested YAML / JSON / PHP keys flattened with dots), JumPHP `config/lang.yaml` (one map per language, the key
|
||
is the English text, never split), Laravel `lang/<locale>/<file>.php` and `lang/<locale>.json` (also `resources/lang/`). Every
|
||
language of the project is a column of each domain: a language without its file there gets it on the first text written.
|
||
The source language is `default_locale` (else `en`).
|
||
- **Checks** per cell: **missing** (red: no text or an empty one), **same as the source** (yellow, a text of 3 letters or more),
|
||
**problems** (orange frame): placeholders not the same as the source's (`%name%`, `{name}`, `{{ limit }}`, Laravel `:name`),
|
||
HTML tags changed, a broken ICU message (braces, a plural / select without `other`, a plural category that is not zero / one /
|
||
two / few / many / other / `=N`), Symfony's plural pipes with another number of forms. Filters: missing (anywhere / in a
|
||
language), same as the source, problems, not found in the code, AI proposals; search in keys and texts.
|
||
- **The code** (👁): one scan of the PHP, Twig and forms / config YAML (the forms the YAML navigation follows: `'key'|trans`,
|
||
`{% trans %}`, `->trans()`, `t()`, `TranslatableMessage`, `Lang::t()`, `__()`, `trans()`, `@lang`, form labels, constraint
|
||
messages): a key found nowhere is **unused**, a key only seen as a plain text of the code is "?" (a JumPHP menu label), and the
|
||
keys given to a translation call that no catalogue has are listed above the grid, each with **Add**. Symfony projects also
|
||
have **debug:translation** (`debug:translation <locale> --only-missing`, through the Console window's runner).
|
||
- **Edits**: a click on a cell edits it (Enter writes, Shift+Enter a new line, Escape cancels): only that key's lines of that
|
||
file change. **+ Key** adds the key to every language file of the domain (a text per language, or empty), making the missing
|
||
files. A row's menu (right click on the key, or ⋯): **Rename…** (in every catalogue, and with the box ticked in the templates
|
||
and the PHP that use it; diffs first, then Write the files), **Delete…** (asks, then every file), translate the key with AI,
|
||
where it is used, open its file. **Language** adds a language: its file in every domain with every key (empty, the source
|
||
text or `TODO`), shown as diffs first.
|
||
- **Formats kept**: YAML is edited line by line (`ide/src/Translations/YamlCatalog.php`: a value replaced on its line with its
|
||
comment, a new key under its deepest parent at its brothers' indentation, a deleted key takes its empty parents, block scalars
|
||
stay blocks; plain values when they read back the same); a text it cannot change safely (flow maps...) is dumped again with its
|
||
values. XLIFF 1.2 / 2.0 are edited as text (`XliffCatalog`: targets changed in place, ids, notes and attributes kept, a new
|
||
unit at the indentation of the last one, ids like translation:extract's). JSON is written again in its own indentation and key
|
||
order. PHP arrays are read by php-parser (never run) and edited at the parser's offsets (comments kept). A file nothing
|
||
changed is never written; a file changed since the preview is refused.
|
||
- **AI** (**Translate…**): from a language to the chosen ones, for the missing texts (default), the rows shown or every key,
|
||
with Claude (this computer's `claude -p`, its login, a JSON schema), OpenCode (`opencode run`) or a chat server of the resource
|
||
editors' Generate… (its key and address as saved there). Batches of 40 texts; each text goes with its key, at most two other
|
||
languages and its XLIFF notes; the prompt asks to keep placeholders, ICU syntax, plural pipes, HTML and the letter case. The
|
||
dialog shows how many texts, characters and requests before it starts. The answers are **proposals** in the grid (green;
|
||
orange text when they break a placeholder): ✓ / edit / ✗ per cell, or **Accept all**; nothing is written before. The
|
||
**Glossary** (`.jumphp/translations-glossary.json`, shared with git): terms never translated, or with a fixed translation per
|
||
language, and a note; only the terms a batch's texts contain are sent. JumPHP projects have **Fill the 14 languages**: the
|
||
missing ones of `fr en es de it pt nl pl ru uk tr ja zh ko` added to `config/lang.yaml`, then the AI dialog for them.
|
||
|
||
Code: `ide/src/Translations/` (`Catalogs`: discovery, groups, checks, edits across files, apply; `YamlCatalog`, `XliffCatalog`,
|
||
`JsonCatalog`, `PhpCatalog`; `Placeholders`; `Usages`: the code scan and the renames in the code; `AiTranslator`: batches,
|
||
prompt, schema, parsing; `TranslationCommands`: `translations.*`), `ide/ui/js/translations.js`, `ide/ui/css/translations.css`.
|
||
Tests: `ide/tests/TranslationsTest.php` (round trips byte for byte, nested YAML, XLIFF 1.2 / 2.0, JSON, PHP, create / rename /
|
||
delete across files, languages added, placeholders and ICU, the code scan, the AI request and answer with a fake AI); in the
|
||
real IDE: `games/ide/tools/ui-translations-check.sh` (a copy of a Symfony project; `TRANSLATIONS_SHOTS=<dir>` keeps the
|
||
screenshots).
|
||
|
||
Limits: Laravel's `lang/vendor/` and Symfony catalogues of bundles are read like the others (no read-only mark); a JSON file's
|
||
nested / flat style is kept but a new file is flat; PHP values that are not plain strings (concatenations, calls) are not shown;
|
||
the code scan does not follow keys built at run time (`'menu.' ~ name`); a rename in the code changes the exact quoted key only.
|
||
|
||
## Docker: a remote engine
|
||
|
||
The **Docker** window (containers, images, volumes, Compose, Docker Hub) works with the engine chosen in its **Engine** menu,
|
||
remembered per project (the IDE's preferences; nothing secret stored):
|
||
|
||
- **This computer**: `docker` as it is (its current context).
|
||
- **A server of the SSH window** ("<name> (remote)"): its host, port, user, key file and jump host are used as they are. Docker's own
|
||
`ssh://` transport cannot take a key file or a jump host (only `~/.ssh/config`, which the IDE never edits) and needs the docker
|
||
CLI on the server, so the IDE opens **its own tunnel** with the computer's `ssh`: `ssh -N -L <local>:<server's docker socket>`
|
||
(`BatchMode=yes`, `ExitOnForwardFailure`, keep-alives, its own connection: `ControlPath=none`), then runs `docker -H <local>`.
|
||
The local end is a unix socket `~/.jumphp/docker/<server id>.sock` (folder 0700) on Linux / macOS, a port of `127.0.0.1` on
|
||
Windows. Only the docker client is needed on this computer; the server needs Docker and sshd's stream-local forwarding (on by default).
|
||
Connecting is three steps, shown beside the menu: the server's docker socket looked for (`$DOCKER_HOST` of the login,
|
||
`/var/run/docker.sock`, rootless Docker's `/run/user/<uid>/docker.sock`; can its user read it?), the tunnel opened, Docker asked its
|
||
version. A tunnel that drops is opened again by the next command; another engine chosen (or the IDE closed) closes it.
|
||
- **A docker context** ("<name> (docker context)", `docker context ls`): `docker --context <name>`, its transport docker's own.
|
||
|
||
Then everything works on that engine: lists, stats, logs, start / stop / remove, inspect, pull, Run…, the shell in the IDE's terminal
|
||
(`docker -H unix://… exec -it …` / `docker --context … exec -it …`), a published port opens on the server's host name. A Compose
|
||
project seen on a server: **Up** runs `docker compose up -d` on the server itself (ssh, in its folder: its files are there); stop / down
|
||
need only its name. The Compose tab's Apply sends the project's local files to the engine chosen, like `docker --context` would.
|
||
|
||
Errors are explained: a host key never seen or a server asking a password ("Open an SSH session": accept it once, or use a key /
|
||
the agent: no question can be answered in a tunnel), no Docker on the server, a user outside the `docker` group (the `usermod`
|
||
line to type), forwarding refused by the server, no ssh / docker program here. Limits: a key file is given to the destination
|
||
only (the jump host authenticates with the agent or `~/.ssh/config`, as `ssh -J` does); on Windows with Docker only inside WSL,
|
||
remote engines need Windows' own docker client.
|
||
|
||
Code: `ide/src/Docker/DockerEngines.php` (pure: command lines, the probe, ssh's errors), `DockerEngine.php` (the chosen engine, the
|
||
tunnel), `DockerCommands.php`. Tests: `ide/tests/DockerEngineTest.php` (a stand-in ssh / docker; `JUMPHP_DOCKER_SSH_E2E=host:port:user:keyfile[:jump]`
|
||
also runs it against a real sshd with Docker, e.g. `ide/tools/docker-ssh-e2e.sh`).
|
||
|
||
## How it works
|
||
|
||
One interface, one PHP core, two hosts:
|
||
|
||
```
|
||
ide/ui (HTML / JS, Monaco) the same files on both
|
||
│ backend.invoke(name, payload), backend.on(event)
|
||
┌─────────────┴──────────────┐
|
||
desktop: window.jumphp (Tauri) web: fetch POST /api/ide/<slug>/invoke
|
||
│ │
|
||
games/ide Main ── session, projects, sign-in jumphp-playground WebIde ── drafts, preview, tests
|
||
│ │
|
||
JumPHP\Ide\Ide ── LocalWorkspace JumPHP\Ide\Ide ── OverlayWorkspace (published game + drafts)
|
||
files, php.*, search.*, git.* (git program), run.* (processes)
|
||
```
|
||
|
||
- **The core** (`JumPHP\Ide\Ide`) answers commands: `file.*`, `php.*` (complete, definition, references, rename, hover,
|
||
signature, diagnostics, outline, symbols), `search.*`, `git.*`, `run.*`, `project.info`. It never blocks: Git and runs are
|
||
processes read a little at every frame (`Processes`), results are `Deferred`.
|
||
- **The PHP index** (`Php\Index`): every PHP file of the project analysed with nikic/php-parser (declarations, references with
|
||
the receiver's type when the file tells it), a few ms per frame, cached; libraries (Composer `vendor/`) found by their PSR-4
|
||
prefixes and analysed when a class is needed, then all of them in the background once the project is done (`indexLibraries()`:
|
||
their implementations and subclasses, classmap classes; cached in `<cache>.libraries`); PHP's own classes and functions by Reflection.
|
||
- **Desktop**: `games/ide` is a JumPHP desktop app (docs/tauri.md). The pages call one command, `ide`; Main answers the session
|
||
and project commands and hands the rest to the open project's `Ide`. Sign-in: a loopback (as native apps do OAuth): the IDE
|
||
listens on `127.0.0.1:<random port>`, opens `jumphp.net/ide/connect`, you authorize, jumphp.net sends the browser back with a
|
||
token (`jpi_…`, revocable in the studio). Git push uses your Git token through jumphp.net, passed in git's environment,
|
||
never written in the repository.
|
||
- **Web**: `jumphp.net/ide/<project>` serves the same `ui/`; its commands work on the published game with your drafts on top
|
||
(the same drafts as the online editor); commit = one commit pushed to Git, the **Game** tool window (right, `Shift+F10` / `Alt+5`) plays the game with the
|
||
drafts beside the code: ⚡ Live puts each save into the running game (hot reload: pictures and sounds in place, code by PHP
|
||
started again in the scene that was playing), Restart, the game's PHP output in its console; tests run
|
||
in the playground's sandbox. The engine's classes and SDL / OpenGL / OpenAL functions resolve there too (sources and stubs
|
||
installed with the IDE by the playground's `bin/ide-install`). Branches, log, blame and local runs are desktop only.
|
||
|
||
### The IDE's tools for an AI (MCP)
|
||
|
||
Each `claude -p` the Claude window starts gets `--mcp-config` (a file only you can read, in the temporary folder) naming
|
||
the IDE's MCP server: HTTP on `127.0.0.1`, a random port, a random token (`Authorization: Bearer`), refused to web pages
|
||
(Origin). Its tools are allowed (`--allowedTools mcp__jumphp-ide`) and told to Claude (`--append-system-prompt`).
|
||
|
||
```
|
||
claude ──HTTP JSON-RPC──▶ McpServer (ide/src/Agent) ──agent.call {call, tool, args}──▶ ide/ui/js/agent.js
|
||
◀── tool result ─── IdeAgent (waits, timeout) ◀──── agent.reply {call, result | error} ───┘ (does it on screen)
|
||
```
|
||
|
||
| Tool | |
|
||
|---|---|
|
||
| `get_state` | open files, the active one with its cursor and selected text, tool windows, run configurations (ids), problems |
|
||
| `open_file` {path, line, end_line} | opens and selects |
|
||
| `highlight` {path, start_line, end_line, message} / `clear_highlights` | marks lines with a note (violet) until cleared |
|
||
| `show_diff` {path?} | the diff with HEAD, or the Commit window |
|
||
| `show_tool` {tool} | project, commit, run, find, problems, game, git… |
|
||
| `find_in_files` {query, regex, include} | shown in Find, the counts returned |
|
||
| `run` {config, wait} | a configuration id (`test:pong`) or `bin/jumphp test|shot|build|webshot|lint|run|app:test… <id>` (only bin/jumphp's, not any program): in the Run window; returns exit code, tests, screenshot, end of the output |
|
||
| `play` {path} | as the IDE's Play (a scene, a test file) |
|
||
| `diagnostics` {path?} | the IDE's PHP problems |
|
||
| `ask_user` {question, options} | a dialog; the answer (10 min at most) |
|
||
| `notify` {message, kind} | a notification |
|
||
| `debug_breakpoints` {path, lines, clear_all} | sets a file's breakpoints (lines, or `{line, condition}`), shown in the gutter; no path: the list |
|
||
| `debug_run` {config, timeout} | a configuration under the debugger (as Debug): waits until a breakpoint stops it, then where, the stack, the locals; or it ended / still runs |
|
||
| `debug_state` {frame} / `debug_variables` {name, frame} | where it stopped, a frame's variables, the children of one (`$this->player`) |
|
||
| `debug_step` {action} | step_over, step_into, step_out, run, stop: waits for the next stop |
|
||
| `debug_eval` {expression} | PHP evaluated where it stopped (shown in the Debug window too) |
|
||
| `debug_run_to` {path, line} | runs to that line (Run to Cursor) |
|
||
| `debug_set_value` {name, value, frame} | a variable given a new value (a PHP expression) |
|
||
| `debug_exceptions` {classes} | exceptions that stop it where thrown (`*`: all; `[]`: none) |
|
||
|
||
Add one: its definition in `AgentTools::all()` (name, description, JSON schema, timeout), its `tool_<name>(args)` in
|
||
`AgentTools` of `agent.js`. Tests: `ide/tests/AgentTest.php` (the protocol over a real socket). The web IDE (Claude of
|
||
your computer through jumphp.net) has Follow, not the tools yet.
|
||
|
||
## Commands
|
||
|
||
```bash
|
||
bin/jumphp install ide # composer install (and Monaco into ide/ui/vendor/)
|
||
bin/jumphp app:run ide # the IDE on your screen (Docker: see below)
|
||
bin/jumphp app:test ide # php -l, phpstan, phpunit (AppTestCase), the app for real on Xvfb
|
||
bin/jumphp app:export ide # games/ide/dist/standalone/ide-linux-x86_64: the IDE as one executable
|
||
bin/jumphp php ide vendor/bin/phpunit # the core's tests
|
||
games/ide/tools/shot.sh var/screenshots/x.png 600 /workspace "<javascript>" # a screenshot driven by a script
|
||
```
|
||
|
||
**Use the exported executable** to work on your projects: it runs on your computer, with your `git` and your Docker
|
||
(`bin/jumphp run / test` of the projects need Docker, as always). `app:run` runs the IDE inside the Tauri image: fine to
|
||
try it, but there it only sees the JumPHP repository and has no Docker.
|
||
|
||
Environment: `JUMPHP_IDE_SERVER` (another jumphp.net, e.g. `http://jumphp.localhost:8000`), `JUMPHP_IDE_PROJECTS` (where
|
||
projects are cloned, default `~/JumPHP-Projects`), `JUMPHP_IDE_PROJECT` (open this folder), `JUMPHP_IDE_EVAL` (JavaScript run
|
||
in the page once loaded: checks and screenshots).
|
||
|
||
**Releases**: bump project.yaml `version`, then `games/ide/tools/release.sh "What is new."`. It runs
|
||
`bin/jumphp app:release ide --linux --windows --macos` (the executables + `update.json` signed with
|
||
`~/.jumphp/keys/ide-update.pem`: **keep a copy of that key**, without it the installed IDEs can never be updated again;
|
||
its public half is `games/ide/config/update.pub`, inside the IDE), attaches them to the GitHub release `ide-v<version>`
|
||
(with the installers of the previous release), checks every address answers, then commits and pushes
|
||
`games/ide/installer/update.json` and `version.json` on main. The installers already given read `version.json` there
|
||
and install the newest version: no need to remake them.
|
||
|
||
**The IDE updates itself** (`games/ide/src/SelfUpdate.php`): 8 s after it starts and every 6 hours it reads
|
||
`games/ide/installer/update.json` on main (project.yaml `app.update.url`), checks its signature, and when the version is
|
||
newer downloads it, checks its SHA-256 and puts it in place of its executable, in the background; a notification then
|
||
offers *Restart Now* (otherwise the next start runs it). Help > Check for Updates…, Help > Update Automatically (on by
|
||
default). Run from its sources it only says a newer version is out. `JUMPHP_UPDATE_URL` tries another update.json,
|
||
`JUMPHP_IDE_UPDATES=0` turns the checks off (tests). IDEs older than 0.1.3 have no updater: reinstall them once.
|
||
Not `tools/github-release.sh` (it points the installers to the repository's newest release, which is JumPHP's, not the IDE's).
|
||
Remaking them (another installer version, pictures, `install.yaml`): from a jumphp2installer clone, with the package
|
||
folder copied into it and its base installers in `bases/` (`gh release download installer-v… -p 'jumphp2installer-*'`):
|
||
`bin/jumphp php . tools/package-release.php <pkg> https://git.jumphp.net/jumphp/jumPhp/raw/branch/main/games/ide/installer/ bases out`,
|
||
then `gh release upload ide-v<version> out/JumPHP-IDE-setup*`. `games/ide/tools/installer-banner.php` remakes its pictures (the banner, the icon, and `jumphp-ide.ico` for the Windows shortcuts).
|
||
|
||
The IDE's own files: `~/.local/share/ide` (exported) or `games/ide/var/` (session, recent projects, PHP index cache).
|
||
A project's IDE settings: `.jumphp/ide.json` (its jumphp.net project, a CPC disc path), kept out of git
|
||
(`.git/info/exclude`); custom run configurations: `.jumphp/run.json` (`[{"label": "…", "command": ["…"]}]`).
|
||
|
||
## Playground side
|
||
|
||
See the playground's README ("Le JumPHP IDE"): `bin/ide-install --from ../JumPHP` copies `ide/src` and `ide/ui` into it;
|
||
routes `/ide`, `/ide/<slug>`, `/ide/connect`, `/studio/ide`, `/api/ide/*` (Bearer `jpi_…`) and `/api/ide/<slug>/invoke`.
|
||
|
||
## Logs
|
||
|
||
**View > Logs** (`Alt+F11`, also Help > Show Logs): the IDE's detailed logs as they happen, like `tail -f` but visual. What the IDE does and
|
||
fails at, and every program it runs (`bin/jumphp`, Docker, git, Claude, OpenCode…: the command, how it ended, and the end of its
|
||
error output when it failed), with a level (debug / info / warn / error), a source, a text search, **Pause** / follow, Copy and Clear. An
|
||
error that arrives while the window is closed puts a red mark on its button. The same lines go to `<IDE data folder>/logs/ide.log`
|
||
(turned into `ide.log.1` at 2 MB: two files at most): the folder button copies its path, send it with a bug report.
|
||
|
||
## AI: online, local, and for the code
|
||
|
||
**Generate… in the resource editors** (sprites, sound effects, tunes, levels, tilesets) asks one of:
|
||
|
||
| provider | needs | where it runs |
|
||
|---|---|---|
|
||
| Claude | the `claude` command, your login | Anthropic |
|
||
| OpenCode | the `opencode` command ([opencode.ai](https://opencode.ai)); Model: `provider/model`, the list is `opencode models` | the model OpenCode is set up for |
|
||
| OpenAI, Mistral, Groq, OpenRouter, Google Gemini | your API key (kept in the IDE on this computer, never in the project) | online |
|
||
| **Ollama**, **LM Studio**, **llama.cpp**'s server, any other OpenAI-compatible server (address + model) | nothing | **your computer: nothing leaves it** |
|
||
| OpenAI Images | your API key | online (sprites and tilesets: the picture is made pixel art) |
|
||
| **ElevenLabs** sound effects and music | your API key | online: a **real sound** (mp3, 1-30 s for an effect, 10-300 s for music) |
|
||
|
||
A **tileset** (the tileset editor's Generate…: tile size, columns, rows) comes back as a sheet of tiles that fit side by side, drawn as a
|
||
PNG next to the `.tsj`, with the collision each tile should have (full, one-way, none): the editor then goes on as with any tileset
|
||
(click a tile to change its collision). A **real sound** is not an editor's setting but an audio file: it is saved as an mp3 next to
|
||
the resource being edited (`assets/sfx/<description>-<code>.mp3`, `assets/music/…`) and the notification opens it; a game plays mp3
|
||
as it is (`SoundManager::loadSfx`, `loadMusic`).
|
||
|
||
The chat services speak OpenAI's chat completions API (`<server>/chat/completions`, JSON answers); the Model field lists
|
||
what the server has (`<server>/models`). Models without structured output get the JSON schema in the prompt, the JSON is found
|
||
wherever the model put it, and an answer the editor cannot use is sent back once with what is wrong (small local models
|
||
often need that second try). The core checks every answer before an editor gets it.
|
||
|
||
**Code**: the Claude window (Alt+8) has an **assistant** selector, **Claude** or **OpenCode**. With OpenCode each message is an
|
||
`opencode run --format json` in the project's folder (`--session` goes on with the conversation, `--model provider/model` from the
|
||
list of `opencode models` or typed), and its answer, the files it reads and edits, the commands it runs appear in the window as
|
||
Claude's do. With a local model set up in OpenCode (Ollama, LM Studio), the code stays on your computer. It answers one message at a
|
||
time and edits files directly (there is no "ask first" mode): review its changes with Git. Switching assistant starts a session
|
||
of its own. Tools > **OpenCode (code assistant, local models)** still opens its full interface in the Terminal, and
|
||
**Ask OpenCode…** sends one request there.
|
||
|
||
## Debugging from a terminal's Claude Code
|
||
|
||
`bin/jumphp debug` is the same debugger as an MCP server (stdin / stdout, in Docker), for Claude Code run in a terminal:
|
||
|
||
```bash
|
||
claude mcp add jumphp-debug -- bin/jumphp debug
|
||
```
|
||
|
||
It waits for Xdebug on port 9003 (`JUMPHP_DEBUG_PORT`). With `JUMPHP_DEBUGGER=php-debugger` it starts PHP Debugger's own MCP server instead (`dbgp mcp`, install `dbgp` from https://php-debugger.dev/agentic-debugging/installation: `claude mcp add dbgp -- dbgp mcp`). Claude sets breakpoints (`debug_breakpoints`) or exceptions
|
||
(`debug_exceptions`), starts the program itself in the background with `JUMPHP_XDEBUG=9003` (`JUMPHP_XDEBUG=9003
|
||
bin/jumphp test pong`, `shot`, `php`...), then `debug_wait` (where it stopped, the stack, the variables), `debug_step`,
|
||
`debug_run_to`, `debug_eval`, `debug_variables`, `debug_set_value`. Paths are relative to the project.
|
||
|
||
## Quick editor and "Open with JumPHP"
|
||
|
||
`jumphp-ide <file>` (or `jumphp-ide --edit <file>`) opens one file of the disk in a light window (`ide/ui/quick.html`): Monaco
|
||
only, no project, no index, no Git. Ctrl+S saves (written next to it then renamed; a file changed by another program since it
|
||
was opened is not overwritten without a yes), Ctrl+O opens another file, "Open the folder as a project" opens the whole IDE on
|
||
the file's folder. Binary files and files over 20 MB open read only. `jumphp-ide <folder>` (or `--project <folder>`) opens the
|
||
folder as a project. Code: `games/ide/src/QuickEditor.php`, `Main::launch()`, `ide/ui/js/quick.js`.
|
||
|
||
**Tools > Integrate with the System…** adds "Open with JumPHP" (a file) and "Open as a project in JumPHP" (a folder) to the
|
||
file manager, for the current user only, no administrator rights (and removes them): Windows: keys of
|
||
`HKCU\Software\Classes` (`*\shell`, `Directory\shell`, `Directory\Background\shell`); Linux: two `.desktop` files of
|
||
`~/.local/share/applications` (the "Open with" lists), Nautilus scripts, Nemo actions, Caja / file-manager actions, Dolphin
|
||
service menus (`games/ide/src/OsIntegration.php`). It needs the installed IDE (its executable); from the sources it says so.
|
||
Not on macOS yet. Each launch is its own IDE process (no forwarding to a window already open).
|
||
|
||
## Roadmap
|
||
|
||
The debugger for remote / browser games, terminal tool window, PHP formatting, local history, more refactorings (extract
|
||
method / variable, move class), a tile map editor for games, multiple projects in one window, signed macOS / Windows executables.
|
||
|
||
## Code updates (no new executable)
|
||
|
||
The desktop IDE is an executable (PHP + the Tauri runtime) that carries its own code. A **code update** replaces only the code: the IDE downloads one
|
||
small signed archive (about 0.5 MB: `games/ide/src`, `config`, and the IDE package's `src` and `ui`, without Monaco) and runs from it at its next start.
|
||
Making one takes a minute (`games/ide/tools/release-code.sh "notes"` after raising `version` in `games/ide/config/game.yaml`), against a quarter of an hour
|
||
for the three executables (`games/ide/tools/release.sh`, still needed when the executable changes). The mechanism is `JumPHP\Tauri\Overlay` (engine), the
|
||
IDE's side `games/ide/src/CodeUpdate.php`; the archive and the signed `update.json` are made by `tools/overlay-build.php`.
|
||
|
||
How it stays safe:
|
||
- the archive is announced by the **signed** `update.json` (`overlay`: version, `compat`, https address, SHA-256) and installed only if the download matches that
|
||
SHA-256, then every file matches the SHA-256 of the archive's manifest;
|
||
- an overlay writes **only** in `src/`, `config/`, `vendor/jumphp/ide/src/` and `vendor/jumphp/ide/ui/`: never the engine, the executable or Composer's autoloader;
|
||
a path with `..`, an absolute path, anything else is refused. `config/update.pub` (the key that checks updates) is never in an overlay;
|
||
- `overlay_compat` in `game.yaml`: the number of the executable's generation. An overlay made for another number is ignored. Raise it when a release changes what an
|
||
overlay cannot carry (the engine's code, a PHP extension, the runtime, a dependency in `games/ide/composer.json`) and publish a full release;
|
||
- **rollback by itself**: from the moment an overlay starts, it is *pending* until the IDE's page has loaded and asked for its state (`session.state`). If the next start
|
||
finds it still pending after a **PHP fatal error** (parse error, uncaught exception: written down by a shutdown function), it is marked bad, never tried again (the signed update.json
|
||
offering it is ignored), and the IDE runs from the files of its executable. A start that was only *not confirmed* (a frozen window killed by the user: it also happens without any
|
||
overlay) gets another try, and the overlay is dropped after 3 such starts in a row (`Overlay::MAX_TRIES`);
|
||
- the executable's own files are never touched: the overlay runs from a copy made with hard links (`<cache>/ide-<build>-ov-<version>`), the older copies are removed;
|
||
- `JUMPHP_NO_OVERLAY=1` starts the IDE from its executable's files (and leaves the overlay alone), for a bug that needs ruling out;
|
||
- installers install the last **full** release (`version.json` is not touched by a code update); the new IDE then takes the code update by itself at its first check.
|
||
|
||
Seen in the IDE as a normal update: "available", "installing", "Restart now". The version shown is the overlay's. Executables older than 0.1.77 do not know code updates:
|
||
they are updated by the full release, then take the following code updates.
|
||
|
||
## Text size per panel (Ctrl + mouse wheel)
|
||
|
||
Ctrl + wheel over a panel (a touchpad pinch too) changes the font of **that** panel only: up = bigger, down = smaller; the page's own zoom is stopped there only. `Ctrl+=`, `Ctrl+-`, `Ctrl+0` do the same when the panel has the focus (View > Increase / Decrease / Reset Font Size, Reset All Zoom; a double click on the small badge resets too).
|
||
|
||
- the code editor: one size for every editor (8 to 40 px, 1 px steps; Settings > Editor font size is its default); the Terminal: its font (8 to 40 px, the shell is told the new size);
|
||
- every other tool window (Claude, Run, Debug, Git, Find, Problems, Logs, Profiler, Project...): a scale of the whole panel (50 to 300 %, 5 % steps, CSS `zoom`), the Claude conversation stays at its end.
|
||
- Ctrl + Shift + wheel, anywhere: the **whole IDE** (50 to 250 %, 10 % steps; View > Zoom In / Out / Reset the Whole IDE). On the desktop it is the WebView's own zoom (`Window::setZoom()`, like a browser's Ctrl + / -: clicks stay exact, in Monaco too); in a browser, or with a runtime library older than this, CSS `zoom` on the page. Kept in prefs (`zoom:ui`), the same for every project (not in the layout record); Reset All Zoom resets it too.
|
||
- The wheel is added up: a mouse notch is one step, a touchpad / pinch makes one step every ~60 px instead of one per event; the panel is redrawn at most once per frame and saved 0.4 s after the wheel stops.
|
||
- Kept per panel in prefs (`zoom:<id>`) and in the window layout record (`layout.v1`, key `zoom`, optional: older records have none). Code: `ide/ui/js/zoom.js`; tests: `zoom.test.mjs`, `games/ide/tools/ui-zoom-check.sh` (`ZOOM_SHOTS=<dir>` keeps screenshots at 8 / 14 / 40 px).
|
||
|
||
## Symfony Validation and Security
|
||
|
||
User documentation: [docs/ide/validation-security.md](ide/validation-security.md). Windows: `ide/ui/js/symfony-validation.js`,
|
||
`symfony-security.js`, `symfony-diff.js` (the difference shown before writing; `css/symfony-tools.css`); capabilities `validation` / `security`.
|
||
|
||
The PHP side: `ide/src/Symfony/` — `ValidationCatalog`, `ValidationClass` (read / edit with php-parser positions: only the attribute
|
||
changes, use lines added), `ValidationPhp`, `ValidationProject` (classes, custom constraints, YAML / XML mappings),
|
||
`ValidationGenerator`, `ValidationCommands` (`validation.*`), `SecurityConfig`, `SecurityYamlEditor`, `SecurityAccessControl` (Symfony's
|
||
matching, shadowed rules), `SecurityRoutes` (routes, matrix, `#[IsGranted]` edits), `SecurityGenerator`, `SecurityCommands`
|
||
(`security.*`). Tests: `ide/tests/SymfonyValidationTest.php`, `ide/tests/SymfonySecurityTest.php` (exact outputs, YAML round trips),
|
||
`games/ide/tools/ui-symfony-security-check.sh` (a copy of a Symfony project, `SX_SHOTS=<dir>` keeps the screenshots). Limits: only PHP
|
||
attributes are edited (YAML / XML mappings and annotations are shown, not changed); routes come from `#[Route]` attributes of
|
||
`src/Controller` (not config/routes YAML); the matrix treats an access_control rule's roles as "any of them" and voters as unknown;
|
||
`when@<env>` blocks are not edited by the forms.
|
||
|
||
## Symfony Forms
|
||
|
||
User documentation: [docs/ide/symfony-forms.md](ide/symfony-forms.md). Window: `ide/ui/js/symfony-forms.js` (the list, the form
|
||
builder, the diffs), `symfony-forms-model.js` (Symfony's types with their options by kind, the validator's constraints, events, themes),
|
||
`symfony-forms-preview.js` (the HTML of `form_div_layout`, `form_table_layout`, `bootstrap_5_layout`, `tailwind_2_layout` with the
|
||
error states, made without PHP; shown by `html-preview.js` in the page `twig-preview.js` lays out from `base.html.twig`),
|
||
`css/symfony-forms.css`; capability `symfonyForms`.
|
||
|
||
The PHP side: `ide/src/Symfony/` — `FormTypeParser` (php-parser: add() chains or one statement per add(), options arrays, constraints
|
||
`new Length(min: 3)` or `new Length(['min' => 3])`, events `[$this, 'method']`, `$builder->get('x')->addModelTransformer(new X())`,
|
||
configureOptions' setDefaults; what is in an `if`, a closure listener, a CallbackTransformer is read "locked"), `FormTypeWriter` (only
|
||
what changed is written, by text edits at php-parser's positions: an option's value, an option line added / removed in the same style,
|
||
a chain's segments moved, statements removed, listener methods and `use` lines added; the rest byte for byte; a new FormType as
|
||
maker-bundle writes them), `FormValues` / `Imports` (values ↔ PHP code, `@class` / `@new` / `@php`, aliases of the file such as
|
||
`Assert\`), `FormFieldSuggester`, `FormCodeGenerator` (controller action, template, transformer class, twig.yaml form_themes),
|
||
`FormCommands` (`forms.list`, `forms.read`, `forms.model`, `forms.write`, `forms.suggest`, `forms.generate`, `forms.themes`: they
|
||
return texts before / after, the window writes after the diff; the model crosses the desktop bridge as a JSON text so that choices keep
|
||
their order). Tests: `ide/tests/SymfonyFormsTest.php` (fixtures `ide/tests/fixtures/forms/`: the exact FormType of every kind of
|
||
field, a hand-written one read back with its locked parts, byte-identical round trips, one option / options / fields / events /
|
||
transformers changed, suggestions from an entity, controller / template / twig.yaml), `ide/ui/js/symfony-forms-preview.test.mjs`
|
||
(HTML per theme, with errors), `games/ide/tools/ui-forms-check.sh` (screenshots on a copy of a Symfony project). Checked on a Symfony 8.1
|
||
project: the generated FormType, controller and template pass `debug:form`, a GET renders every field with Bootstrap 5's classes, an
|
||
invalid POST answers 422 with the constraint's message, a valid one redirects (303) and shows the flash. Limits: a field moved to
|
||
another `$builder` statement stays in its own; removing an event or a transformer leaves its method / class; the preview does not draw a
|
||
project's own theme blocks; EntityType choices and enum labels are samples.
|
||
|
||
## Security Audit
|
||
|
||
User documentation: [docs/ide/security-audit.md](ide/security-audit.md). Window: `ide/ui/js/security-audit.js` (`css/security-audit.css`,
|
||
capability `securityAudit`, desktop only: registered with the terminal). The PHP side, `ide/src/Audit/`:
|
||
`Auditor` (the deterministic checks, each one guarded, one-line fixes), `Checks/ConfigCheck` (security.yaml, framework, nelmio_cors,
|
||
.env files), `Checks/PhpCodeCheck` + `Checks/TaintState` (php-parser, request data followed inside a function to SQL / shell /
|
||
unserialize / redirects / responses / dynamic setters; routes, IDOR candidates, access_control gaps; templates rendered with request
|
||
data), `Checks/TwigCheck`, `Checks/SecretsCheck` (git's tracked files), `Checks/DockerCheck`, `Checks/DependencyCheck` (composer /
|
||
npm audit JSON), `Checks/HeadersCheck`, `Rules` (ids, severities, OWASP; the texts are the window's, translated), `Redactor` (secrets
|
||
masked everywhere: findings, prompts, storage), `AuditStore` (`.jumphp/security/state.json`, `audits/*.json`), `Patches` (a patch
|
||
applied near its finding, unified diff; written through `Symfony\CodeChanges`), `AiReviewer` (claude -p / opencode run / chat servers
|
||
like the Translations window: batches of a few files, excerpts, JSON schema, patches checked against the file, logic flaws),
|
||
`LocalGuard` (the hard-coded allow-list: localhost, *.localhost, 127/8, ::1, compose services on Docker networks; every resolved
|
||
address checked, the request pinned to it), `Probes` (read-only GET plans, verdicts, `.http` files in `http-requests/security-probes/`),
|
||
`AuditCommands` (`audit.*`, its own `Transport` polled by `Ide::tick`).
|
||
|
||
Tests: `ide/tests/SecurityAuditTest.php` (every check on fixtures, true and false positives; the guard with DNS tricks; storage
|
||
without secrets; patches and recheck; AI batching with a fake AI; probes with a fake site, answers arriving frames later) and
|
||
`games/ide/tools/ui-security-audit-check.sh` (`SA_PROJECT` a vulnerable copy of a Symfony project, `SA_SITE` its `web:serve` site,
|
||
`SA_SHOTS=<dir>` keeps the screenshots). Limits: intra-function data flow only; proofs only for GET routes; no automatic proof for
|
||
commands, uploads, unserialize and mass assignment.
|
||
|
||
## Performance
|
||
|
||
What runs every frame and what the editor asks at every key is kept short: the desktop app's PHP runs on the window's own thread
|
||
(Tauri calls it each frame), so any long piece of PHP is a frozen window.
|
||
|
||
- **The editor's questions on the same text are answered from one parse.** `Php\Analyzer` keeps the last texts parsed (3 trees) and
|
||
analyzed (8) by hash; hover, definition, completion, outline, diagnostics and highlights of one version of a file share them. Parsing
|
||
runs without PHP's cycle collector (it walked the new tree and the whole index again: 22 to 65 ms for one parse, depending on when).
|
||
`QueryVisitor` skips the functions the cursor is not in and everything after it.
|
||
- **Find usages, the calls lenses, the highlights look only at the files that name the symbol** (`Index::filesReferencing()`, an
|
||
inverted index of reference names kept up to date file by file), and `Index::update()` does nothing when the editor's text did not change.
|
||
- **`php.callCounts`**: every "↳ N calls" lens of a file in one question (Monaco resolved them one by one, each a `php.calls` with the
|
||
whole text: 30 lenses = 2 s of PHP after every change); the counts of one version of the text are kept in the page.
|
||
- **`php.highlights`**: the symbol's places in this file only, asked once the cursor rests (120 ms): it was `php.symbol` + `php.references`
|
||
over the whole project at every cursor move.
|
||
- **The index cache is used at the next start**: its JSON gave every `mtime` back as an int, so every project file was analyzed again at
|
||
each start. The libraries' cache is JSON lines, read a slice per frame and decoded only when its file is reached, written a slice per
|
||
frame and only when something changed; the libraries' folders are listed one per frame.
|
||
- **The first indexing runs on every core** (`Async\WorkerPool`, see below).
|
||
|
||
### Workers (every core, desktop only)
|
||
|
||
The IDE runs on the desktop runtime (PHP 8.5 NTS, and StaticPHP's micro once exported): no threads there (TrueAsync's threads need the
|
||
async runtime, PHP 8.6 ZTS). So the multi-core path is **helper processes** of the same PHP: `ide/bin/ide-worker.php` (`Async\Worker`),
|
||
started by `Async\WorkerPool` with `proc_open` (the IDE's `Processes`: non-blocking pipes, temporary files on Windows). An exported IDE
|
||
starts its own executable with `JUMPHP_WORKER_SCRIPT` (tools/standalone-stub.php runs that script of the app instead of the app; an
|
||
older executable has no such stub: no pool).
|
||
|
||
- Jobs are JSON lines (`analyze` a project file, `declarations` a library file), answers one line each; plain values only. A worker
|
||
gets 8 jobs at a time (its pipe never fills), runs at a lower priority (`proc_nice(5)`: on a loaded computer the window keeps its frames, the indexing takes longer).
|
||
- `poll($budget)` reads the answers between frames, settles `Deferred`s; an error in a job comes back as a value (`WorkerError`), the
|
||
worker goes on.
|
||
- A worker that dies (fatal error, killed) or hangs past its job's timeout (60 s) is stopped and replaced; its jobs are tried once more,
|
||
then rejected. Six deaths in a minute, or workers that never say they are ready, and the pool closes itself.
|
||
- The `Index` gives files to the workers only when there are many (more than 24) and once a worker is ready; it analyzes them itself
|
||
meanwhile, and does any rejected job itself: the single-thread path is always there.
|
||
- Size: cores - 1, at most 8; let go once the indexing is done. Off: `JUMPHP_IDE_WORKERS=0` (or `=N` workers), or the command
|
||
`perf.workers {enabled: false}` (kept in the cache folder: `workers.off`).
|
||
|
||
### Measuring
|
||
|
||
- `bin/jumphp php games/ide tools/perf-bench.php /workspace [--cold] [--base <checkout>] --json out.json`: the core on a project (frames
|
||
while it indexes and idle, the host's file scan, the editor's commands on a big file, each typed again: a new text every time);
|
||
`tools/perf-compare.php a.json b.json` side by side. `--base` runs the same bench on the core of another checkout (a `git worktree`
|
||
of the commit before).
|
||
- `games/ide/tools/perf-ui.sh [project] [file] [--base <checkout>]`: the real IDE on a virtual screen: round trip of a tiny command,
|
||
frame gaps, a key typed -> next painted frame, while indexing, typing, scrolling, opening windows.
|
||
|
||
Before / after (JumPHP's repository, `ide/src/Ide.php` 1000 lines, 8 workers; ms, p50 unless said):
|
||
|
||
| | before | after |
|
||
|---|---|---|
|
||
| first indexing (cold), whole | 16.1 s | 3.7 s |
|
||
| its longest frame | 284 | 32 |
|
||
| next start (warm), whole | 3.8 s | 1.2 s |
|
||
| next start, peak memory | 315 MB | 161 MB |
|
||
| Symfony project (9 500 library files), cold | 8.9 s, frames up to 187 | 2.0 s, frames up to 14 |
|
||
| all "N calls" lenses of the file | 2 086 | 29 (one `php.callCounts`) |
|
||
| highlights at a cursor move | ~135 (symbol + references) | 10 |
|
||
| hover / definition after a change | 27 / 31 | 0.8 / 0.7 |
|
||
| outline | 31 | 0.2 |
|
||
| find usages | 106 | 15 |
|
||
| diagnostics (the first question on a new text: parses it) | 65 | 60 |
|
||
|
||
The real IDE (`perf-ui.sh`, the Symfony project + a 1000-line file, 8 workers, on a computer loaded by other jobs: load average
|
||
10 to 50, so the numbers are noisy): while it indexes, frame gaps p50 17 ms / p95 47 ms and a command's round trip p50 21 ms with the
|
||
workers at a lower priority (p50 174 ms / 35 ms when they were not); idle round trip p50 10 ms.
|
||
Limits: Monaco itself (the WebView's rendering) is not changed; the first diagnostics of a new text still parses it (~20 ms for 1000
|
||
lines) in the frame; the host's scan of the project's files every 3 s (8 ms for JumPHP's repository) stays in a frame.
|