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>
36 lines
2.6 KiB
Markdown
36 lines
2.6 KiB
Markdown
# Documentation
|
|
|
|
Developer documentation for [php-qml](../README.md). Design rationale and roadmap live in [PLAN.md](../PLAN.md); per-release changes in [CHANGELOG.md](../CHANGELOG.md).
|
|
|
|
## Start here
|
|
|
|
- **[Getting started](getting-started.md)** — install prerequisites, scaffold a project, run it, troubleshoot.
|
|
- **[Architecture](architecture.md)** — process-pair design, transport, dev vs bundled mode.
|
|
|
|
## Concepts
|
|
|
|
- **[Update semantics](update-semantics.md)** — `Connecting → Online → Reconnecting → Offline`, optimistic mutations, idempotency-key round-tripping.
|
|
- **[Reactive models](reactive-models.md)** — `ReactiveListModel`, `ReactiveObject`, Mercure dual-publish on `app://model/<name>` and `app://model/<name>/<id>`.
|
|
- **[Bundled mode](bundled-mode.md)** — what changes when there is no `BRIDGE_URL`: supervisor, per-session secret rotation, first-launch migrations.
|
|
|
|
## Guides
|
|
|
|
- **[Makers](makers.md)** — `make:bridge:resource` (`--with-dto` opt-in), `make:bridge:command`, `make:bridge:event`, `make:bridge:read-model`, `make:bridge:window`.
|
|
- **[Dev workflow](dev-workflow.md)** — hot reload (PHP + QML), dev console (Ctrl+backtick), editor configs, `bridge:doctor`, `make qmltest`.
|
|
- **[Linux packaging](packaging-linux.md)** — `make appimage`, AppImageUpdate (launch + periodic), performance budgets.
|
|
- **[Native dialogs](native-dialogs.md)** — 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](qml-api.md)** — `BackendConnection`, `RestClient`, `MercureClient`, `ReactiveListModel`, `ReactiveObject`, `AppShell`, `DevConsole`, `SingleInstance`.
|
|
- **[PHP API](php-api.md)** — `BridgeBundle`, `#[BridgeResource]`, `BridgeOp` enum, `PublisherInterface`, `ModelPublisherInterface`, `CorrelationContextInterface`, `BridgeBundleInfo`, `bridge:doctor`, `bridge:export`, `SessionAuthenticator`.
|
|
- **[Configuration](configuration.md)** — 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](../PLAN.md). When a feature is shipped, the doc covers it without forward-looking caveats.
|