[DOC-CVS] [doc-en] master: appendix 8.4 property hooks: improve terminology (#4688)

Author: CIIDMike (belfie13)
Committer: GitHub (web-flow)
Pusher: jordikroon
Date: 2026-06-05T15:10:33+02:00

Commit: https://github.com/php/doc-en/commit/d7efc67559999c1dda0f65c90617b60c6872a61b
Raw diff: https://github.com/php/doc-en/commit/d7efc67559999c1dda0f65c90617b60c6872a61b.diff

appendix 8.4 property hooks: improve terminology (#4688)

* confusing use of terms

MAY   This word, or the adjective "OPTIONAL", mean that an item is truly optional. RFC2119

in the property hooks example
// A "virtual" property.  It **may** not be set explicitly.
could mean that the virtual property may OR may not be set explicitly.
updated to 
// A "virtual" property. It **can** not be set explicitly.
also added to the example to show the error that would be thrown if the property was set

Co-authored-by: Kamil Tekiela <[email protected]>
Co-authored-by: Jordi Kroon <[email protected]>

Changed paths:
  M  appendices/migration84/new-features.xml


Diff:

diff --git a/appendices/migration84/new-features.xml b/appendices/migration84/new-features.xml
index 652e000f9e87..a562828e009a 100644
--- a/appendices/migration84/new-features.xml
+++ b/appendices/migration84/new-features.xml
@@ -23,7 +23,7 @@
 <?php
 class Person
 {
-    // A "virtual" property.  It may not be set explicitly.
+    // A "virtual" property. It cannot be set explicitly.
     public string $fullName {
         get => $this->firstName . ' ' . $this->lastName;
     }
@@ -52,6 +52,8 @@ $p->firstName = 'peter';
 print $p->firstName; // Prints "Peter"
 $p->lastName = 'Peterson';
 print $p->fullName; // Prints "Peter Peterson"
+
+$p->fullName = "Peter 'Pete' Peterson"; // Throws Error: "Property Person::$fullName is read-only"
 ]]>
     </programlisting>
    </informalexample>
@@ -155,7 +157,7 @@ $object = $reflector->newLazyGhost($initializer);
 
    <!-- TODO: expand and examples? -->
    <simpara>
-    New expressions with constructor arguments are now dereferenceable, meaning
+    New expressions with constructor arguments are now dereferencable, meaning
     they allow chaining method calls, property accesses, etc. without enclosing
     the expression in parentheses.
    </simpara>