Adds a note about hooks + constructor property promotion

language/oop5/property-hooks.xml

@@ -199,6 +199,72 @@ class Example
    On a backed property, omitting a <literal>get</literal> or<literal>set</literal>
    hook means the default read or write behavior will be used.
   </simpara>
+  <note>
+   <simpara>
+    Hooks can be defined when using
+    <link linkend="language.oop5.decon.constructor.promotion">constructor property promotion</link>.
+    However, when doing so, values provided
+    to the constructor must match the type associated with the property,
+    regardless of what the <literal>set</literal> hook might allow.
+   </simpara>
+   <simpara>
+    Consider the following:
+   </simpara>
+   <programlisting role="php">
+<![CDATA[
+class Example
+{
+    public function __construct(
+        public private(set) DateTimeInterface $created {
+            set (string|DateTimeInterface $value) {
+                if (is_string($value)) {
+                    $value = new DateTimeImmutable($value);
+                }
+                $this->created = $value;
+            }
+        },
+    ) {
+    }
+}
+]]>
+   </programlisting>
+   <simpara>
+    Internally, the engine decomposes this to the following:
+   </simpara>
+   <programlisting role="php">
+<![CDATA[
+class Example
+{
+    public private(set) DateTimeInterface $created {
+        set (string|DateTimeInterface $value) {
+            if (is_string($value)) {
+                $value = new DateTimeImmutable($value);
+            }
+            $this->created = $value;
+        }
+    }
+
+    public function __construct(
+        DateTimeInterface $created,
+    ) {
+        $this->created = $created;
+    }
+}
+]]>
+   </programlisting>
+   <simpara>
+    Any attempts to set the property outside the constructor will
+    allow either <type>string</type> or <interfacename>DateTimeInterface</interfacename>
+    values, but the constructor will only allow <interfacename>DateTimeInterface</interfacename>.
+    This is because the defined type for the property (<interfacename>DateTimeInterface</interfacename>)
+    is used as the parameter type within the constructor signature, regardless of what
+    the <literal>set</literal> hook allows.
+   </simpara>
+   <simpara>
+    If this kind of behavior is needed from the constructor, constructor
+    property promotion cannot be used.
+   </simpara>
+  </note>
  </sect2>
  <sect2 xml:id="language.oop5.property-hooks.virtual">
   <title>Virtual properties</title>