From fdfef2b14a457ce6361b8f50d55a6a0377352ed7 Mon Sep 17 00:00:00 2001
From: Fabien Potencier <fabien@potencier.org>
Date: Fri, 28 Aug 2026 18:11:30 +0200
Subject: [PATCH] Clarify source function trust requirements

---
 doc/functions/source.rst | 33 +++++++++++++++++++++++++--------
 1 file changed, 25 insertions(+), 8 deletions(-)

diff --git a/doc/functions/source.rst b/doc/functions/source.rst
index 077ba91a4..45cb324d6 100644
--- a/doc/functions/source.rst
+++ b/doc/functions/source.rst
@@ -1,26 +1,43 @@
 ``source``
 ==========
 
-The ``source`` function returns the content of a template without rendering it:
+The ``source`` function returns the content of a resource without rendering it.
+The resource can be a Twig template or any other file exposed by the configured
+template loader:
 
 .. code-block:: twig
 
     {{ source('template.html.twig') }}
     {{ source(some_var) }}
 
+The function uses the same template loaders as the ones used to include
+templates. With the filesystem loader, it can read any file under the configured
+loader paths, even when the file does not contain Twig syntax.
+
+.. warning::
+
+    The return value is considered safe and is not escaped automatically. Use
+    the ``escape`` filter explicitly when the returned content should be
+    escaped:
+
+    .. code-block:: twig
+
+        {{ source('message.txt')|escape }}
+
+    Only pass trusted resource names to ``source()`` and configure loader paths
+    to contain no secrets or untrusted files. In sandboxed templates, allow the
+    ``source`` function only when every loader-accessible resource is safe for
+    template authors to read.
+
 When you set the ``ignore_missing`` flag, Twig will return an empty string if
-the template does not exist:
+the resource does not exist:
 
 .. code-block:: twig
 
     {{ source('template.html.twig', ignore_missing = true) }}
 
-The function uses the same template loaders as the ones used to include
-templates. So, if you are using the filesystem loader, the templates are looked
-for in the paths defined by it.
-
 Arguments
 ---------
 
-* ``name``: The name of the template to read
-* ``ignore_missing``: Whether to ignore missing templates or not
+* ``name``: The name of the resource to read
+* ``ignore_missing``: Whether to ignore missing resources or not