From 852982f81b41d4665606b8e5005b617b95e6fcc9 Mon Sep 17 00:00:00 2001
From: lacatoire <la.catoire@gmail.com>
Date: Thu, 5 Feb 2026 11:00:21 +0100
Subject: [PATCH] Clarify that null coalesce warning suppression only applies
 to variable expressions

---
 language/operators/comparison.xml | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/language/operators/comparison.xml b/language/operators/comparison.xml
index 4e89a9156d0f..b748c33325b7 100644
--- a/language/operators/comparison.xml
+++ b/language/operators/comparison.xml
@@ -500,11 +500,20 @@ if (isset($_POST['action'])) {
    <replaceable>expr2</replaceable> if <replaceable>expr1</replaceable> is
    &null;, and <replaceable>expr1</replaceable> otherwise.
   </para>
-  <para>
-   In particular, this operator does not emit a notice or warning if the left-hand side
-   value does not exist, just like <function>isset</function>. This is especially
-   useful on array keys.
-  </para>
+  <simpara>
+   In particular, this operator does not emit a notice or warning if the
+   left-hand side value does not exist, just like <function>isset</function>.
+   This is especially useful on array keys.
+   This suppression only applies when the left-hand operand is a variable
+   expression: a combination of variable accesses
+   (<literal>$var</literal>), array accesses (<literal>$var['key']</literal>),
+   property accesses (<literal>$var->prop</literal>), null-safe property and
+   method accesses (<literal>$var?->prop</literal>,
+   <literal>$var?->method()</literal>), static property accesses
+   (<literal>Class::$prop</literal>), and function/method calls.
+   If the left-hand operand is a more complex expression (such as a
+   concatenation or arithmetic operation), warnings will not be suppressed.
+  </simpara>
   <note>
    <simpara>
     Please note that the null coalescing operator is an expression, and that it