Phase 1 sub-commit 2: Symfony bundle internals

Bundle code for php-qml/bridge: BridgeBundle (AbstractBundle, autoloads
config/services.yaml), Publisher (thin wrapper over Mercure HubInterface
that enforces envelope-as-JSON), SessionAuthenticator (bearer-token
custom Symfony authenticator with problem+json failures), and
HealthController (GET /healthz readiness probe).

Composer constraints bumped to Symfony ^8.0 across the board (per user
request); mercure component to ^0.7. PHPUnit 11 suite covers Publisher
publish + private flag and SessionAuthenticator support/auth/failure
paths — 8 tests, 22 assertions, all green.

PLAN.md §13 updated to record the Symfony 8 minimum.

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

.gitignore

@@ -5,6 +5,8 @@ build/
 # Composer
 vendor/
 composer.phar
+# Library packages don't ship composer.lock; applications do.
+framework/php/composer.lock
 
 # PHPUnit
 .phpunit.cache/

PLAN.md

@@ -584,7 +584,7 @@ Phase 1 turns the spike into the smallest dev-mode-only framework that can repla
 | PHP namespace | `PhpQml\Bridge\` |
 | Qt module URI | `PhpQml.Bridge` |
 | C++ namespace | `PhpQml::Bridge` |
-| Symfony minimum | `^7.1` |
+| Symfony minimum | `^8.0` |
 | PHP minimum | `^8.3` |
 | Qt minimum | `6.5 LTS` (build), `6.11` is what's on the dev box |
 

framework/php/composer.json

@@ -5,14 +5,21 @@
     "license": "proprietary",
     "require": {
         "php": "^8.3",
-        "symfony/framework-bundle": "^7.1"
+        "symfony/framework-bundle": "^8.0",
+        "symfony/mercure": "^0.7",
+        "symfony/security-bundle": "^8.0",
+        "symfony/routing": "^8.0",
+        "symfony/http-foundation": "^8.0",
+        "symfony/console": "^8.0",
+        "symfony/dependency-injection": "^8.0",
+        "symfony/config": "^8.0"
     },
     "require-dev": {
         "phpunit/phpunit": "^11",
         "phpstan/phpstan": "^2",
         "phpstan/phpstan-symfony": "^2",
         "friendsofphp/php-cs-fixer": "^3",
-        "symfony/phpunit-bridge": "^7.1"
+        "symfony/phpunit-bridge": "^8.0"
     },
     "autoload": {
         "psr-4": {

framework/php/config/services.yaml

@@ -0,0 +1,13 @@
+services:
+    _defaults:
+        autowire: true
+        autoconfigure: true
+
+    PhpQml\Bridge\:
+        resource: '../src/'
+        exclude:
+            - '../src/BridgeBundle.php'
+
+    PhpQml\Bridge\SessionAuthenticator:
+        arguments:
+            $expectedToken: '%env(default::BRIDGE_TOKEN)%'

framework/php/phpunit.xml.dist

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+         bootstrap="vendor/autoload.php"
+         colors="true"
+         cacheDirectory=".phpunit.cache"
+         executionOrder="random"
+         failOnRisky="true"
+         failOnWarning="true">
+    <testsuites>
+        <testsuite name="bridge">
+            <directory>tests/</directory>
+        </testsuite>
+    </testsuites>
+
+    <source>
+        <include>
+            <directory>src</directory>
+        </include>
+    </source>
+</phpunit>

framework/php/src/BridgeBundle.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpQml\Bridge;
+
+use Symfony\Component\Config\Definition\Configurator\DefinitionConfigurator;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+use Symfony\Component\HttpKernel\Bundle\AbstractBundle;
+
+final class BridgeBundle extends AbstractBundle
+{
+    public function loadExtension(array $config, ContainerConfigurator $container, ContainerBuilder $builder): void
+    {
+        $container->import(__DIR__ . '/../config/services.yaml');
+    }
+
+    public function configure(DefinitionConfigurator $definition): void
+    {
+        // Bundle config tree gains nodes when bridge:doctor and the
+        // skeleton's wiring need settable knobs (Phase 1 sub-commits 3 & 6).
+    }
+}

framework/php/src/Controller/HealthController.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpQml\Bridge\Controller;
+
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\Routing\Attribute\Route;
+
+/**
+ * Readiness probe used by the Qt host to detect when the backend is up.
+ * See PLAN.md §3 (*Startup*, step 4).
+ */
+final class HealthController
+{
+    #[Route('/healthz', name: 'php_qml_bridge_healthz', methods: ['GET'])]
+    public function __invoke(): JsonResponse
+    {
+        return new JsonResponse(['status' => 'ok']);
+    }
+}

framework/php/src/Publisher.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpQml\Bridge;
+
+use Symfony\Component\Mercure\HubInterface;
+use Symfony\Component\Mercure\Update;
+
+/**
+ * Publishes envelopes onto the bridge's Mercure hub.
+ *
+ * Topic conventions and envelope shape are defined in PLAN.md §4.
+ * Reactive-model-aware helpers (publishModelUpdate, etc.) arrive with
+ * the model layer in Phase 2.
+ */
+final readonly class Publisher
+{
+    public function __construct(
+        private HubInterface $hub,
+    ) {
+    }
+
+    /**
+     * @param array<string, mixed> $envelope
+     */
+    public function publish(string $topic, array $envelope, bool $private = false): string
+    {
+        return $this->hub->publish(new Update(
+            $topic,
+            json_encode($envelope, JSON_THROW_ON_ERROR),
+            $private,
+        ));
+    }
+}

framework/php/src/SessionAuthenticator.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpQml\Bridge;
+
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
+use Symfony\Component\Security\Core\Exception\AuthenticationException;
+use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
+use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
+use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
+use Symfony\Component\Security\Http\Authenticator\Passport\SelfValidatingPassport;
+
+/**
+ * Validates the per-session bearer token shared between the Qt host
+ * and the Symfony backend.
+ *
+ * In dev mode the token is read from `.env.local`; in bundled mode the
+ * Qt host generates it per session and passes it to FrankenPHP via env.
+ * See PLAN.md §3 (*Run modes*, *Edge cases — Per-session secret rotation*).
+ */
+final class SessionAuthenticator extends AbstractAuthenticator
+{
+    public function __construct(
+        #[\SensitiveParameter]
+        private readonly string $expectedToken,
+    ) {
+    }
+
+    public function supports(Request $request): ?bool
+    {
+        return $request->headers->has('Authorization');
+    }
+
+    public function authenticate(Request $request): Passport
+    {
+        $header = (string) $request->headers->get('Authorization', '');
+        if (!str_starts_with($header, 'Bearer ')) {
+            throw new AuthenticationException('Bearer token missing.');
+        }
+
+        $token = substr($header, 7);
+        if ($this->expectedToken === '' || !hash_equals($this->expectedToken, $token)) {
+            throw new AuthenticationException('Bearer token invalid.');
+        }
+
+        // Single-session model — there is one bridge "user", not per-end-user auth.
+        return new SelfValidatingPassport(new UserBadge('bridge'));
+    }
+
+    public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response
+    {
+        return null;
+    }
+
+    public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response
+    {
+        return new JsonResponse(
+            [
+                'type'   => 'about:blank',
+                'title'  => 'Unauthorized',
+                'status' => Response::HTTP_UNAUTHORIZED,
+                'detail' => $exception->getMessage(),
+            ],
+            Response::HTTP_UNAUTHORIZED,
+            ['Content-Type' => 'application/problem+json'],
+        );
+    }
+}

framework/php/tests/PublisherTest.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpQml\Bridge\Tests;
+
+use PhpQml\Bridge\Publisher;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Mercure\HubInterface;
+use Symfony\Component\Mercure\Update;
+
+#[CoversClass(Publisher::class)]
+final class PublisherTest extends TestCase
+{
+    public function testPublishWritesEnvelopeAsJsonOnTheGivenTopic(): void
+    {
+        $captured = null;
+        $hub = new class($captured) implements HubInterface {
+            public function __construct(private mixed &$captured) {}
+
+            public function getUrl(): string { return 'http://localhost/.well-known/mercure'; }
+
+            public function getPublicUrl(): string { return $this->getUrl(); }
+
+            public function getProvider(): \Symfony\Component\Mercure\Jwt\TokenProviderInterface
+            {
+                throw new \LogicException('not used in test');
+            }
+
+            public function getFactory(): ?\Symfony\Component\Mercure\Jwt\TokenFactoryInterface
+            {
+                return null;
+            }
+
+            public function publish(Update $update): string
+            {
+                $this->captured = $update;
+                return 'urn:uuid:test';
+            }
+        };
+
+        $publisher = new Publisher($hub);
+        $id = $publisher->publish('app://model/todo', ['op' => 'upsert', 'id' => '1', 'data' => ['done' => true], 'version' => 7]);
+
+        self::assertSame('urn:uuid:test', $id);
+        self::assertInstanceOf(Update::class, $captured);
+        self::assertSame(['app://model/todo'], $captured->getTopics());
+        self::assertJsonStringEqualsJsonString(
+            '{"op":"upsert","id":"1","data":{"done":true},"version":7}',
+            $captured->getData(),
+        );
+        self::assertFalse($captured->isPrivate());
+    }
+
+    public function testPrivateFlagIsForwarded(): void
+    {
+        $captured = null;
+        $hub = new class($captured) implements HubInterface {
+            public function __construct(private mixed &$captured) {}
+            public function getUrl(): string { return ''; }
+            public function getPublicUrl(): string { return ''; }
+            public function getProvider(): \Symfony\Component\Mercure\Jwt\TokenProviderInterface { throw new \LogicException(); }
+            public function getFactory(): ?\Symfony\Component\Mercure\Jwt\TokenFactoryInterface { return null; }
+            public function publish(Update $update): string { $this->captured = $update; return ''; }
+        };
+
+        (new Publisher($hub))->publish('app://event/internal', ['data' => 'x'], private: true);
+
+        self::assertTrue($captured->isPrivate());
+    }
+}

framework/php/tests/SessionAuthenticatorTest.php

@@ -0,0 +1,86 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpQml\Bridge\Tests;
+
+use PhpQml\Bridge\SessionAuthenticator;
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\Security\Core\Exception\AuthenticationException;
+use Symfony\Component\Security\Http\Authenticator\Passport\SelfValidatingPassport;
+
+#[CoversClass(SessionAuthenticator::class)]
+final class SessionAuthenticatorTest extends TestCase
+{
+    public function testSupportsOnlyWhenAuthorizationHeaderPresent(): void
+    {
+        $auth = new SessionAuthenticator('s3cret');
+
+        self::assertFalse($auth->supports(new Request()));
+
+        $request = new Request();
+        $request->headers->set('Authorization', 'Bearer s3cret');
+        self::assertTrue($auth->supports($request));
+    }
+
+    public function testAuthenticateAcceptsMatchingBearerToken(): void
+    {
+        $auth = new SessionAuthenticator('s3cret');
+        $request = new Request();
+        $request->headers->set('Authorization', 'Bearer s3cret');
+
+        $passport = $auth->authenticate($request);
+
+        self::assertInstanceOf(SelfValidatingPassport::class, $passport);
+        self::assertSame('bridge', $passport->getBadge(\Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge::class)->getUserIdentifier());
+    }
+
+    public function testAuthenticateRejectsMissingBearerScheme(): void
+    {
+        $auth = new SessionAuthenticator('s3cret');
+        $request = new Request();
+        $request->headers->set('Authorization', 'Basic deadbeef');
+
+        $this->expectException(AuthenticationException::class);
+        $this->expectExceptionMessage('Bearer token missing.');
+        $auth->authenticate($request);
+    }
+
+    public function testAuthenticateRejectsWrongToken(): void
+    {
+        $auth = new SessionAuthenticator('s3cret');
+        $request = new Request();
+        $request->headers->set('Authorization', 'Bearer wrong');
+
+        $this->expectException(AuthenticationException::class);
+        $this->expectExceptionMessage('Bearer token invalid.');
+        $auth->authenticate($request);
+    }
+
+    public function testAuthenticateRejectsEmptyExpectedToken(): void
+    {
+        // Avoids passing a misconfigured (empty) deployment.
+        $auth = new SessionAuthenticator('');
+        $request = new Request();
+        $request->headers->set('Authorization', 'Bearer ');
+
+        $this->expectException(AuthenticationException::class);
+        $auth->authenticate($request);
+    }
+
+    public function testAuthenticationFailureProducesProblemJson(): void
+    {
+        $auth = new SessionAuthenticator('s3cret');
+        $response = $auth->onAuthenticationFailure(new Request(), new AuthenticationException('Bearer token invalid.'));
+
+        self::assertNotNull($response);
+        self::assertSame(Response::HTTP_UNAUTHORIZED, $response->getStatusCode());
+        self::assertSame('application/problem+json', $response->headers->get('Content-Type'));
+        $body = json_decode((string) $response->getContent(), true);
+        self::assertSame(401, $body['status']);
+        self::assertSame('Unauthorized', $body['title']);
+    }
+}