Files

magdev da048434b8 docs: rewrite README + add comprehensive docs/

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>

2026-05-02 22:18:37 +02:00

7.1 KiB

Raw Blame History

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 and connects to this URL. If unset, host runs in bundled mode.
`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 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`

7.1 KiB Raw Blame History

Configuration reference

Environment variables

Read by the Qt host (BackendConnection)

Read by the bundled Symfony app

Read by make dev / scripts/dev.sh

Read by make appimage / build-appimage.sh

Read by tests/perfsmoke.sh

Read by bin/php-qml-init