magdev
beb4e3ab9d
The README still framed the project as "Phase 5 / pre-v0.1.0" and the docs predated the v0.2.0 surface (typed BridgeOp, public service interfaces, port negotiation, pre-migration auto-backup, bridge:export, periodic auto-update, two new makers, qmltestrunner). Bring them in line with what's actually shipped, and add badges (release, license, PHP, Symfony, Qt, FrankenPHP, CI, platform) to the README so the status is legible at a glance. 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(--with-dtoopt-in),make:bridge:command,make:bridge:event,make:bridge:read-model,make:bridge:window. - Dev workflow — hot reload (PHP + QML), dev console (Ctrl+backtick), editor configs,
bridge:doctor,make qmltest. - Linux packaging —
make appimage, AppImageUpdate (launch + periodic), performance budgets. - Native dialogs — file pickers, confirmations, system notifications: where they live (QML, not PHP) and how to use the platform-native components Qt already ships.
Reference
- QML API —
BackendConnection,RestClient,MercureClient,ReactiveListModel,ReactiveObject,AppShell,DevConsole,SingleInstance. - PHP API —
BridgeBundle,#[BridgeResource],BridgeOpenum,PublisherInterface,ModelPublisherInterface,CorrelationContextInterface,BridgeBundleInfo,bridge:doctor,bridge:export,SessionAuthenticator. - Configuration — env vars (
BRIDGE_URL,BRIDGE_TOKEN,BRIDGE_PORT,BRIDGE_AUTO_UPDATE_*,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.