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

docs: rewrite README + add comprehensive docs/

Browse Source 
README is now tight and link-heavy: 60-second tour, then deep links
into docs/. The wall of detail moved out.

docs/ covers the framework end-to-end:
- getting-started.md — prerequisites by distro (Tumbleweed, Fedora,
  Debian/Ubuntu, Arch), full first-run walkthrough, troubleshooting.
- architecture.md — process pair, transport, dev/bundled mode.
- update-semantics.md — state machine + optimistic mutations + key
  round-tripping.
- reactive-models.md — ReactiveListModel, ReactiveObject, Mercure
  dual-publish.
- makers.md — make:bridge:resource/command/window.
- dev-workflow.md — hot reload (PHP + QML), dev console, editor
  configs, bridge:doctor, snapshot/integration test loops, perfsmoke.
- bundled-mode.md — supervisor, per-session secret rotation,
  first-launch migrations, auto-update wiring.
- packaging-linux.md — make appimage, build-appimage.sh CLI,
  AppImageUpdate sidecar, perfsmoke budgets, release CI, bundle-size
  breakdown.
- qml-api.md / php-api.md — exhaustive symbol reference with all
  Q_PROPERTY/Q_INVOKABLE/signals + every public PHP service / attribute
  / command.
- configuration.md — every env var (host, Symfony, dev script,
  packaging script, perfsmoke), every CLI flag (php-qml-init,
  build-appimage.sh), make targets, default ports/paths.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Marco Grätsch
2026-05-02 22:18:37 +02:00
parent 26a2b3771b
commit da048434b8
13 changed files with 2338 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
docs/configuration.md Normal file
View File

@@ -0,0 +1,142 @@
# Configuration reference
Exhaustive lookup for env vars and CLI flags. For *what* the framework does with these, see the linked concept docs.
## Environment variables
### Read by the Qt host (`BackendConnection`)
| Var | Default | Effect |
| --- | --- | --- |
| `BRIDGE_URL` | unset | If set, host runs in [dev mode](architecture.md#dev-mode-vs-bundled-mode) and connects to this URL. If unset, host runs in [bundled mode](bundled-mode.md). |
| `BRIDGE_TOKEN` | unset | Bearer token for `Authorization` headers. Dev mode reads this from env (typically set in `.env`); bundled mode generates a per-session value and ignores env. |
| `BRIDGE_FRANKENPHP_BIN` | `<bin>/bin/frankenphp` | Bundled mode: override the FrankenPHP binary path. |
| `BRIDGE_SYMFONY_DIR` | candidate list | Bundled mode: override the Symfony app directory. Candidates: `<bin>/symfony`, `<bin>/../symfony`, `<bin>/../share/<app>/symfony`, `<bin>/../usr/share/<app>/symfony`. |
| `BRIDGE_CADDYFILE` | candidate list | Bundled mode: override the Caddyfile path. Same candidate prefixes as `BRIDGE_SYMFONY_DIR`. |
| `BRIDGE_APPIMAGEUPDATE_BIN` | `<bin>/AppImageUpdate.AppImage` | Override the auto-update sidecar path. |
| `APPIMAGE` | set by AppImage runtime | Bundled-mode auto-update reads this to know which AppImage to update. |
### Read by the bundled Symfony app
These come from `framework/skeleton/symfony/.env` in dev mode and from environment passed by `BackendConnection::spawnChild()` in bundled mode.
| Var | Notes |
| --- | --- |
| `APP_ENV` | `dev` (dev mode) or `prod` (bundled mode). |
| `APP_DEBUG` | `1` / `0` to match. |
| `APP_SECRET` | Symfony framework secret. Static in dev; per-session random in bundled mode. |
| `BRIDGE_TOKEN` | Bearer token the `SessionAuthenticator` checks against. |
| `DATABASE_URL` | `sqlite:///%kernel.project_dir%/var/data.sqlite` (dev) or `sqlite:///<userdata>/var/data.sqlite` (bundled). Override to switch to PostgreSQL/MySQL. |
| `MERCURE_URL` | `http://127.0.0.1:8765/.well-known/mercure`. |
| `MERCURE_PUBLIC_URL` | Same as `MERCURE_URL` for local-only deployment. |
| `MERCURE_JWT_SECRET` | HMAC secret for minting publisher JWTs. ≥256 bits. |
| `MERCURE_PUBLISHER_JWT_KEY` | Same value as `MERCURE_JWT_SECRET`. |
| `MERCURE_SUBSCRIBER_JWT_KEY` | Same value as `MERCURE_JWT_SECRET`. |
| `PORT` | `8765`. Used by the Caddyfile. Override for non-default ports. |
### Read by `make dev` / `scripts/dev.sh`
| Var | Default | Effect |
| --- | --- | --- |
| `FRANKENPHP` | `frankenphp` (PATH lookup) | Path to the FrankenPHP binary. |
### Read by `make appimage` / `build-appimage.sh`
| Var | Default | Effect |
| --- | --- | --- |
| `FRANKENPHP` | `frankenphp` (PATH lookup) | Path to the FrankenPHP binary to bundle. |
| `APPIMAGE_UPDATE_INFO` | unset | If set, embedded into the AppImage's `.upd_info` ELF section so AppImageUpdate finds the appcast. Format: `zsync\|<url-to-.zsync>`. |
| `APPIMAGE_EXTRACT_AND_RUN` | unset | If `1`, the AppImage runtime extracts to a temp dir before running. CI sets this so the AppImage works on systems without FUSE. |
### Read by `tests/perfsmoke.sh`
| Var | Default | Effect |
| --- | --- | --- |
| `PERF_COLD_START_MS` | `2000` | Cold-start budget. CI uses `4000` for shared runners. |
| `PERF_IDLE_MEM_MB` | `200` | Idle RSS budget (host + descendants). |
| `PERF_BUNDLE_MB` | `200` | Bundle size budget. |
| `PERF_BACKEND_PORT` | `8765` | Port the smoke probes for `/healthz`. |
| `PERF_HEALTHZ_DEADLINE_MS` | `5000` | How long to wait for the first 200 before failing. CI uses `8000`. |
### Read by `bin/php-qml-init`
| Var | Default | Effect |
| --- | --- | --- |
| `PHP_QML_FRAMEWORK` | unset → auto-detect | Path to a php-qml checkout. Auto-detected when the script is run from a checkout (`<repo>/bin/php-qml-init`); pass explicitly when the script lives elsewhere. |
---
## CLI flags
### `bin/php-qml-init`
```
php-qml-init [--framework <dir>] [--vendor] [--skip-install] [--git] <name>
```
| Flag | Default | Effect |
| --- | --- | --- |
| `<name>` | required | Project directory name. Lowercase, alphanumeric, `_` or `-`, leading letter. |
| `--framework <dir>` | auto-detect | Override the php-qml checkout location. Equivalent to `PHP_QML_FRAMEWORK`. |
| `--vendor` | off | Copy `framework/php` and `framework/qml` into `<name>/.bridge/` and `<name>/.bridge-qml/`. The new project is portable away from the checkout but won't pick up framework updates automatically. |
| `--skip-install` | off | Don't run `composer install` or migrations. Useful for offline scaffolding. |
| `--git` | off | `git init` and create an "Initial scaffold" commit. |
| `-h`, `--help` | — | Print usage. |
The script auto-validates that `<name>` doesn't already exist (or that the existing dir is empty). It rewrites every `skeleton` identifier to the project name (CMake project, Qt target, QML URI, app title, single-instance lock id, composer path-repo, CMake `add_subdirectory(framework/qml)`, `.vscode/launch.json`).
### `packaging/linux/build-appimage.sh`
```
build-appimage.sh \
--app-name <name> \
--host-binary <path> \
--symfony-dir <path> \
--frankenphp <path> \
--caddyfile <path> \
--desktop <path> \
--icon <path> \
--output <path.AppImage> \
[--update-info <zsync-url>]
```
All except `--update-info` are required. See [Linux packaging §CLI](packaging-linux.md#cli-build-appimagesh) for details.
### `make` targets
Run from a project's root (skeleton, todo example, or a `php-qml-init`'d project).
| Target | What it does |
| --- | --- |
| `make help` | Print available targets. |
| `make install` | `composer install` in `symfony/`. |
| `make build` | `cmake -S qml -B build/qml && cmake --build build/qml`. |
| `make dev` | `make build` + `scripts/dev.sh` (FrankenPHP `--watch` + Qt host). |
| `make doctor` | `bin/console bridge:doctor`. |
| `make doctor-connect` | `bin/console bridge:doctor --connect`. |
| `make quality` | PHP quality + qmllint + (todo example) integration test. |
| `make integration` | (todo example only) HTTP+SSE round-trip + crash-recover smoke. |
| `make appimage` | (todo example only) Stage symfony --no-dev, run `build-appimage.sh`. |
| `make perf` | (todo example only) Run `tests/perfsmoke.sh` against the built AppImage. |
| `make clean` | Remove `build/`. |
---
## Default ports & paths
| What | Where |
| --- | --- |
| FrankenPHP HTTP / Mercure | `http://127.0.0.1:8765` |
| Mercure SSE endpoint | `/.well-known/mercure` |
| Health probe | `GET /healthz` (returns `200 OK` when ready) |
| Bundled-mode user data | `~/.local/share/<app>/var/` (Linux). `XDG_DATA_HOME` honoured. |
| Bundled-mode SQLite | `~/.local/share/<app>/var/data.sqlite` |
| Bundled-mode logs | `~/.local/share/<app>/var/log/` |
| Single-instance socket | `~/.local/share/<app>/<app>.sock` |
| AppImage AppDir layout | `usr/bin/<app>`, `usr/share/<app>/symfony/`, `usr/share/<app>/Caddyfile`, `usr/bin/AppImageUpdate.AppImage` |
## See also
- [Getting started](getting-started.md) — installation, first run, troubleshooting.
- [Bundled mode](bundled-mode.md) — what bundled mode reads these env vars for.
- [Linux packaging](packaging-linux.md) — when to set `APPIMAGE_UPDATE_INFO` etc.