ES

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), 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): 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).