Files

magdev beb4e3ab9d docs: refresh README + docs/ for v0.2.0

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>

2026-05-03 22:27:52 +02:00

2.6 KiB

Raw Blame History

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 on app://model/<name> and app://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-dto opt-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], BridgeOp enum, 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 for php-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.

2.6 KiB Raw Blame History