v0.2.0 (8/N): make:bridge:read-model maker

Implements PLAN.md §8's fourth makers-table row. Read-models are
server-side projections — joined fetches, aggregates, denormalised
views — that QML reads without going through a writable
#[BridgeResource]. The maker emits:

  - src/ReadModel/<Name>ReadModel.php — query service stub injecting
    EntityManagerInterface; user fills query() with DQL / QueryBuilder
    / raw SQL as fits.
  - src/Controller/<Name>Controller.php — single GET handler at
    /api/<kebab-plural>, just normalises the read-model output to JSON.
  - {qml_path}/<Name>List.qml — ReactiveListModel bound to the route,
    deliberately no Mercure topic.

The "no topic" choice is the design call worth documenting: read-models
are queries, not reactive resources, and pretending otherwise would
either auto-publish stale aggregates on every entity change or require
the user to invent invalidation logic in the listener. Better: pair
the read-model with `make:bridge:event` and call refresh() from the
QML event-handler when the underlying data really changes.

Naming convention: kebab-PLURAL routes (`/api/todo-summaries`) for
consistency with REST list semantics; resource path stays singular
under `src/ReadModel/`.

Wired into services.yaml's when@dev block. Three new snapshot
baselines (TodoSummaryReadModel.php / TodoSummaryController.php /
TodoSummaryList.qml) plus runner extension. All 14 maker outputs
verify on the committed state.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -17,6 +17,7 @@ This section tracks work landing on `dev` toward **v0.2.0** (next minor; pre-1.0
 - **`Maker\Support\Naming`** — `camelTo($name, $separator)` helper. Replaces inline `preg_replace('/(?<!^)[A-Z]/', $sep.'$0', $name)` regex copies (BridgeResourceMaker emits `_`-joined route plurals, BridgeCommandMaker emits `-`-joined kebab slugs).
 - **`make:bridge:resource --with-dto` opt-in.** Generates `Create<Name>Dto` + `Update<Name>Dto` under `src/Dto/` alongside the controller, and the controller dispatches via `#[MapRequestPayload]`. Closes the input-validation gap from the audit: malformed JSON, missing required fields, or `#[Assert\NotBlank]` violations now produce RFC 7807 `application/problem+json` automatically (Symfony's `RequestPayloadValueResolver`) — no more `if (isset($data['title']))` boilerplate, no silent type coercion. Update DTOs use nullable defaults so PATCH callers send only the fields they want changed. Without `--with-dto` the legacy template still ships unchanged. Maker fails loud if `symfony/validator` isn't autoloadable. Skeleton + example/todo composer.json pull `symfony/validator` so scaffolded apps work out of the box. Snapshot test exercises both modes.
 - **`make:bridge:event <Name>` maker.** Generates a domain-event class (`src/Event/<Name>Event.php`, readonly value object), a subscriber (`src/EventSubscriber/<Name>Subscriber.php`) that republishes via `PublisherInterface` on `app://event/<kebab-name>`, and a QML stub (`{qml_path}/<Name>EventHandler.qml`) that listens via `MercureClient` and re-emits as a typed `signal`. Closes the third row of PLAN.md §8's makers table; pairs with the existing `make:bridge:resource` / `command` / `window` makers so domain events have a one-command path from PHP through to QML.
+- **`make:bridge:read-model <Name>` maker.** Generates a query-only projection: `src/ReadModel/<Name>ReadModel.php` (query service stub injecting `EntityManagerInterface`), `src/Controller/<Name>Controller.php` (single GET handler at `/api/<kebab-plural>`), and `{qml_path}/<Name>List.qml` (`ReactiveListModel` bound to the route, deliberately *no* Mercure topic — read-models aren't auto-reactive; invalidation is event-driven via `make:bridge:event`). Closes the fourth row of PLAN.md §8's makers table.
 
 ### Changed
 

framework/php/config/services.yaml

@@ -45,3 +45,7 @@ when@dev:
         PhpQml\Bridge\Maker\BridgeEventMaker:
             arguments:
                 $qmlPath: '%bridge.qml_path%'
+
+        PhpQml\Bridge\Maker\BridgeReadModelMaker:
+            arguments:
+                $qmlPath: '%bridge.qml_path%'

framework/php/src/Maker/BridgeReadModelMaker.php

@@ -0,0 +1,143 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpQml\Bridge\Maker;
+
+use Doctrine\ORM\EntityManagerInterface;
+use PhpQml\Bridge\Maker\Support\NameInput;
+use PhpQml\Bridge\Maker\Support\Naming;
+use Symfony\Bundle\MakerBundle\ConsoleStyle;
+use Symfony\Bundle\MakerBundle\DependencyBuilder;
+use Symfony\Bundle\MakerBundle\Generator;
+use Symfony\Bundle\MakerBundle\InputConfiguration;
+use Symfony\Bundle\MakerBundle\Maker\AbstractMaker;
+use Symfony\Bundle\MakerBundle\Str;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputArgument;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\Routing\Attribute\Route;
+
+/**
+ * `make:bridge:read-model <Name>` — generates a query-only projection.
+ *
+ * Read-models are server-side joined / aggregated views QML reads
+ * without going through a writable `#[BridgeResource]`. Three files:
+ *
+ *   - src/ReadModel/<Name>ReadModel.php — query service stub
+ *   - src/Controller/<Name>Controller.php — `GET /api/<kebab-plural>`
+ *   - {qml_path}/<Name>List.qml — `ReactiveListModel` bound to the route,
+ *     no Mercure topic (read-models aren't reactive — invalidation is
+ *     driven by domain events; see `make:bridge:event`).
+ */
+final class BridgeReadModelMaker extends AbstractMaker
+{
+    public function __construct(
+        private readonly string $qmlPath = '../qml/',
+    ) {
+    }
+
+    public static function getCommandName(): string
+    {
+        return 'make:bridge:read-model';
+    }
+
+    public static function getCommandDescription(): string
+    {
+        return 'Generate a read-only projection (query service + GET controller + QML stub).';
+    }
+
+    public function configureCommand(Command $command, InputConfiguration $inputConfig): void
+    {
+        $command
+            ->addArgument(
+                'name',
+                InputArgument::OPTIONAL,
+                'CamelCase projection name (e.g. TodoSummary, RecentActivity).',
+            )
+            ->setHelp(
+                "Creates three files:\n\n"
+                ." • <info>src/ReadModel/<Name>ReadModel.php</info> — query service (you fill in the body)\n"
+                ." • <info>src/Controller/<Name>Controller.php</info> — GET handler at /api/<kebab-plural>\n"
+                ." • <info>{qml_path}/<Name>List.qml</info> — ReactiveListModel bound to the route\n\n"
+                ."Read-models are not auto-reactive. To refresh from server-side changes,\n"
+                ."generate a paired domain event with <info>make:bridge:event</info>.\n"
+            );
+    }
+
+    public function interact(InputInterface $input, ConsoleStyle $io, Command $command): void
+    {
+        NameInput::askOrFail(
+            $input,
+            $io,
+            'name',
+            'Projection name (CamelCase, e.g. TodoSummary)?',
+            'Projection name cannot be empty.',
+        );
+    }
+
+    public function generate(InputInterface $input, ConsoleStyle $io, Generator $generator): void
+    {
+        $rawName     = (string) $input->getArgument('name');
+        $singular    = ucfirst(Str::asCamelCase($rawName));
+        $pluralCamel = Str::singularCamelCaseToPluralCamelCase($singular);
+        $resource    = Naming::camelTo($singular, '_');
+        $route       = '/api/'.Naming::camelTo($pluralCamel, '-');
+
+        $readModelFqcn = $generator->createClassNameDetails(
+            $singular,
+            'ReadModel\\',
+            'ReadModel',
+        );
+        $controllerFqcn = $generator->createClassNameDetails(
+            $singular,
+            'Controller\\',
+            'Controller',
+        );
+
+        $vars = [
+            'singular'         => $singular,
+            'resource'         => $resource,
+            'route'            => $route,
+            'read_model_short' => $readModelFqcn->getShortName(),
+            'read_model_fqcn'  => $readModelFqcn->getFullName(),
+            'controller_short' => $controllerFqcn->getShortName(),
+        ];
+
+        $generator->generateFile(
+            'src/ReadModel/'.$readModelFqcn->getShortName().'.php',
+            __DIR__.'/templates/ReadModel.tpl.php',
+            $vars,
+        );
+        $generator->generateFile(
+            'src/Controller/'.$controllerFqcn->getShortName().'.php',
+            __DIR__.'/templates/ReadModelController.tpl.php',
+            $vars,
+        );
+
+        $qmlTarget = rtrim($this->qmlPath, '/').'/'.$singular.'List.qml';
+        $generator->generateFile(
+            $qmlTarget,
+            __DIR__.'/templates/ReadModelQml.tpl.php',
+            $vars,
+        );
+
+        $generator->writeChanges();
+
+        $this->writeSuccessMessage($io);
+        $io->text([
+            'Next:',
+            "  • Implement <info>{$readModelFqcn->getShortName()}::query()</info>.",
+            "  • Use <info>{$singular}List.qml</info> in your QML.",
+            '  • Optionally pair with <info>make:bridge:event</info> for invalidation.',
+        ]);
+    }
+
+    public function configureDependencies(DependencyBuilder $dependencies): void
+    {
+        $dependencies->addClassDependency(EntityManagerInterface::class, 'doctrine/orm');
+        $dependencies->addClassDependency(Route::class, 'symfony/routing');
+        $dependencies->addClassDependency(JsonResponse::class, 'symfony/http-foundation');
+    }
+}

framework/php/src/Maker/templates/ReadModel.tpl.php

@@ -0,0 +1,38 @@
+<?= "<?php\n" ?>
+
+declare(strict_types=1);
+
+namespace App\ReadModel;
+
+use Doctrine\ORM\EntityManagerInterface;
+
+/**
+ * Auto-generated query service for the <?= $singular ?> read-model.
+ *
+ * Read-models are server-side projections — joined fetches, aggregates,
+ * denormalised views — that QML reads without going through a writable
+ * `#[BridgeResource]`. Replace the body of `query()` with the actual
+ * DQL / raw SQL / joined fetch.
+ *
+ * Per PLAN.md §4 *Pagination*, return an array of associative arrays so
+ * the controller can normalise to JSON without a serializer; or wire up
+ * a normalizer if you prefer typed DTOs in the projection.
+ */
+final readonly class <?= $singular ?>ReadModel
+
+{
+    public function __construct(
+        private EntityManagerInterface $em,
+    ) {
+    }
+
+    /**
+     * @return list<array<string, mixed>>
+     */
+    public function query(): array
+    {
+        // TODO: implement the read query — DQL, ->createQueryBuilder(),
+        // or ->getConnection()->executeQuery() as fits.
+        return [];
+    }
+}

framework/php/src/Maker/templates/ReadModelController.tpl.php

@@ -0,0 +1,29 @@
+<?= "<?php\n" ?>
+
+declare(strict_types=1);
+
+namespace App\Controller;
+
+use App\ReadModel\<?= $singular ?>ReadModel;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\Routing\Attribute\Route;
+
+/**
+ * Read-only endpoint for the <?= $singular ?> projection.
+ * Auto-generated by `make:bridge:read-model` — the read-model owns
+ * the query; this controller just normalises the result to JSON.
+ */
+final class <?= $singular ?>Controller
+
+{
+    public function __construct(
+        private readonly <?= $singular ?>ReadModel $readModel,
+    ) {
+    }
+
+    #[Route('<?= $route ?>', name: '<?= $resource ?>_read', methods: ['GET'])]
+    public function __invoke(): JsonResponse
+    {
+        return new JsonResponse($this->readModel->query());
+    }
+}

framework/php/src/Maker/templates/ReadModelQml.tpl.php

@@ -0,0 +1,28 @@
+// Auto-generated by `bin/console make:bridge:read-model <?= $singular ?>`.
+// Read-only projection — no Mercure topic, no auto-updates.
+//
+// For invalidation: when the underlying data changes, dispatch a
+// domain event from PHP (see `make:bridge:event`) and call
+// `<?= lcfirst($singular) ?>List.refresh()` from the event-handler in QML.
+
+import QtQuick
+import QtQuick.Controls
+import PhpQml.Bridge
+
+ListView {
+    id: <?= lcfirst($singular) ?>List
+
+    model: ReactiveListModel {
+        baseUrl: BackendConnection.url
+        token:   BackendConnection.token
+        source:  "<?= $route ?>"
+        // topic: intentionally unset — read-models are queries, not
+        // reactive resources. Drive refreshes from domain events.
+    }
+
+    delegate: ItemDelegate {
+        // Replace with your projection's columns.
+        text:  String(model.modelData)
+        width: ListView.view.width
+    }
+}

framework/php/tests/snapshot/TodoSummaryController.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Controller;
+
+use App\ReadModel\TodoSummaryReadModel;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\Routing\Attribute\Route;
+
+/**
+ * Read-only endpoint for the TodoSummary projection.
+ * Auto-generated by `make:bridge:read-model` — the read-model owns
+ * the query; this controller just normalises the result to JSON.
+ */
+final class TodoSummaryController
+{
+    public function __construct(
+        private readonly TodoSummaryReadModel $readModel,
+    ) {
+    }
+
+    #[Route('/api/todo-summaries', name: 'todo_summary_read', methods: ['GET'])]
+    public function __invoke(): JsonResponse
+    {
+        return new JsonResponse($this->readModel->query());
+    }
+}

framework/php/tests/snapshot/TodoSummaryList.qml

@@ -0,0 +1,28 @@
+// Auto-generated by `bin/console make:bridge:read-model TodoSummary`.
+// Read-only projection — no Mercure topic, no auto-updates.
+//
+// For invalidation: when the underlying data changes, dispatch a
+// domain event from PHP (see `make:bridge:event`) and call
+// `todoSummaryList.refresh()` from the event-handler in QML.
+
+import QtQuick
+import QtQuick.Controls
+import PhpQml.Bridge
+
+ListView {
+    id: todoSummaryList
+
+    model: ReactiveListModel {
+        baseUrl: BackendConnection.url
+        token:   BackendConnection.token
+        source:  "/api/todo-summaries"
+        // topic: intentionally unset — read-models are queries, not
+        // reactive resources. Drive refreshes from domain events.
+    }
+
+    delegate: ItemDelegate {
+        // Replace with your projection's columns.
+        text:  String(model.modelData)
+        width: ListView.view.width
+    }
+}

framework/php/tests/snapshot/TodoSummaryReadModel.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\ReadModel;
+
+use Doctrine\ORM\EntityManagerInterface;
+
+/**
+ * Auto-generated query service for the TodoSummary read-model.
+ *
+ * Read-models are server-side projections — joined fetches, aggregates,
+ * denormalised views — that QML reads without going through a writable
+ * `#[BridgeResource]`. Replace the body of `query()` with the actual
+ * DQL / raw SQL / joined fetch.
+ *
+ * Per PLAN.md §4 *Pagination*, return an array of associative arrays so
+ * the controller can normalise to JSON without a serializer; or wire up
+ * a normalizer if you prefer typed DTOs in the projection.
+ */
+final readonly class TodoSummaryReadModel
+{
+    public function __construct(
+        private EntityManagerInterface $em,
+    ) {
+    }
+
+    /**
+     * @return list<array<string, mixed>>
+     */
+    public function query(): array
+    {
+        // TODO: implement the read query — DQL, ->createQueryBuilder(),
+        // or ->getConnection()->executeQuery() as fits.
+        return [];
+    }
+}

framework/php/tests/snapshot/run.sh

@@ -51,7 +51,8 @@ clear_outputs
     && bin/console make:bridge:resource Todo --no-interaction >/dev/null \
     && bin/console make:bridge:command MarkAllDone --no-interaction >/dev/null \
     && bin/console make:bridge:window Todo --no-interaction >/dev/null \
-    && bin/console make:bridge:event TodoCompleted --no-interaction >/dev/null )
+    && bin/console make:bridge:event TodoCompleted --no-interaction >/dev/null \
+    && bin/console make:bridge:read-model TodoSummary --no-interaction >/dev/null )
 
 check "$APP/symfony/src/Entity/Todo.php"                             "$SCRIPT_DIR/Todo.php"
 check "$APP/symfony/src/Controller/TodoController.php"               "$SCRIPT_DIR/TodoController.php"
@@ -61,6 +62,9 @@ check "$APP/qml/TodoWindow.qml"                                     "$SCRIPT_DIR
 check "$APP/symfony/src/Event/TodoCompletedEvent.php"                "$SCRIPT_DIR/TodoCompletedEvent.php"
 check "$APP/symfony/src/EventSubscriber/TodoCompletedSubscriber.php" "$SCRIPT_DIR/TodoCompletedSubscriber.php"
 check "$APP/qml/TodoCompletedEventHandler.qml"                       "$SCRIPT_DIR/TodoCompletedEventHandler.qml"
+check "$APP/symfony/src/ReadModel/TodoSummaryReadModel.php"          "$SCRIPT_DIR/TodoSummaryReadModel.php"
+check "$APP/symfony/src/Controller/TodoSummaryController.php"        "$SCRIPT_DIR/TodoSummaryController.php"
+check "$APP/qml/TodoSummaryList.qml"                                 "$SCRIPT_DIR/TodoSummaryList.qml"
 
 # ── Mode 2: --with-dto (re-runs make:bridge:resource only) ────────────
 # The entity + QML output is byte-identical between modes; only the