From c38868cdd03a8f044b212ccd9bac09c8bc9252c0 Mon Sep 17 00:00:00 2001
From: Fabien Potencier <fabien@potencier.org>
Date: Wed, 4 Feb 2026 22:36:00 +0100
Subject: [PATCH] Add a not about the return value of destructuring

---
 doc/templates.rst | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/doc/templates.rst b/doc/templates.rst
index 9743f8a37..d56130b46 100644
--- a/doc/templates.rst
+++ b/doc/templates.rst
@@ -1111,13 +1111,21 @@ parentheses:
 Destructuring
 -------------
 
+.. versionadded:: 3.23
+
+    Destructuring was added in Twig 3.23.
+
 Destructuring allows you to extract values from sequences and assign them to
 variables in a single operation using the ``=`` :ref:`assignment operator
 <templates-assignment-operator>`.
 
-.. versionadded:: 3.23
+Like in PHP, destructuring expressions return the right-hand side value, not
+the extracted values:
 
-    Destructuring was added in Twig 3.23.
+.. code-block:: twig
+
+    {# returns the full user object, allowing chained access #}
+    {{ ({name} = user).email }}
 
 Sequence Destructuring
 ~~~~~~~~~~~~~~~~~~~~~~