php-qml/docs/configuration.md

# 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_PORT` | (negotiated) | Bundled mode: pin a specific TCP port instead of negotiating one. Set by test harnesses (`bundled-supervisor.sh`, `perfsmoke.sh`) for reproducibility. Dev mode ignores it (the Caddyfile still reads `{$PORT:8765}`). |
| `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. |
| `BRIDGE_AUTO_UPDATE_DISABLE` | unset | Bundled mode: set to `1` to disable the periodic auto-update poll. The QML `checkForUpdates()` / `applyUpdate()` Q_INVOKABLEs still work. |
| `BRIDGE_AUTO_UPDATE_PERIOD_MIN` | `360` | Bundled mode: override the periodic auto-update interval in minutes (default 6 h). |
| `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` in dev. In bundled mode the host sets this to the negotiated port (or to `BRIDGE_PORT` if pinned). The Caddyfile reads `{$PORT:8765}`. |

### 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`).

### `bin/console bridge:export`

```
bin/console bridge:export <destination>
```

Copies the active SQLite database (read from `DATABASE_URL`) to `<destination>`. Overwrites the destination if it exists. Works in both dev and bundled mode.

| Arg | Required | Notes |
| --- | --- | --- |
| `<destination>` | yes | Filesystem path. The QML side has the same operation as `BackendConnection.exportDatabase(path)`. |

Errors with exit code `1` if `DATABASE_URL` doesn't point at a SQLite file or if the source doesn't exist. See [PHP API §bridge:export](php-api.md#bridgeexport).

### `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 qmltest` | Configure with `-DBUILD_TESTING=ON`, run the `qmltestrunner` Quick Test target via CTest. Skeleton + `examples/todo`. |
| `make quality` | PHP quality + qmllint + `qmltest` + (todo example) integration test. |
| `make integration` | (todo example only) HTTP+SSE round-trip + crash-recover smoke. |
| `make integration-bundled` | (todo example only) bundled-mode supervisor smoke (cache redirect + auto-backup + clean shutdown). |
| `make appimage` | Stage symfony --no-dev, run `build-appimage.sh`. (Skeleton + todo example.) |
| `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:<port>` (`8765` in dev; negotiated in bundled mode) |
| Mercure SSE endpoint | `/.well-known/mercure` |
| Health probe | `GET /healthz` (returns `200 OK` when ready; response carries `name`, `bundle`) |
| Bundled-mode user data | `~/.local/share/<app>/var/` (Linux). `XDG_DATA_HOME` honoured. |
| Bundled-mode SQLite | `~/.local/share/<app>/var/data.sqlite` |
| Bundled-mode auto-backups | `~/.local/share/<app>/var/data.sqlite.<timestamp>.bak` (last 5 kept) |
| Bundled-mode runtime port | `~/.local/share/<app>/var/bridge.port` (written every launch) |
| 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.