winzik/docs/web.md
David Nurdin 23966a2d07 Web sites: reliable live reload between the browser and the IDE
The reload container (docker/web-dev/live.js, browser-sync) now publishes the site's port itself, so the page's socket can connect
(the old proxy ws option moved it to an unpublished port: the tab never followed). The IDE tells it each saved file (POST /__jumphp/notify),
so it works without file events (Docker Desktop also polls); CSS is injected without a reload, anything else reloads once.
Status bar item Live: N (browser tabs connected), open the site at the live-reload address, turn it off ('live': 'off' in web.json).
bin/jumphp web:live, LiveReload (IDE) + tests, end-to-end test with headless Chrome on a Symfony site, docs, 14 languages.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-16 10:31:20 +01:00

129 lines
12 KiB
Markdown

# Web sites (not games): Symfony, WordPress, PrestaShop, Sylius, Laravel, PHP
The JumPHP IDE (New Project > Web site, or any PHP site opened as a project) and `bin/jumphp web:*` make and serve web
sites, on any folder, with nothing installed but Docker (`tools/web.sh`, image `docker/web-dev`).
| Command | What it does |
|---|---|
| `bin/jumphp web:new <kind> <folder>` | a new site: `symfony` (skeleton + webapp, `.env.local` on the database), `wordpress` (wordpress.org), `prestashop` (the latest GitHub release), `sylius` (sylius-standard), `laravel`, `php` |
| `bin/jumphp web:serve [folder]` | FrankenPHP (the site's PHP, below, + pdo_mysql, gd, intl, zip, opcache, xdebug...), MariaDB 11.4 when the site needs one, browser-sync (live reload, [below](#live-reload)), and the assets: `npm run watch` / `dev` when `package.json` has it, else `sass --watch` on the folders holding `.scss`; prints `[web] open <url>` (the IDE opens the browser there), then the logs |
| `bin/jumphp web:stop [folder]` | stops it; the database stays (a Docker volume) |
| `bin/jumphp web:info [folder]` | its kind and addresses |
| `bin/jumphp web:composer <folder> ...` / `web:console <folder> ...` | composer / `bin/console` (Laravel: `artisan`) in its PHP container |
| `bin/jumphp web:php <folder> [8.x\|auto]` | its PHP version, shown or chosen (below) |
| `bin/jumphp web:live [folder] [status\|notify <file>...]` | the live reload: how many browser tabs follow (JSON); tells it a file was saved (what the IDE does at each save) |
| `bin/jumphp web:docker <folder> [jumphp\|dunglas\|compose [service] [file]]` | its Docker setup, shown or changed (below) |
Addresses (fixed per folder): the site with live reload `http://localhost:P`, PHP directly `P+1`, the database `P+2`
(`mysql://app:[email protected]:P+2/app`; from the site: host `db`, port 3306, user / password / database `app`).
The kind is guessed (WordPress, PrestaShop, Sylius, Laravel, Symfony, else plain PHP) or read from `.jumphp/web.json`;
`.jumphp/` (the compose file made at each start) is kept out of git.
## Database, symfony-docker, debugging
- **The database** of a site: `bin/jumphp web:new <kind> <folder> --db=mariadb|postgres|sqlite|none` (the IDE's New Project > Web site asks
it), changed later with `bin/jumphp web:db <folder> <db>` (or Run > Site > Database: …). Symfony / Sylius get `DATABASE_URL` in `.env.local`,
Laravel its `DB_*`; `web:serve` starts MariaDB 11.4 or PostgreSQL 16 (user `app`, password `app`, database `app`, host `db` from the site,
`127.0.0.1:<port+2>` from this computer); SQLite is `var/data.db`. WordPress and PrestaShop need MariaDB.
- **symfony-docker** ([dunglas/symfony-docker](https://github.com/dunglas/symfony-docker)): `bin/jumphp web:new symfony <folder> --docker=dunglas`
makes the project inside its Dockerfile and compose.yaml (PostgreSQL through its Doctrine recipe, MariaDB: that recipe turned into a `mariadb:11.4` service with `pdo_mysql`, SQLite or none); an existing Symfony site
moves to it with `bin/jumphp web:dockerize <folder>` (its own compose files kept as `*.before-symfony-docker`). `web:serve` / `web:stop` /
`web:composer` / `web:console` then drive its own stack (plain http on the site's port).
- **Debug**: the IDE's Debug on "Serve the site" turns Xdebug on in the site's container (off otherwise, no cost): breakpoints in the gutter
stop the requests; the container's `/app` is the project. **Cryo**: "Run with memory metrics" works for any PHP program run through
bin/jumphp (CLI apps included).
- **The Symfony toolbar** works through the live-reload address: browser-sync keeps the browser's Host (`.jumphp/live.js`).
- `web:composer` / `web:console` run in the site's running container when it is up (its database is reachable), else in a new one.
## The PHP version
One PHP per site, the same for `web:serve`, `web:composer`, `web:console` and the IDE's Console and Composer windows, so the
dependencies Composer resolves and the PHP that runs them agree (otherwise: "Composer detected issues in your platform: Your
Composer dependencies require a PHP version >= 8.5.12. You are running 8.4.27").
- Offered: the versions FrankenPHP has images for, **8.2, 8.3, 8.4, 8.5**. The JumPHP stack builds one image per version,
`jumphp/web:php<x.y>` (`docker/web-dev`, build argument `PHP_VERSION`), the first time it is needed.
- Chosen: `bin/jumphp web:php <folder> 8.5` (or the IDE: the PHP selector of the Console window, Docker window > Compose > PHP),
kept in `.jumphp/web.json` (`"php": "8.5"`). `web:php <folder> auto` goes back to the default; `web:php <folder>` shows it and why.
- Default: what Composer needs: `config.platform.php` of composer.json when it has one, else the newest offered version that
composer.json's `require.php`, composer.lock's platform and every locked package's `require.php` allow (`tools/web-php.php`,
kept in `.jumphp/php.auto` until those files change); a site without composer.json: 8.4. `web:new` remembers the PHP it made
the site with (`--php=8.x` to choose it).
- Applied to the Docker setup: the JumPHP stack uses that image (a running site is restarted on it); symfony-docker gets its
Dockerfile's `FROM dunglas/frankenphp:1-php<x.y>` rewritten (rebuilt at once when it runs); an own compose stack gets the image
tag of its PHP service rewritten (`php:8.3-fpm` -> `php:8.5-fpm`, or its Dockerfile's `FROM`), else it says to do it by hand.
## The Docker setup
`bin/jumphp web:docker <folder> <setup>` (IDE: Docker window > Compose > Docker setup) says what it changes:
- `jumphp`: the stack `web:serve` writes (`.jumphp/compose.yaml` + the site's `compose.override.yaml`). Coming from symfony-docker,
its files stay in the folder unused, its `compose.override.yaml` is kept as `compose.override.yaml.symfony-docker`, the site's
PHP is kept and `DATABASE_URL` goes to the stack's `db`.
- `dunglas`: symfony-docker (`web:dockerize`): its Dockerfile, compose files and `frankenphp/` (the site's own compose files kept
as `*.before-symfony-docker`), its Dockerfile set to the site's PHP; going back to it reuses the files already there.
- `compose [service] [file]`: the site's own compose file (default: the one `docker compose` reads); `web:serve` = `docker compose
up`, `web:console` / `web:composer` run in that service (`exec` when it runs, else `run --rm --no-deps`). Without a service
name: `php`, `app`, `php-fpm`, `fpm`, `web` or `frankenphp`, the first one it has.
- A JumPHP stack does not merge a `compose.override.yaml` written by Symfony Flex's recipes (`###> doctrine/doctrine-bundle ###`
blocks for compose.yaml's `database`) while Compose refuses it with the stack: it says so.
**Local PHP** (IDE): the Console window can run `bin/console` / `artisan` with the computer's PHP instead (Docker / Local PHP,
the `php` of the PATH or a chosen program, its version shown); kept in `.jumphp/web.json` (`"runner": "local"`, `"local_php"`),
and the Composer window then runs the computer's `composer` with it. `.jumphp/` is out of git: nothing secret, nothing shared.
## Customising the stack (Docker Compose)
- `web:serve` writes the stack into `.jumphp/compose.yaml` at each start (out of git). The site's own changes go into
**`compose.override.yaml` at its root** (kept in git): Docker Compose merges it over the generated file
(`docker compose -f .jumphp/compose.yaml -f compose.override.yaml`, the site as project directory: relative paths and `.env`
are the site's). Name a service with only what differs (`app: {environment: {APP_DEBUG: 1}}`, another `db` image, more `ports`),
or add services (Mailpit, Redis, Adminer...).
- `bin/jumphp web:up [folder]` applies a change (the containers whose settings changed are made again, no logs);
`bin/jumphp web:config [folder]` prints the merged stack (a mistake is reported with its file).
- symfony-docker sites keep their own `compose.yaml` + `compose.override.yaml` (Compose reads both by itself).
- **In the IDE**: Docker window > **Compose** tab: the project's compose files per folder (what starts them, in the order they
are merged), create the override, **Add a service** from a template (MariaDB, MySQL, PostgreSQL, Redis, Memcached, Mailpit,
Adminer, phpMyAdmin, RabbitMQ, Elasticsearch, Meilisearch, MongoDB: data in a named volume, ports on 127.0.0.1),
**Check** (`docker compose config`: its errors in the Problems window at their line), **Apply** (`web:up`, or
`docker compose up -d` for any other stack), **Search Docker Hub** (inserts `image: name:tag`).
- The editor reads every `.yaml` / `.yml`: colours (keys, anchors / aliases / `<<`, tags such as `!php/const`, block scalars,
`${VAR:-default}`), problems as one types (syntax with its line and column; in compose files unknown keys, a service without
image nor build, ports / volumes / environment / restart written wrong, `depends_on` / networks / named volumes nobody declares;
in Symfony's `config/services.yaml` its keys), completion (Compose keys and values, ready-made services under `services:`,
`image:` names and tags from Docker Hub, Symfony's services keys), a hover on `image:` (description, stars, pulls), folding
and the outline (Structure window).
## Live reload
The address `http://localhost:P` is browser-sync (`docker/web-dev/live.js`, copied to `.jumphp/live.js` at each start) proxying the site and
injecting its client into every page; the tab follows the saves of the site's files:
- a **CSS** change is injected (the rule changes, no reload: scroll, forms and JavaScript state stay); a change of a `.scss` / `.sass` / `.less`
file is followed by the `.css` the compiler (`sass --watch`, `npm run watch`) writes;
- **Twig / HTML / PHP / JS / `config/*.yaml` / `.env` / translations / JSON / SVG**: the page reloads. FrankenPHP runs with
`opcache.validate_timestamps=1, revalidate_freq=0` and Symfony's dev container rebuilds itself when `config/`, `.env` or the bundles change,
so no cache has to be cleared by hand (`vendor/`, `var/`, `.git/`, `node_modules/` are not watched).
How it is made reliable:
1. **The reload container watches the files** (inotify). Docker Desktop (Windows, macOS) sends no file events on bind mounts: the stack then
polls (`JUMPHP_LIVE_POLL=1` forces it, `0` forbids it; the default looks at `docker info`).
2. **The IDE tells it each save**: `POST http://127.0.0.1:P/__jumphp/notify {"files": ["templates/base.html.twig"]}` (no browser `Origin`
allowed: a web page cannot do it). The watcher and the notice say the same save: it reloads once. The same from a terminal:
`bin/jumphp web:live <folder> notify templates/base.html.twig`.
3. **`GET /__jumphp/status`** (`bin/jumphp web:live <folder>`): `{"ok": true, "clients": <browser tabs connected>, "reloads", "injects", "poll"}`.
4. The socket of the page is on the site's port itself (the reload container publishes `P:P`): a socket on another port nobody publishes
(what `ws: true` of the proxy does) was never reachable from the browser.
5. `.jumphp/web.json` `"live": "off"` (IDE: status bar > Live > Turn live reload off, then restart the site): no reload container, the site is served
on `P` and `P+1` directly.
Test (Docker, network, a few minutes): `bash tools/tests/live-reload.test.sh`: a Symfony site, a headless Chrome on the live-reload address,
a CSS rule, a Twig template and a controller changed; once with the IDE's notice, once with the watcher alone.
Not covered: symfony-docker (`dunglas`) and the site's own compose stack have no reload container (their own server answers on the site's port),
so no live reload; **Alt+click on an element to open its Twig line in the IDE** is not done: it needs the IDE to listen for the link
(`xdebug.file_link_format` / `framework.ide` pointing at it, with the container's `/app` remapped to the project's folder).