framework/php/tests/snapshot/ holds reference output for every shipped
maker (resource Todo, command MarkAllDone, window Todo). The
run.sh script:
- git-archives the skeleton into a temp dir
- composer-installs against the bundle's real path
- removes the existing maker outputs so the regenerators don't bail
- runs the three makers
- diffs each generated file against the matching baseline
CI / make quality fail on any drift; if a template change is intended,
the baselines must be regenerated in the same commit. Wired into:
- framework/skeleton/Makefile's `quality` target (local/dev runs)
- .gitea/workflows/ci.yml (CI runs after qmllint)
Plus a few hardenings discovered while wiring this up:
- The resource maker template now injects NormalizerInterface
(not SerializerInterface — that interface lacks ::normalize()).
All Todo controllers re-rendered to match.
- The command maker template emits a $this->em->flush() so the
injected EntityManager isn't a property.onlyWritten violation
in PHPStan after the user fills in the body.
- phpstan.neon and php-cs-fixer's Finder both exclude tests/snapshot
so the baselines aren't auto-rewritten or analysed as live code.
CI workflow now also installs FrankenPHP, builds the todo example, and
runs the bridge-integration test from Phase 3 sub-commit 4.
Phase 3 done. Outstanding follow-ups (deferred per spec): the
qmltestrunner-driven QML unit tests, make:bridge:event,
make:bridge:read-model, ReactiveObject pagination.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Runs `make:bridge:resource Todo` against the skeleton, then `make:migration`
+ `doctrine:migrations:migrate`, and verifies the round-trip end-to-end:
- POST /api/todos creates a row with a UUIDv7 id
- GET /api/todos returns the row
- Mercure dual-publishes:
- app://model/todo (collection topic)
- app://model/todo/{uuid} (entity topic)
- The published envelope shape matches PLAN.md §4 exactly:
{op:"upsert", id:..., version:..., data:{...}, correlationKey:"..."}
- correlationKey echoes the request's Idempotency-Key, ready to be
matched by ReactiveListModel's pending state on the QML side.
Generated files committed as the regression baseline (Phase 3 will add
a CI check that re-running the maker reproduces these byte-for-byte):
- framework/skeleton/symfony/src/Entity/Todo.php
- framework/skeleton/symfony/src/Controller/TodoController.php
- framework/skeleton/symfony/migrations/Version20260502004612.php
- framework/skeleton/qml/TodoList.qml
framework/skeleton/README.md captures the three-command flow plus a
curl walkthrough so future readers can reproduce. Phase 2 done.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bundle picks up symfony/maker-bundle as require-dev. New BridgeResourceMaker
under PhpQml\Bridge\Maker generates three files for a named resource:
- src/Entity/<Name>.php — Doctrine entity with #[BridgeResource]
and a UUIDv7 id by default. --int-id flips
to auto-incrementing int IDs.
- src/Controller/<Name>Controller.php — CRUD on /api/{plural} (list,
create, update, delete) with serializer-
normalised JSON responses.
- {qml_path}/<Name>List.qml — starter ListView wrapped around a
ReactiveListModel bound to the right topic
and source URL.
The Doctrine subscriber from sub-commit 2 picks the entity up
automatically — no per-resource listener generated. The QML snippet
target defaults to '../qml/' (relative to the Symfony project root)
and is overridable via the maker's $qmlPath constructor arg.
Templates live under src/Maker/templates/ as .tpl.php files using
short-echo and alternative-syntax control structures by convention.
PHPStan and php-cs-fixer skip them — the maker's Generator binds the
template variables at render time.
Skeleton picks up MakerBundle as a `dev` bundle and require-dev'd
symfony/maker-bundle, so `bin/console make:bridge:resource Todo`
works out-of-the-box.
Verified: maker runs end-to-end against `Todo` and emits readable,
syntactically valid output. composer quality (16 tests, 45 assertions,
PHPStan clean, cs-fixer clean) stays green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Bundle gains the model layer that bridges Doctrine entities to Mercure
without per-resource glue. Three new pieces:
- `#[BridgeResource(name: ?string)]` attribute marks an entity as a
reactive bridge model. Topic name defaults to the lowercased class
basename and can be overridden per resource.
- `ModelPublisher` translates entity changes into PLAN.md §4 envelopes
({op, id, data, version, ?correlationKey}) and dual-publishes them
on `app://model/{name}` (collection topic) and `app://model/{name}/{id}`
(entity topic). Entity normalisation goes through Symfony's Serializer
(ObjectNormalizer + DateTime + BackedEnum) for predictable JSON. The
envelope `version` field is a per-process monotonic counter — fine for
single-instance dev mode; production should back this with a Postgres
SEQUENCE or equivalent (noted for Phase 4).
- `DoctrineBridgeListener` registers `postPersist`/`postUpdate`/
`postRemove` via `#[AsDoctrineListener]` and routes events through
ModelPublisher. Entities without `#[BridgeResource]` are silently
skipped.
Plus the correlation-key plumbing the §5 Update Semantics layer needs:
- `CorrelationContext` is a per-request holder for the originating
request's `Idempotency-Key`.
- `CorrelationKeyListener` reads the header on `KernelEvents::REQUEST`
and clears the context on `KernelEvents::TERMINATE` (worker mode
hygiene). CLI mutations see no key, which is correct.
Bundle composer.json picks up `doctrine/dbal`, `doctrine/orm`,
`doctrine/doctrine-bundle`, `symfony/serializer`, `symfony/property-*`,
`symfony/uid`. PHPStan extension `phpstan-doctrine` added so the listener's
event-args types resolve. Skeleton's framework.yaml enables `serializer`
and `property_info`.
Tests: 5 new for ModelPublisher (dual publish, correlation echo, delete
op omits data, untagged entities ignored, version increments). Total:
16 tests, 45 assertions, PHPStan clean, cs-fixer clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Skeleton gains Doctrine ORM 3.6 (with DoctrineBundle 3.x and Migrations
4.x), pointed at a SQLite file under var/data.sqlite. Apps move to
Postgres/MySQL by overriding DATABASE_URL in .env.local.
config/packages/doctrine.yaml registers the symfony/uid UuidType so
Phase 2 sub-commit 4's UUIDv7 default works without per-app config,
and pre-wires the App\Entity attribute mapping under src/Entity/ for
the maker to drop entities into.
Bundle gains an optional doctrine/dbal Connection via Autowire; when
present, bridge:doctor adds a "Database reachable" SELECT-1 probe.
The bundle still installs cleanly without doctrine/dbal — apps that
opt out get a doctor table without the database row.
Verified: `bin/console bridge:doctor` is all green against a fresh
SQLite. composer quality (PHPStan + cs-fixer + PHPUnit) stays green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Symfony app under framework/skeleton/symfony/: minimal bin/console,
public/index.php, MicroKernel-based src/Kernel.php, services.yaml,
framework/security/mercure config, and a demo App\Controller\PingController
that GETs /api/ping (returning JSON pong) and republishes the same
payload to the Mercure topic app://ping. composer.json uses a path
repository to symlink the bundle from ../../php so local edits are
picked up live.
QML app under framework/skeleton/qml/: top-level CMake that
add_subdirectory's framework/qml, a main.cpp that creates the Qt
process, runs SingleInstance.acquireOrForward before any QML loads,
exposes SingleInstance via context property, and loadFromModule's
Skeleton.Main. Main.qml uses BackendConnection / RestClient /
MercureClient from PhpQml.Bridge and renders status dots, a Ping
button, and an event log.
Caddyfile binds 127.0.0.1:8765, enables in-memory Mercure with a
256-bit dev JWT (matches symfony/.env, lcobucci/jwt requires this).
Makefile wraps build / dev / doctor / clean; scripts/dev.sh starts
FrankenPHP --watch and the Qt host together with explicit PID-based
teardown (process-group `kill 0` proved unreliable when frankenphp's
watch fork reparented).
Bug fixes uncovered in this sub-commit:
- SingleInstance.acquireOrForward: probe-first, then removeServer +
retry-listen. The original loop-with-removeServer-after-failed-bind
silently exited on stale sockets from prior runs.
- Main.qml: MercureClient does NOT inherit BackendConnection.token —
Mercure subscribes anonymously in dev (Caddyfile), and forwarding
the bridge bearer made it 401-loop.
- /api/ping was 500ing because the dev MERCURE_JWT_SECRET was 144 bits;
bumped to 64-char (>=256 bit) to satisfy lcobucci/jwt.
- Linked the framework lib (php_qml_bridge) explicitly in addition to
the QML plugin so SingleInstance.h resolves.
- Auto-generated config/reference.php gitignored.
Smoke verified offscreen: /healthz 200, /api/ping 200, 1 publish, 1
subscriber, zero 401s, clean shutdown with no zombies.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
