magdev
341bcacafe
The v0.1.0 shakedown fixes for AppImage assembly (path-repo
symlink:false sed, writable-cache redirect) all landed in
examples/todo. The skeleton — which is what bin/php-qml-init copies
when scaffolding a new app — had no `appimage` target at all, so every
scaffolded app would have to either copy the example's Makefile by
hand or re-discover the same shakedown bugs.
Brings parity:
- framework/skeleton/Makefile gains `staging-symfony` and `appimage`
targets, mirroring the example's. Two new variables (BUNDLE_SRC,
PACKAGING) parameterise the framework-tree paths so bin/php-qml-init
can rewrite them at scaffold time without sed-touching the recipe.
- framework/skeleton/packaging/skeleton.{desktop,png} added — minimum
surface for the AppImage assembly to succeed without the user
needing to author them.
- framework/skeleton/Makefile's staging-symfony recipe handles both
relative (framework default `../../php`) and absolute (post-scaffold)
BUNDLE_SRC values via a case statement.
- bin/php-qml-init renames packaging/skeleton.* → packaging/$NAME.*,
rewrites the .desktop file's Name/Exec/Icon, and updates the
Makefile's --app-name / --output / --desktop / --icon flags +
BUNDLE_SRC + PACKAGING variables. For --vendor mode, framework's
packaging/linux/ is also vendored to .bridge-packaging/ alongside
the existing .bridge/ + .bridge-qml/.
Verified by scaffolding both modes:
- non-vendored: BUNDLE_SRC + PACKAGING absolute paths
- --vendor: BUNDLE_SRC=../.bridge, PACKAGING=.bridge-packaging,
.bridge-packaging/ contains build-appimage.sh
Skeleton's `make quality` still green; staging-symfony works locally
(vendor/php-qml/bridge resolves to a real directory, not a symlink).
Closes the v0.1.1 follow-up "bin/php-qml-init parity" tracked in
PLAN.md §13.
Bundled drive-by: docs/makers.md picked up two markdownlint auto-fixes
(blank lines around lists) when the IDE saved.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Documentation
Developer documentation for php-qml. Design rationale and roadmap live in PLAN.md; per-release changes in CHANGELOG.md.
Start here
- Getting started — install prerequisites, scaffold a project, run it, troubleshoot.
- Architecture — process-pair design, transport, dev vs bundled mode.
Concepts
- Update semantics —
Connecting → Online → Reconnecting → Offline, optimistic mutations, idempotency-key round-tripping. - Reactive models —
ReactiveListModel,ReactiveObject, Mercure dual-publish onapp://model/<name>andapp://model/<name>/<id>. - Bundled mode — what changes when there is no
BRIDGE_URL: supervisor, per-session secret rotation, first-launch migrations.
Guides
- Makers —
make:bridge:resource,make:bridge:command,make:bridge:window. - Dev workflow — hot reload (PHP + QML), dev console (
Ctrl+\``), editor configs,bridge:doctor`. - Linux packaging —
make appimage, AppImageUpdate, performance budgets.
Reference
- QML API —
BackendConnection,RestClient,MercureClient,ReactiveListModel,ReactiveObject,AppShell,DevConsole,SingleInstance. - PHP API —
BridgeBundle,#[BridgeResource],ModelPublisher,bridge:doctor,CorrelationKeyListener,SessionAuthenticator. - Configuration — env vars (
BRIDGE_URL,BRIDGE_TOKEN,FRANKENPHP, …) and CLI flags forphp-qml-init/build-appimage.sh.
How the docs are organised
- Concept docs answer what is this and why?. They reference code only when it clarifies the model.
- Guide docs walk through a workflow end-to-end with copy-pasteable commands.
- Reference docs are exhaustive lookups for symbols, env vars, and flags. They prioritise findability over narrative.
When something is in flux or aspirational, the doc says so and links into PLAN.md. When a feature is shipped, the doc covers it without forward-looking caveats.