magdev
da048434b8
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>
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.