magdev
a1cc06abbb
Auto-detected on construction:
- BRIDGE_URL env set → dev mode (today's behaviour, unchanged).
- BRIDGE_URL unset → bundled mode: BackendConnection now
1. Resolves the user app data dir (QStandardPaths::AppDataLocation,
~/.local/share/<org>/<app> on Linux) and ensures var/, var/log/,
var/cache/ exist there.
2. Generates a per-session 32-byte URL-safe token and a 48-byte
Mercure JWT secret.
3. Runs `frankenphp php-cli bin/console doctrine:migrations:migrate -n`
against the user's DATABASE_URL with a 60s timeout.
4. Spawns FrankenPHP via QProcess with BRIDGE_TOKEN/MERCURE_*/PORT
in the env, prctl(PR_SET_PDEATHSIG, SIGTERM) on the child, and
a supervisor that re-spawns up to 5 times on unexpected exit.
Each restart fires tokenRotated(newToken).
Path resolution defaults to applicationDirPath() + bin/frankenphp,
applicationDirPath() + symfony, applicationDirPath() + Caddyfile, with
both `/../share/<app>/...` and `/../usr/share/<app>/...` fallbacks for
AppImage-style layouts. All three are overridable via
BRIDGE_FRANKENPHP_BIN / BRIDGE_SYMFONY_DIR / BRIDGE_CADDYFILE env vars.
Caddyfiles in skeleton + example now use {$VAR:default} substitution
for PORT and the Mercure JWT keys, so the same Caddyfile works in both
modes. Dev defaults match symfony/.env.
restart() in bundled mode re-spawns the child (resets the supervisor
counter); in dev mode it stays a probe-only no-op.
Smoke-tested locally with `BRIDGE_FRANKENPHP_BIN=… BRIDGE_SYMFONY_DIR=…
BRIDGE_CADDYFILE=… ./build/qml/todo` (no BRIDGE_URL): bundled mode
created ~/.local/share/php-qml/todo/var/data.sqlite, ran the migration,
spawned FrankenPHP, served /healthz, accepted a POST /api/todos with
the per-session bearer. Dev mode (`make dev`) still works unchanged.
Includes a `phpqml.bridge.bundled` Q_LOGGING_CATEGORY so failures
surface to the user; enable with QT_LOGGING_RULES='phpqml.bridge.bundled.*=true'.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
php-qml
A framework for building native desktop applications with a Symfony / FrankenPHP backend and a Qt/QML frontend, packaged as a single distributable per OS.
Status
Planning stage. The architectural design lives in PLAN.md. No implementation exists yet — first code lands in Phase 0 (a throwaway transport spike). See the roadmap.
What it is
php-qml lets a PHP developer write a desktop application using ordinary Symfony on the backend and ordinary QML on the frontend. The two halves run as a process pair inside one bundled binary:
- A Qt/QML host process owns the window, input, and rendering.
- A bundled FrankenPHP child runs a Symfony application in worker mode.
- They communicate over a local socket — HTTP for commands and queries, Mercure SSE for state push.
The framework provides the lifecycle, transport, reactive models, and scaffolding so application code stays idiomatic on both sides.
What it is not
Not a PHP↔Qt language binding. It does not embed PHP into a Qt event loop and it does not generate Qt classes from PHP. The two languages run in separate processes; the bridge is a wire protocol, not an FFI layer.
If you've watched php-gtk and php-qt go quiet, that is the failure mode this project deliberately avoids — the framework owns the boring parts (lifecycle, transport, conventions) so it doesn't depend on a single maintainer keeping a language binding alive.
Tech stack
- Backend: PHP 8.x, Symfony, Doctrine ORM, FrankenPHP (worker mode), Mercure
- Frontend: Qt 6 LTS, QML, C++ plugin where required
- Build: CMake, Composer
- CI: Gitea Actions, Gitea Releases
- Targets: Linux (AppImage), macOS (
.app+.dmg), Windows (NSIS / MSIX)
Getting started
Nothing to run yet. Once Phase 0 lands:
- Clone the repository and check out the
devbranch. - Install Qt 6 and PHP 8.x; the FrankenPHP runtime is fetched at build time.
task dev— starts FrankenPHP in watch mode and launches the Qt host pointed at it.
Detailed setup will be documented alongside the framework skeleton in Phase 1.
Project structure
See PLAN.md §9 for the intended layout. The repo currently contains only PLAN.md and this README.
Roadmap
Six phases, each ending with something runnable. Detail in PLAN.md §13.
- Phase 0 — throwaway spike, prove transport on Linux.
- Phase 1 — framework skeleton, dev mode, single-instance lock, CI quality gate.
- Phase 2 — reactive models, update semantics, headline maker (
make:bridge:resource). - Phase 3 — POC todo application generated via the makers; testing infrastructure.
- Phase 4 — bundled mode, per-OS packaging, release CI, auto-update.
- Phase 5 — DX polish.
Contributing
Active development happens on the dev branch; main only carries release commits. Pull requests target dev.
A CONTRIBUTING.md will be added with the framework skeleton in Phase 1.
Versioning
Semantic Versioning — MAJOR.MINOR.BUGFIX. MAJOR for breaking changes, MINOR for backwards-compatible features, BUGFIX for backwards-compatible fixes.
License
To be decided before the first release. The framework's own code will be permissively licensed; note that Qt is shipped under LGPL and that carries obligations for distributors — see PLAN.md §12 (Qt LGPL relinkability).