Add support for object instances in structured output

wachterjohannes · wachterjohannes · commit 50418470a3e9 · 2026-02-04T22:21:05.000+01:00
This change implements two features for structured output: 1. Object instances in response_format option - PlatformSubscriber now accepts both class-string and object instances - Uses Symfony Serializer's OBJECT_TO_POPULATE context - Preserves object identity (same instance returned) - Allows AI to populate missing data in partially-instantiated objects 2. Object parameters in Message::ofUser() - Accepts objects as last parameter for automatic context serialization - Object is JSON-serialized and appended to message content - Provides AI with current object state as context - Stores object reference in message metadata Usage example: ```php $city = new City(name: 'Berlin'); // Partial object $messages = new MessageBag( Message::ofUser('Research missing data for this city', $city), ); $result = $platform->invoke($messages, [ 'response_format' => $city, ]); // Returns same instance with all fields populated ``` Fixes #1545
diff --git a/examples/platform/structured-output-populate-object.php b/examples/platform/structured-output-populate-object.php
@@ -0,0 +1,56 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
+use Symfony\AI\Platform\Message\Message;
+use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Platform\StructuredOutput\PlatformSubscriber;
+use Symfony\Component\EventDispatcher\EventDispatcher;
+
+require_once dirname(__DIR__).'/bootstrap.php';
+
+final class City
+{
+    public function __construct(
+        public ?string $name = null,
+        public ?int $population = null,
+        public ?string $country = null,
+        public ?string $mayor = null,
+    ) {
+    }
+}
+
+$dispatcher = new EventDispatcher();
+$dispatcher->addSubscriber(new PlatformSubscriber());
+
+$platform = PlatformFactory::create(env('OPENAI_API_KEY'), http_client(), eventDispatcher: $dispatcher);
+
+// Create a partially populated object with only the city name
+$city = new City(name: 'Berlin');
+
+echo "Initial object state:\n";
+dump($city);
+
+$messages = new MessageBag(
+    Message::forSystem('You are a helpful assistant that provides information about cities.'),
+    Message::ofUser('Please research the missing data attributes for this city', $city),
+);
+
+$result = $platform->invoke('gpt-5-mini', $messages, [
+    'response_format' => $city,
+]);
+
+echo "\nPopulated object state:\n";
+dump($result->asObject());
+
+// Verify that the same object instance was populated
+echo "\nObject identity preserved: ";
+var_dump($city === $result->asObject());
diff --git a/src/platform/CHANGELOG.md b/src/platform/CHANGELOG.md
@@ -4,6 +4,8 @@ CHANGELOG
 0.3
 ---
 
+ * Add support for populating existing object instances in structured output via `response_format` option
+ * Add support for passing objects to `Message::ofUser()` for automatic serialization as context
  * Add `StreamListenerInterface` to hook into response streams
  * [BC BREAK] Change `TokenUsageAggregation::__construct()` from variadic to array
  * Add `TokenUsageAggregation::add()` method to add more token usages
diff --git a/src/platform/src/Message/Message.php b/src/platform/src/Message/Message.php
@@ -43,8 +43,22 @@ public static function ofAssistant(?string $content = null, ?array $toolCalls =
         return new AssistantMessage($content, $toolCalls);
     }
 
-    public static function ofUser(\Stringable|string|ContentInterface ...$content): UserMessage
+    public static function ofUser(mixed ...$content): UserMessage
     {
+        $contextObject = null;
+        if (\count($content) > 0) {
+            $lastArg = $content[\count($content) - 1];
+            if (\is_object($lastArg) && !$lastArg instanceof \Stringable && !$lastArg instanceof ContentInterface) {
+                $contextObject = array_pop($content);
+            }
+        }
+
+        foreach ($content as $entry) {
+            if (!\is_string($entry) && !$entry instanceof \Stringable && !$entry instanceof ContentInterface) {
+                throw new \InvalidArgumentException(\sprintf('Content must be string, Stringable, or ContentInterface, %s given.', get_debug_type($entry)));
+            }
+        }
+
         $content = array_map(
             static fn (\Stringable|string|ContentInterface $entry) => match (true) {
                 $entry instanceof ContentInterface => $entry,
@@ -54,7 +68,17 @@ public static function ofUser(\Stringable|string|ContentInterface ...$content):
             $content,
         );
 
-        return new UserMessage(...$content);
+        if (null !== $contextObject) {
+            $content[] = new Text(json_encode($contextObject, \JSON_PRETTY_PRINT | \JSON_THROW_ON_ERROR));
+        }
+
+        $message = new UserMessage(...$content);
+
+        if (null !== $contextObject) {
+            $message->getMetadata()->add('structured_output_object', $contextObject);
+        }
+
+        return $message;
     }
 
     public static function ofToolCall(ToolCall $toolCall, string $content): ToolCallMessage
diff --git a/src/platform/src/StructuredOutput/PlatformSubscriber.php b/src/platform/src/StructuredOutput/PlatformSubscriber.php
@@ -29,6 +29,8 @@ final class PlatformSubscriber implements EventSubscriberInterface
 
     private string $outputType;
 
+    private ?object $objectToPopulate = null;
+
     private SerializerInterface $serializer;
 
     public function __construct(
@@ -54,11 +56,19 @@ public function processInput(InvocationEvent $event): void
     {
         $options = $event->getOptions();
 
-        if (!isset($options[self::RESPONSE_FORMAT]) || !\is_string($options[self::RESPONSE_FORMAT])) {
+        if (!isset($options[self::RESPONSE_FORMAT])) {
             return;
         }
 
-        if (!class_exists($options[self::RESPONSE_FORMAT])) {
+        $responseFormat = $options[self::RESPONSE_FORMAT];
+
+        if (\is_object($responseFormat)) {
+            $this->objectToPopulate = $responseFormat;
+            $className = $responseFormat::class;
+        } elseif (\is_string($responseFormat) && class_exists($responseFormat)) {
+            $this->objectToPopulate = null;
+            $className = $responseFormat;
+        } else {
             return;
         }
 
@@ -70,9 +80,9 @@ public function processInput(InvocationEvent $event): void
             throw MissingModelSupportException::forStructuredOutput($event->getModel());
         }
 
-        $this->outputType = $options[self::RESPONSE_FORMAT];
+        $this->outputType = $className;
 
-        $options[self::RESPONSE_FORMAT] = $this->responseFormatFactory->create($options[self::RESPONSE_FORMAT]);
+        $options[self::RESPONSE_FORMAT] = $this->responseFormatFactory->create($className);
 
         $event->setOptions($options);
     }
@@ -86,8 +96,16 @@ public function processResult(ResultEvent $event): void
         }
 
         $deferred = $event->getDeferredResult();
-        $converter = new ResultConverter($deferred->getResultConverter(), $this->serializer, $this->outputType ?? null);
+        $converter = new ResultConverter(
+            $deferred->getResultConverter(),
+            $this->serializer,
+            $this->outputType ?? null,
+            $this->objectToPopulate
+        );
 
         $event->setDeferredResult(new DeferredResult($converter, $deferred->getRawResult(), $options));
+
+        // Reset object to populate for next invocation
+        $this->objectToPopulate = null;
     }
 }
diff --git a/src/platform/src/StructuredOutput/ResultConverter.php b/src/platform/src/StructuredOutput/ResultConverter.php
@@ -20,6 +20,7 @@
 use Symfony\AI\Platform\ResultConverterInterface;
 use Symfony\AI\Platform\TokenUsage\TokenUsageExtractorInterface;
 use Symfony\Component\Serializer\Exception\ExceptionInterface as SerializerExceptionInterface;
+use Symfony\Component\Serializer\Normalizer\AbstractNormalizer;
 use Symfony\Component\Serializer\SerializerInterface;
 
 final class ResultConverter implements ResultConverterInterface
@@ -28,6 +29,7 @@ public function __construct(
         private readonly ResultConverterInterface $innerConverter,
         private readonly SerializerInterface $serializer,
         private readonly ?string $outputType = null,
+        private readonly ?object $objectToPopulate = null,
     ) {
     }
 
@@ -45,8 +47,19 @@ public function convert(RawResultInterface $result, array $options = []): Result
         }
 
         try {
-            $structure = null === $this->outputType ? json_decode($innerResult->getContent(), true, flags: \JSON_THROW_ON_ERROR)
-                : $this->serializer->deserialize($innerResult->getContent(), $this->outputType, 'json');
+            $context = [];
+            if (null !== $this->objectToPopulate) {
+                $context[AbstractNormalizer::OBJECT_TO_POPULATE] = $this->objectToPopulate;
+            }
+
+            $structure = null === $this->outputType
+                ? json_decode($innerResult->getContent(), true, flags: \JSON_THROW_ON_ERROR)
+                : $this->serializer->deserialize(
+                    $innerResult->getContent(),
+                    $this->outputType,
+                    'json',
+                    $context
+                );
         } catch (\JsonException $e) {
             throw new RuntimeException('Cannot json decode the content.', previous: $e);
         } catch (SerializerExceptionInterface $e) {
diff --git a/src/platform/tests/Fixtures/StructuredOutput/City.php b/src/platform/tests/Fixtures/StructuredOutput/City.php
@@ -0,0 +1,23 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\AI\Platform\Tests\Fixtures\StructuredOutput;
+
+final class City
+{
+    public function __construct(
+        public ?string $name = null,
+        public ?int $population = null,
+        public ?string $country = null,
+        public ?string $mayor = null,
+    ) {
+    }
+}
diff --git a/src/platform/tests/Message/MessageTest.php b/src/platform/tests/Message/MessageTest.php
@@ -17,6 +17,7 @@
 use Symfony\AI\Platform\Message\Content\Text;
 use Symfony\AI\Platform\Message\Message;
 use Symfony\AI\Platform\Result\ToolCall;
+use Symfony\AI\Platform\Tests\Fixtures\StructuredOutput\City;
 
 final class MessageTest extends TestCase
 {
@@ -122,4 +123,117 @@ public function testCreateToolCallMessage()
         $this->assertSame('Foo bar.', $message->getContent());
         $this->assertSame($toolCall, $message->getToolCall());
     }
+
+    public function testCreateUserMessageWithObjectSerializesItAsContext()
+    {
+        $city = new City(name: 'Berlin', population: 3500000);
+        $message = Message::ofUser('Please research missing data', $city);
+
+        $content = $message->getContent();
+        $this->assertCount(2, $content);
+
+        $this->assertInstanceOf(Text::class, $content[0]);
+        $this->assertSame('Please research missing data', $content[0]->getText());
+
+        $this->assertInstanceOf(Text::class, $content[1]);
+        $serializedContent = $content[1]->getText();
+        $this->assertStringContainsString('Berlin', $serializedContent);
+        $this->assertStringContainsString('3500000', $serializedContent);
+        $this->assertStringContainsString('"name"', $serializedContent);
+        $this->assertStringContainsString('"population"', $serializedContent);
+    }
+
+    public function testCreateUserMessageWithObjectStoresItInMetadata()
+    {
+        $city = new City(name: 'Berlin');
+        $message = Message::ofUser('Research data', $city);
+
+        $this->assertTrue($message->getMetadata()->has('structured_output_object'));
+        $this->assertSame($city, $message->getMetadata()->get('structured_output_object'));
+    }
+
+    public function testCreateUserMessageWithMultipleContentAndObject()
+    {
+        $city = new City(name: 'Paris');
+        $message = Message::ofUser(
+            'Check this city',
+            new ImageUrl('http://example.com/paris.jpg'),
+            $city
+        );
+
+        $content = $message->getContent();
+        $this->assertCount(3, $content);
+
+        $this->assertInstanceOf(Text::class, $content[0]);
+        $this->assertInstanceOf(ImageUrl::class, $content[1]);
+
+        $this->assertInstanceOf(Text::class, $content[2]);
+        $this->assertStringContainsString('Paris', $content[2]->getText());
+    }
+
+    public function testCreateUserMessageWithOnlyObject()
+    {
+        $city = new City(name: 'Tokyo');
+        $message = Message::ofUser($city);
+
+        $content = $message->getContent();
+        $this->assertCount(1, $content);
+
+        $this->assertInstanceOf(Text::class, $content[0]);
+        $serializedContent = $content[0]->getText();
+        $this->assertStringContainsString('Tokyo', $serializedContent);
+        $this->assertStringContainsString('"name"', $serializedContent);
+    }
+
+    public function testCreateUserMessageWithStringableIsNotTreatedAsObject()
+    {
+        $stringable = new class implements \Stringable {
+            public function __toString(): string
+            {
+                return 'I am stringable';
+            }
+        };
+
+        $message = Message::ofUser('Hello', $stringable);
+
+        $content = $message->getContent();
+        $this->assertCount(2, $content);
+
+        $this->assertInstanceOf(Text::class, $content[0]);
+        $this->assertInstanceOf(Text::class, $content[1]);
+        $this->assertSame('I am stringable', $content[1]->getText());
+
+        $this->assertFalse($message->getMetadata()->has('structured_output_object'));
+    }
+
+    public function testCreateUserMessageWithContentInterfaceIsNotTreatedAsObject()
+    {
+        $imageUrl = new ImageUrl('http://example.com/image.jpg');
+        $message = Message::ofUser('Look at this', $imageUrl);
+
+        $content = $message->getContent();
+        $this->assertCount(2, $content);
+
+        $this->assertInstanceOf(Text::class, $content[0]);
+        $this->assertInstanceOf(ImageUrl::class, $content[1]);
+
+        $this->assertFalse($message->getMetadata()->has('structured_output_object'));
+    }
+
+    public function testCreateUserMessageThrowsExceptionForInvalidContentType()
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Content must be string, Stringable, or ContentInterface');
+
+        Message::ofUser('Hello', ['invalid' => 'array']);
+    }
+
+    public function testCreateUserMessageWithObjectAndInvalidTypeThrowsException()
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('Content must be string, Stringable, or ContentInterface');
+
+        $city = new City(name: 'London');
+        Message::ofUser(123, 'text', $city);
+    }
 }
diff --git a/src/platform/tests/StructuredOutput/PlatformSubscriberTest.php b/src/platform/tests/StructuredOutput/PlatformSubscriberTest.php
diff --git a/src/platform/tests/StructuredOutput/ResultConverterTest.php b/src/platform/tests/StructuredOutput/ResultConverterTest.php
