magdev
91f4d619fc
PLAN.md §12 noted "Native dialogs (file pickers, notifications) — where do they live?" as an open question with the bias "QML side via Qt". That bias was never written up; without the doc, a Symfony developer new to Qt would reasonably reach for "POST /api/show-dialog" or roll a custom QML "FileDialog" using Window + ListView. Both are wrong. The doc: - States the boundary plainly (native UI = QML side, never PHP) plus the architectural reason (PHP's process can't reach the user's window manager; Qt's can and already wraps every platform's native API). - Walks through Qt.labs.platform.FileDialog / MessageDialog / SystemTrayIcon / StandardPaths with copy-pasteable examples so apps don't need to discover Qt.labs the hard way. - Explains the trigger-vs-effect split: user-initiated confirmations open from the QML handler that fired the action; server-side events route through Mercure and let QML decide how to surface them (toast / dialog / tray notification). Anti-pattern callouts: don't dispatch dialogs from Doctrine listeners, don't add HTTP endpoints whose only job is to trigger UI side-effects, don't roll a custom QML file browser. Notifications caveat: Qt.labs.platform.SystemTrayIcon::showMessage covers the common case but routes through the tray. Richer notifications (action buttons, replies) need platform-specific code and are deferred — flagged in-doc. PLAN.md §13 also mentioned "ship a small Q_INVOKABLE helper for the common cases". Skipped: every common case Qt.labs.platform already covers, and a wrapper would just shadow upstream's API. If a future need surfaces a real gap (XDG portal notifications without tray, say), that's the time to add framework-side code; the doc will point at it. No code changes; doc-only. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2.4 KiB
2.4 KiB
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. - 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],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.