From 4e2fa12c0c0cfca2922091e1018e806cad30378c Mon Sep 17 00:00:00 2001
From: Matthew Weier O'Phinney <matthew@weierophinney.net>
Date: Fri, 6 Dec 2024 08:13:49 -0600
Subject: [PATCH 1/6] docs: adds a note about cpp + hooks

Per a conversation with @crell, added a note to detail behavior of hooks
when the set hook allows more types than the property, and is used with
constructor property promotion.
---
 language/oop5/property-hooks.xml | 63 ++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/language/oop5/property-hooks.xml b/language/oop5/property-hooks.xml
index 05637fb9751a..f68439aa892f 100644
--- a/language/oop5/property-hooks.xml
+++ b/language/oop5/property-hooks.xml
@@ -199,6 +199,69 @@ 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 <literal>string</literal> or <literal>DateTimeInterface</literal>
+    values, but the constructor will only allow <literal>DateTimeInterface<literal>,
+    as that is the type associated with the property.
+   </simpara>
+   <simpara>
+    If you need to allow this kind of behavior from the constructor, you
+    cannot use constructor property promotion.
+   </simpara>
+  </note>
  </sect2>
  <sect2 xml:id="language.oop5.property-hooks.virtual">
   <title>Virtual properties</title>

From 4a46b48e441ff862a3ebac34ff923ba3bb4c31cf Mon Sep 17 00:00:00 2001
From: Matthew Weier O'Phinney <matthew@weierophinney.net>
Date: Wed, 11 Dec 2024 10:52:06 -0600
Subject: [PATCH 2/6] Update language/oop5/property-hooks.xml

Co-authored-by: Gina Peter Banyard <girgias@php.net>
---
 language/oop5/property-hooks.xml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/language/oop5/property-hooks.xml b/language/oop5/property-hooks.xml
index f68439aa892f..a9c4b6448e6d 100644
--- a/language/oop5/property-hooks.xml
+++ b/language/oop5/property-hooks.xml
@@ -201,8 +201,9 @@ class Example
   </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
+    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>

From 894938c37f029e6807ca68952672ab538a19530d Mon Sep 17 00:00:00 2001
From: Matthew Weier O'Phinney <matthew@weierophinney.net>
Date: Wed, 11 Dec 2024 10:52:21 -0600
Subject: [PATCH 3/6] Update language/oop5/property-hooks.xml

Co-authored-by: Gina Peter Banyard <girgias@php.net>
---
 language/oop5/property-hooks.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/language/oop5/property-hooks.xml b/language/oop5/property-hooks.xml
index a9c4b6448e6d..65a5ead9a9e6 100644
--- a/language/oop5/property-hooks.xml
+++ b/language/oop5/property-hooks.xml
@@ -254,8 +254,8 @@ class Example
    </programlisting>
    <simpara>
     Any attempts to set the property outside the constructor will
-    allow either <literal>string</literal> or <literal>DateTimeInterface</literal>
-    values, but the constructor will only allow <literal>DateTimeInterface<literal>,
+    allow either <type>string</type> or <interfacename>DateTimeInterface</interfacename>
+    values, but the constructor will only allow <interfacename>DateTimeInterface<interfacename>,
     as that is the type associated with the property.
    </simpara>
    <simpara>

From dca5509fed1f3be4922a00b70f82635d2792e91f Mon Sep 17 00:00:00 2001
From: Matthew Weier O'Phinney <matthew@weierophinney.net>
Date: Wed, 11 Dec 2024 10:55:00 -0600
Subject: [PATCH 4/6] fix: remove personalization pronouns

---
 language/oop5/property-hooks.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/language/oop5/property-hooks.xml b/language/oop5/property-hooks.xml
index 65a5ead9a9e6..c915e86d858b 100644
--- a/language/oop5/property-hooks.xml
+++ b/language/oop5/property-hooks.xml
@@ -259,8 +259,8 @@ class Example
     as that is the type associated with the property.
    </simpara>
    <simpara>
-    If you need to allow this kind of behavior from the constructor, you
-    cannot use constructor property promotion.
+    If this kind of behavior is needed from the constructor, constructor
+    property promotion cannot be used.
    </simpara>
   </note>
  </sect2>

From 7e0afc47ee1c2bb829a3c6a9deba3717a15fbec4 Mon Sep 17 00:00:00 2001
From: Matthew Weier O'Phinney <matthew@weierophinney.net>
Date: Wed, 11 Dec 2024 10:57:44 -0600
Subject: [PATCH 5/6] fix: clarify property/parameter type references

---
 language/oop5/property-hooks.xml | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/language/oop5/property-hooks.xml b/language/oop5/property-hooks.xml
index c915e86d858b..4dab7d7b0da4 100644
--- a/language/oop5/property-hooks.xml
+++ b/language/oop5/property-hooks.xml
@@ -255,8 +255,10 @@ class Example
    <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>,
-    as that is the type associated with the property.
+    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

From 76863c2873a94e92d6ca5796936eb17d15e942f1 Mon Sep 17 00:00:00 2001
From: Matthew Weier O'Phinney <matthew@weierophinney.net>
Date: Thu, 12 Dec 2024 09:55:10 -0600
Subject: [PATCH 6/6] fix: proper ending tags for interfacename

---
 language/oop5/property-hooks.xml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/language/oop5/property-hooks.xml b/language/oop5/property-hooks.xml
index 4dab7d7b0da4..d66568b61517 100644
--- a/language/oop5/property-hooks.xml
+++ b/language/oop5/property-hooks.xml
@@ -255,8 +255,8 @@ class Example
    <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>)
+    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>