From 25d3c00ae584008ac38c3843427d6cd0280f14d4 Mon Sep 17 00:00:00 2001
From: Christopher Hertel <mail@christopher-hertel.de>
Date: Sat, 13 Dec 2025 00:18:54 +0100
Subject: [PATCH] Add docs for message templates

---
 docs/bundles/ai-bundle.rst   |  8 ++++
 docs/components/platform.rst | 83 ++++++++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+)

diff --git a/docs/bundles/ai-bundle.rst b/docs/bundles/ai-bundle.rst
index ecbe540bb4..280c02570f 100644
--- a/docs/bundles/ai-bundle.rst
+++ b/docs/bundles/ai-bundle.rst
@@ -423,6 +423,14 @@ Then configure the prompt with translation enabled:
 The system prompt text will be automatically translated using the configured translator service.
 If no translation domain is specified, the default domain will be used.
 
+Message Template Support
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Platform's feature for using message templates is set up by the bundle, and conditionally also registers the
+expression language support if the `symfony/expression-language` package is installed.
+
+More about message templates can be found in the :doc:`Platform documentation <components/platform>`.
+
 Memory Provider Configuration
 -----------------------------
 
diff --git a/docs/components/platform.rst b/docs/components/platform.rst
index 33998b11eb..c2f50a5f95 100644
--- a/docs/components/platform.rst
+++ b/docs/components/platform.rst
@@ -229,6 +229,89 @@ This provides several benefits:
     // Get string representation
     echo $id->toRfc4122(); // e.g., "01928d1f-6f2e-7123-a456-123456789abc"
 
+Message Templates
+~~~~~~~~~~~~~~~~~
+
+Message templates allow dynamic variable substitution in messages. Both system and user messages support templates, enabling reusable message patterns with runtime variables.
+
+String Templates
+................
+
+String templates use curly braces for variable placeholders::
+
+    use Symfony\AI\Platform\Message\Message;
+    use Symfony\AI\Platform\Message\MessageBag;
+    use Symfony\AI\Platform\Message\Template;
+
+    // System message with template
+    $messages = new MessageBag(
+        Message::forSystem(Template::string('You are a {role} assistant.')),
+        Message::ofUser('What is PHP?')
+    );
+
+    $result = $platform->invoke('gpt-4o-mini', $messages, [
+        'template_vars' => ['role' => 'programming'],
+    ]);
+
+User messages also support templates::
+
+    $messages = new MessageBag(
+        Message::forSystem('You are a helpful assistant.'),
+        Message::ofUser(Template::string('Tell me about {topic}'))
+    );
+
+    $result = $platform->invoke('gpt-4o-mini', $messages, [
+        'template_vars' => ['topic' => 'PHP'],
+    ]);
+
+Multiple messages can use the same variable set::
+
+    $messages = new MessageBag(
+        Message::forSystem(Template::string('You are a {domain} assistant.')),
+        Message::ofUser(Template::string('Calculate {operation}'))
+    );
+
+    $result = $platform->invoke('gpt-4o-mini', $messages, [
+        'template_vars' => [
+            'domain' => 'math',
+            'operation' => '2 + 2',
+        ],
+    ]);
+
+Expression Templates
+....................
+
+For advanced use cases, expression templates provide dynamic evaluation using Symfony's Expression Language::
+
+    $template = Template::expression('price * quantity');
+
+.. note::
+
+    Expression templates require the ``symfony/expression-language`` component to be installed.
+
+Setup
+.....
+
+To use templates, register the ``TemplateRendererListener`` with your platform's event dispatcher::
+
+    use Symfony\AI\Platform\EventListener\TemplateRendererListener;
+    use Symfony\AI\Platform\Message\TemplateRenderer\StringTemplateRenderer;
+    use Symfony\AI\Platform\Message\TemplateRenderer\TemplateRendererRegistry;
+    use Symfony\Component\EventDispatcher\EventDispatcher;
+
+    $eventDispatcher = new EventDispatcher();
+    $rendererRegistry = new TemplateRendererRegistry([
+        new StringTemplateRenderer(),
+    ]);
+    $templateListener = new TemplateRendererListener($rendererRegistry);
+    $eventDispatcher->addSubscriber($templateListener);
+
+    $platform = PlatformFactory::create($apiKey, eventDispatcher: $eventDispatcher);
+
+.. note::
+
+    When using the AI Bundle, template rendering is automatically configured and available without manual setup.
+
 Result Streaming
 ----------------