feature #711 [Platform] Add UserMessage::asText() method (OskarStark)

This PR was squashed before being merged into the main branch.

Discussion
----------

[Platform] Add `UserMessage::asText()` method

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| Docs?         | no
| Issues        | --
| License       | MIT

Move text extraction logic from MessageBag::getUserMessageText() to a new UserMessage::asText() method for better encapsulation and reusability.

Commits
-------

c245522 [Platform] Add `UserMessage::asText()` method

Author: OskarStark

src/agent/src/MultiAgent/MultiAgent.php

@@ -66,10 +66,11 @@ public function call(MessageBag $messages, array $options = []): ResultInterface
     {
         $userMessages = $messages->withoutSystemMessage();
 
-        $userText = $userMessages->getUserMessageText();
-        if (null === $userText) {
+        $userMessage = $userMessages->getUserMessage();
+        if (null === $userMessage) {
             throw new RuntimeException('No user message found in conversation.');
         }
+        $userText = $userMessage->asText();
         $this->logger->debug('MultiAgent: Processing user message', ['user_text' => $userText]);
 
         $this->logger->debug('MultiAgent: Available agents for routing', ['agents' => array_map(fn ($handoff) => [
@@ -120,11 +121,6 @@ public function call(MessageBag $messages, array $options = []): ResultInterface
 
         $this->logger->debug('MultiAgent: Delegating to agent', ['agent_name' => $decision->agentName]);
 
-        $userMessage = $userMessages->getUserMessage();
-        if (null === $userMessage) {
-            throw new RuntimeException('No user message found in conversation.');
-        }
-
         // Call the selected agent with the original user question
         return $targetAgent->call(new MessageBag($userMessage), $options);
     }

src/agent/tests/MultiAgent/MultiAgentTest.php

@@ -353,7 +353,8 @@ public function testBuildAgentSelectionPromptIncludesFallback()
             ->method('call')
             ->with(
                 $this->callback(function (MessageBag $messages) {
-                    $text = $messages->getUserMessageText();
+                    $userMessage = $messages->getUserMessage();
+                    $text = $userMessage?->asText();
 
                     return str_contains($text, 'general-fallback: fallback agent for general/unmatched queries');
                 }),

src/platform/src/Message/MessageBag.php

@@ -11,7 +11,6 @@
 
 namespace Symfony\AI\Platform\Message;
 
-use Symfony\AI\Platform\Message\Content\Text;
 use Symfony\AI\Platform\Metadata\MetadataAwareTrait;
 
 /**
@@ -66,23 +65,6 @@ public function getUserMessage(): ?UserMessage
         return null;
     }
 
-    public function getUserMessageText(): ?string
-    {
-        $userMessage = $this->getUserMessage();
-        if (null === $userMessage) {
-            return null;
-        }
-
-        $textParts = [];
-        foreach ($userMessage->content as $content) {
-            if ($content instanceof Text) {
-                $textParts[] = $content->text;
-            }
-        }
-
-        return implode(' ', $textParts);
-    }
-
     public function with(MessageInterface $message): self
     {
         $messages = clone $this;

src/platform/src/Message/UserMessage.php

@@ -15,6 +15,7 @@
 use Symfony\AI\Platform\Message\Content\ContentInterface;
 use Symfony\AI\Platform\Message\Content\Image;
 use Symfony\AI\Platform\Message\Content\ImageUrl;
+use Symfony\AI\Platform\Message\Content\Text;
 use Symfony\Component\Uid\AbstractUid;
 use Symfony\Component\Uid\TimeBasedUidInterface;
 use Symfony\Component\Uid\Uuid;
@@ -69,4 +70,20 @@ public function hasImageContent(): bool
 
         return false;
     }
+
+    public function asText(): ?string
+    {
+        $textParts = [];
+        foreach ($this->content as $content) {
+            if ($content instanceof Text) {
+                $textParts[] = $content->text;
+            }
+        }
+
+        if ([] === $textParts) {
+            return null;
+        }
+
+        return implode(' ', $textParts);
+    }
 }

src/platform/tests/Message/MessageBagTest.php

@@ -216,7 +216,8 @@ public function testGetUserMessageText()
             Message::ofAssistant('How can I help you?'),
         );
 
-        $userText = $messageBag->getUserMessageText();
+        $userMessage = $messageBag->getUserMessage();
+        $userText = $userMessage?->asText();
 
         $this->assertSame('Hello, world!', $userText);
     }
@@ -228,7 +229,9 @@ public function testGetUserMessageTextReturnsNullWithoutUserMessage()
             Message::ofAssistant('It is time to sleep.'),
         );
 
-        $this->assertNull($messageBag->getUserMessageText());
+        $userMessage = $messageBag->getUserMessage();
+
+        $this->assertNull($userMessage?->asText());
     }
 
     public function testGetUserMessageTextWithMultipleTextParts()
@@ -239,7 +242,8 @@ public function testGetUserMessageTextWithMultipleTextParts()
             Message::ofAssistant('Response'),
         );
 
-        $userText = $messageBag->getUserMessageText();
+        $userMessage = $messageBag->getUserMessage();
+        $userText = $userMessage?->asText();
 
         $this->assertSame('Part one Part two Part three', $userText);
     }
@@ -252,7 +256,8 @@ public function testGetUserMessageTextIgnoresNonTextContent()
             Message::ofAssistant('Response'),
         );
 
-        $userText = $messageBag->getUserMessageText();
+        $userMessage = $messageBag->getUserMessage();
+        $userText = $userMessage?->asText();
 
         // Should only return the text content, ignoring the image
         $this->assertSame('Text content', $userText);

src/platform/tests/Message/UserMessageTest.php

@@ -108,4 +108,46 @@ public function testMessageIdImplementsRequiredInterfaces()
         $this->assertInstanceOf(TimeBasedUidInterface::class, $message->getId());
         $this->assertInstanceOf(UuidV7::class, $message->getId());
     }
+
+    public function testAsTextWithSingleTextContent()
+    {
+        $message = new UserMessage(new Text('Hello, world!'));
+
+        $this->assertSame('Hello, world!', $message->asText());
+    }
+
+    public function testAsTextWithMultipleTextParts()
+    {
+        $message = new UserMessage(new Text('Part one'), new Text('Part two'), new Text('Part three'));
+
+        $this->assertSame('Part one Part two Part three', $message->asText());
+    }
+
+    public function testAsTextIgnoresNonTextContent()
+    {
+        $message = new UserMessage(
+            new Text('Text content'),
+            new ImageUrl('http://example.com/image.png'),
+            new Text('More text')
+        );
+
+        $this->assertSame('Text content More text', $message->asText());
+    }
+
+    public function testAsTextWithoutTextContent()
+    {
+        $message = new UserMessage(new ImageUrl('http://example.com/image.png'));
+
+        $this->assertNull($message->asText());
+    }
+
+    public function testAsTextWithAudioAndImage()
+    {
+        $message = new UserMessage(
+            Audio::fromFile(\dirname(__DIR__, 4).'/fixtures/audio.mp3'),
+            new ImageUrl('http://example.com/image.png')
+        );
+
+        $this->assertNull($message->asText());
+    }
 }