magdev/php-qml
1
Fork 0
Code Issues Pull Requests Actions Releases 4 Activity

Phase 5 sub-commit 3: hot-reload docs + .vscode/.idea editor configs

Browse Source 
Skeleton README documents the hot-reload story end-to-end:
- PHP-side: frankenphp run --watch (already what `make dev` uses).
- QML-side: Qt Creator Reload, qmlls live preview, run-from-source.
- Dev console: Ctrl+` toggle from sub-commit 1.

Both skeleton and todo example ship .vscode/ (launch.json with Xdebug
attach + Qt-host gdb launch + a compound config, tasks.json for the
make targets, settings.json) and .idea/runConfigurations/ shell run
configs for `make dev`, `make doctor`, `make quality` (and `make
appimage` in the todo example). PhpStorm's Xdebug listener is global
so we don't ship a project-level run config for it; the README
points users at the toolbar toggle.

php-qml-init also rewrites .vscode/launch.json's binary path and
config label so a fresh scaffold's debugger configs point at the
new project's binary.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Marco Grätsch
2026-05-02 21:28:02 +02:00
parent 975add1760
commit b925774eea
17 changed files with 395 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
framework/skeleton/README.md
View File

@@ -6,7 +6,7 @@ The framework's reference application: a minimal Symfony backend plus a Qt/QML h
- Linux (other platforms land in Phase 4)
- Qt 6.5+ dev packages (`qt6-base-devel`, `qt6-declarative-devel`, `qt6-quickcontrols2-devel`, `qt6-tools-devel`), CMake, gcc-c++
- PHP 8.3+
- PHP 8.4+ (Symfony 8 enforces this)
- [FrankenPHP](https://frankenphp.dev/) on PATH (or set `FRANKENPHP=/path/to/frankenphp`)
- Composer
@@ -63,6 +63,50 @@ curl -X POST http://127.0.0.1:8765/api/todos \
The Mercure SSE stream receives a `correlationKey: my-key-1` envelope which the Qt host's `ReactiveListModel` matches against any in-flight optimistic mutation (PLAN.md §5).
## Hot reload
Both halves of the app reload without re-running `make dev`.
### PHP-side (Symfony / FrankenPHP)
`make dev` runs `frankenphp run --watch` (see `Caddyfile` and `scripts/dev.sh`). FrankenPHP rebuilds the worker on any change under `symfony/` — controllers, services, entities, templates, configuration. Just save the file; the next request through the Qt host hits the new code. There is no opcache to clear and no service to restart.
If you change something Doctrine-mapped, run a fresh migration in another terminal:
```bash
cd symfony
bin/console make:migration
bin/console doctrine:migrations:migrate -n
```
The Qt host stays up across all of this.
### QML-side
The Qt host loads QML from a compiled-in resource bundle, so saving a `.qml` file does **not** flip the running window automatically. Three workflows that do:
- **Qt Creator → File → Reload** (or `Ctrl+R` with focus on a QML file). Rebuilds the QML cache and reloads the window in place.
- **`qmlls` live preview** — the QML language server bundled with Qt 6.5+ runs a live preview connected to your editor (VSCode + the Qt extension, neovim, helix). Edits show up instantly in the preview window without rebuilding.
- **Run from source** — start the host with `QT_QUICK_CONTROLS_CONF=` and `QML_IMPORT_TRACE=1` set, and pass `-DQT_QML_DEBUG` so the running engine accepts a hot-reload connection from Qt Creator. PLAN.md §6 captures the long-term plan to gate this behind `BRIDGE_DEV=1`.
For most edits, Qt Creator's *Reload* is the lowest-friction option. The `.qmlls.ini` file (auto-generated when `qmlls` first runs) configures completion + live preview against this project's QML import paths.
### Editor configs
Both `.vscode/` and `.idea/runConfigurations/` ship with the skeleton.
VSCode (`.vscode/launch.json`):
- **Listen for Xdebug** — attaches the debugger on port 9003 once you set `XDEBUG_MODE=debug` for the FrankenPHP child (e.g. `XDEBUG_MODE=debug make dev`).
- **Run skeleton (Qt host)** — gdb-launches the built binary with `BRIDGE_URL=http://127.0.0.1:8765` so it talks to the dev mode FrankenPHP started elsewhere by `make dev`.
- **Compound: Dev: Xdebug + Qt host** — runs both at once.
PhpStorm (`.idea/runConfigurations/`): `make dev`, `make doctor`, `make quality` shell run configs. PHP debugging is via the toolbar's **Start Listening for PHP Debug Connections** toggle (PhpStorm's Xdebug listener is global, not per-project).
### Dev console
`Ctrl+`` toggles an in-window console showing the bundled FrankenPHP child's stdout + stderr (PLAN.md §8). It's a passive ring buffer (~500 lines) — opening it has no IPC cost. Use it when you don't have a separate terminal to read the dev log.
## Quality checks
```bash