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>

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
+    }
+}