From 0b42c0fa0939bfd71938719232557630341a9c4a Mon Sep 17 00:00:00 2001
From: Louis-Arnaud Catoire <la.catoire@gmail.com>
Date: Fri, 30 Jan 2026 11:34:05 +0100
Subject: [PATCH] Document that readonly properties cannot be initialized by
 reference

Clarify that readonly properties must be initialized through direct
assignment and cannot be initialized via by-reference parameters.

Fixes https://github.com/php/doc-en/issues/3250
---
 language/oop5/properties.xml | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/language/oop5/properties.xml b/language/oop5/properties.xml
index 9fc60965ea20..3ccb9b26c1a3 100644
--- a/language/oop5/properties.xml
+++ b/language/oop5/properties.xml
@@ -257,6 +257,35 @@ $test1->prop = "foobar";
      </programlisting>
     </example>
    </para>
+   <note>
+    <para>
+     Readonly properties can only be initialized by a direct assignment.
+     An uninitialized readonly property cannot be initialized by reference, not even
+     from the scope where it has been declared: passing it to a function parameter that
+     expects to be passed by reference, or assigning it by reference, results in an
+     <exceptionname>Error</exceptionname> exception.
+     <informalexample>
+      <programlisting role="php" annotations="non-interactive">
+<![CDATA[
+<?php
+
+class Test {
+    public readonly array $matches;
+
+    public function __construct(string $subject) {
+        // Illegal initialization by reference.
+        preg_match('/\d+/', $subject, $this->matches);
+        // Error: Cannot indirectly modify readonly property Test::$matches
+    }
+}
+
+new Test('abc 42');
+?>
+]]>
+      </programlisting>
+     </informalexample>
+    </para>
+   </note>
    <note>
     <para>
      Specifying an explicit default value on readonly properties is not allowed, because a readonly property with a default value is essentially the same as a constant, and thus not particularly useful.