updated rfc

Author: withinboredom

published/records.ptxt

@@ -12,7 +12,7 @@ This RFC proposes the introduction of ''%%record%%'' objects, which are immutabl
 
 ==== Value objects ====
 
-Value objects are immutable objects that represent a value. They’re used to store values with a different semantic meaning than their technical value, adding additional context. For example, a ''%%Point%%'' object with ''%%x%%'' and ''%%y%%'' properties can represent a point in a 2D space, and an ''%%ExpirationDate%%'' can represent a date when something expires. This prevents developers from accidentally using the wrong value in the wrong context.
+Value objects are immutable objects that represent a value. They’re used to store values with a different semantic by wrapping their technical value, adding additional context. For example, a ''%%Point%%'' object with ''%%x%%'' and ''%%y%%'' properties can represent a point in a 2D space, and an ''%%ExpirationDate%%'' can represent a date when something expires. This prevents developers from accidentally using the wrong value in the wrong context.
 
 Consider this example where a function accepts an integer as a user ID, and the ID is accidentally set to a nonsensical value:
 
@@ -76,6 +76,8 @@ A **record** body may also declare properties whose values are only mutable duri
 
 A **record** body may also contain static methods and properties, which behave identically to static methods and properties in classes. They may be accessed using the ''%%::%%'' operator.
 
+As an example, the following code defines a **record** named ''%%Pigment%%'' to represent a color, ''%%StockPaint%%'' to represent paint colors in stock, and ''%%PaintBucket%%'' to represent a collection of stock paints mixed together. The actual behavior isn’t important, but illustrates the syntax and semantics of records.
+
 <code php>
 namespace Paint;
 
@@ -125,7 +127,26 @@ record PaintBucket(StockPaint ...$constituents) {
 
 === Usage ===
 
-A record may be used as a readonly class, as the behavior of the two is very similar, assisting in migrating from one implementation to another.
+A record may be used much like a class, as the behavior of the two is very similar, assisting in migrating from one implementation to another:
+
+<code php>
+$gray = $bucket->mixIn($blackPaint)->mixIn($whitePaint);
+</code>
+
+Records are instantiated in a function format, with ''%%&%%'' prepended. This provides visual feedback that a record is being created instead of a function call.
+
+<code php>
+$black = &Pigment(0, 0, 0);
+$white = &Pigment(255, 255, 255);
+$blackPaint = &StockPaint($black, 1);
+$whitePaint = &StockPaint($white, 1);
+$bucket = &PaintBucket();
+
+$gray = $bucket->mixIn($blackPaint)->mixIn($whitePaint);
+$grey = $bucket->mixIn($blackPaint)->mixIn($whitePaint);
+
+assert($gray === $grey); // true
+</code>
 
 === Optional parameters and default values ===
 
@@ -135,7 +156,7 @@ One or more properties defined in the inline constructor may have a default valu
 
 <code php>
 record Rectangle(int $x, int $y = 10);
-var_dump(Rectangle(10)); // output a record with x: 10 and y: 10
+var_dump(&Rectangle(10)); // output a record with x: 10 and y: 10
 </code>
 
 === Auto-generated with method ===
@@ -163,7 +184,7 @@ record UserId(int $id) {
   }
 }
 
-$userId = UserId(1);
+$userId = &UserId(1);
 $otherId = $userId->with(2); // Fails: Named arguments must be used
 $otherId = $userId->with(serialNumber: "U2"); // Error: serialNumber is not defined in the inline constructor
 $otherId = $userId->with(id: 2); // Success: id is updated
@@ -174,20 +195,15 @@ Using variadic arguments:
 <code php>
 record Vector(int $dimensions, int ...$values);
 
-$vector = Vector(3, 1, 2, 3);
+$vector = &Vector(3, 1, 2, 3);
 $vector = $vector->with(dimensions: 4); // Success: values are updated
 $vector = $vector->with(dimensions: 4, 1, 2, 3, 4); // Error: mixing named arguments with variadic arguments is not allowed by PHP syntax
 $vector = $vector->with(dimensions: 4)->with(1, 2, 3, 4); // Success: First update dimensions, then values
 </code>
 
 == Custom with method ==
 
-A developer may define their own ''%%with%%'' method if they choose, and reference the generated ''%%with%%'' method using ''%%parent::with()%%''. This allows a developer to define policies or constraints on how data is updated.
-
-Contravariance and covariance are enforced in the developer’s code via the ''%%Record%%'' interface:
-
-  * Contravariance: the parameter type of the custom ''%%with%%'' method must be a supertype of the generated ''%%with%%'' method.
-  * Covariance: the return type of the custom ''%%with%%'' method must be ''%%self%%'' of the generated ''%%with%%'' method.
+A developer may define their own ''%%with%%'' method if they choose, and reference the generated ''%%with%%'' method using ''%%parent::with()%%''. This allows a developer to define policies or constraints on how data can change from instance to instance.
 
 <code php>
 record Planet(string $name, int $population) {
@@ -212,43 +228,57 @@ The inline constructor is always required and must define at least one parameter
 When a traditional constructor exists and is called, the properties are already initialized to the values from the inline constructor and are mutable until the end of the method, at which point they become immutable.
 
 <code php>
-// Inline constructor
-record User(string $name, string $email) {
+// Inline constructor defining two properties
+record User(string $name, string $emailAddress) {
   public string $id;
 
   // Traditional constructor
   public function __construct() {
-    if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
+    if (!is_valid_email($this->emailAddress)) {
       throw new InvalidArgumentException("Invalid email address");
     }
 
-    $this->id = hash('sha256', $email);
-    $this->name = ucwords($name);
+    $this->id = hash('sha256', $this->emailAddress);
+    $this->name = ucwords($this->name);
+    // all properties are now immutable
   }
 }
 </code>
 
 ==== Mental models and how it works ====
 
-From the perspective of a developer, declaring a record declares an object and function with the same name. The developer can consider the record function (the inline constructor) as a factory function that creates a new object or retrieves an existing object from an array.
+From the perspective of a developer, declaring a record declares an object with the same name. The developer can consider the record function (the inline constructor) as a factory function that creates a new object or retrieves an existing object from an array.
 
 For example, this would be a valid mental model for a Point record:
 
 <code php>
 record Point(int $x, int $y) {
+    public float $magnitude;
+    
+    public function __construct() {
+        $this->magnitude = sqrt($this->x ** 2 + $this->y ** 2);
+    }
+
     public function add(Point $point): Point {
-        return Point($this->x + $point->x, $this->y + $point->y);
+        return &Point($this->x + $point->x, $this->y + $point->y);
+    }
+    
+    public function dot(Point $point): int {
+        return $this->x * $point->x + $this->y * $point->y;
     }
 }
 
 // similar to declaring the following function and class
 
-// used during construction to allow immutability
+// used during construction to allow mutability
 class Point_Implementation {
     public int $x;
     public int $y;
+    public float $magnitude;
 
-    public function __construct() {}
+    public function __construct() {
+        $this->magnitude = sqrt($this->x ** 2 + $this->y ** 2);
+    }
 
     public function with(...$parameters) {
         // validity checks omitted for brevity
@@ -259,14 +289,16 @@ class Point_Implementation {
     public function add(Point $point): Point {
         return Point($this->x + $point->x, $this->y + $point->y);
     }
+    
+    public function dot(Point $point): int {
+        return $this->x * $point->x + $this->y * $point->y;
+    }
 }
 
-interface Record {
-    public function with(...$parameters): self;
-}
+// used to enforce immutability but has nearly the same implementation
+readonly class Point {
+    public float $magnitude;
 
-// used to enforce immutability but has the same implementation
-readonly class Point implements Record {
     public function __construct(public int $x, public int $y) {}
 
     public function with(...$parameters): self {
@@ -278,64 +310,73 @@ readonly class Point implements Record {
     public function add(Point $point): Point {
         return Point($this->x + $point->x, $this->y + $point->y);
     }
+    
+    public function dot(Point $point): int {
+        return $this->x * $point->x + $this->y * $point->y;
+    }
 }
 
 function Point(int $x, int $y): Point {
     static $points = [];
-    // look up the identity of the point
-    $key = hash_func($x, $y);
+    
+    $key = hash_object($mutablePoint);
     if ($points[$key] ?? null) {
         // return an existing point
         return $points[$key];
     }
-
+    
     // create a new point
     $reflector = new \ReflectionClass(Point_Implementation::class);
-    $point = $reflector->newInstanceWithoutConstructor();
-    $point->x = $x;
-    $point->y = $y;
-    $point->__construct();
-    // copy properties to an immutable point and return it
-    $point = new Point($point->x, $point->y);
+    $mutablePoint = $reflector->newInstanceWithoutConstructor();
+    $mutablePoint->x = $x;
+    $mutablePoint->y = $y;
+    $mutablePoint->__construct();
+    
+    // copy properties to an immutable Point and return it
+    $point = new Point($mutablePoint->x, $mutablePoint->y);
+    $point->magnitude = $mutablePoint->magnitude;
     return $points[$key] = $point;
 }
 </code>
 
-In reality, this is quite different from how it works in the engine, but this provides a mental model of how behavior should be expected to work. In other words, if it can work in the above model, then it be possible.
+In reality, this is quite different from how it works in the engine, but this provides a mental model of how behavior should be expected to work.
 
 ==== Performance considerations ====
 
-To ensure that records are both performant and memory-efficient, the RFC proposes leveraging PHP’s copy-on-write (COW) semantics (similar to arrays) and interning values. Unlike interned strings, the garbage collector will be allowed to clean up these interned records when they’re no longer necessary.
+To ensure that records are both performant and memory-efficient, the RFC proposes leveraging PHP’s copy-on-write (COW) semantics (similar to arrays) and interning values. Unlike interned strings, the garbage collector will be allowed to clean up these interned records when they’re no longer referenced.
 
 <code php>
-$point1 = Point(3, 4);
+$point1 = &Point(3, 4);
 $point2 = $point1; // No data duplication, $point2 references the same data as $point1
 $point3 = Point(3, 4); // No data duplication, it is pointing to the same memory as $point1
 
 $point4 = $point1->with(x: 5); // Data duplication occurs here, creating a new instance
+$point5 = &Point(5, 4); // No data duplication, it is pointing to the same memory as $point4
 </code>
 
 === Cloning and with() ===
 
 Calling ''%%clone%%'' on a ''%%record%%'' results in the same record object being returned. As it is a "value" object, it represents a value and is the same thing as saying ''%%clone 3%%''—you expect to get back a ''%%3%%''.
 
-''%%with%%'' may be called with no arguments, and it is the same behavior as ''%%clone%%''. This is an important consideration because a developer may call ''%%$new = $record->with(...$array)%%'' and we don’t want to crash. If a developer wants to crash, they can do by ''%%assert($new !== $record)%%''.
+If ''%%->with()%%'' is called with no arguments, a warning will be emitted, as this is most likely a mistake.
 
 ==== Serialization and deserialization ====
 
-Records are fully serializable and deserializable.
+Records are fully serializable and deserializable, even when nested.
 
 <code php>
 record Single(string $value);
 record Multiple(string $value1, string $value2);
 
-echo $single = serialize(Single('value')); // Outputs: "O:6:"Single":1:{s:5:"value";s:5:"value";}"
-echo $multiple = serialize(Multiple('value1', 'value2')); // Outputs: "O:8:"Multiple":1:{s:6:"values";a:2:{i:0;s:6:"value1";i:1;s:6:"value2";}}"
+echo $single = serialize(&Single('value')); // Outputs: "O:6:"Single":1:{s:5:"value";s:5:"value";}"
+echo $multiple = serialize(&Multiple('value1', 'value2')); // Outputs: "O:8:"Multiple":1:{s:6:"values";a:2:{i:0;s:6:"value1";i:1;s:6:"value2";}}"
 
-echo unserialize($single) === Single('value'); // Outputs: true
-echo unserialize($multiple) === Multiple('value1', 'value2'); // Outputs: true
+echo unserialize($single) === &Single('value'); // Outputs: true
+echo unserialize($multiple) === &Multiple('value1', 'value2'); // Outputs: true
 </code>
 
+If a record contains objects or values that are unserializable, the record will not be serializable.
+
 ==== Equality ====
 
 A ''%%record%%'' is always strongly equal (''%%===%%'') to another record with the same value in the properties, much like an ''%%array%%'' is strongly equal to another array containing the same elements. For all intents, ''%%$recordA === $recordB%%'' is the same as ''%%$recordA == $recordB%%''.
@@ -344,7 +385,7 @@ Comparison operations will behave exactly like they do for classes, which is cur
 
 === Non-trivial values ===
 
-For non-trivial values (e.g., objects, closures, resources, etc.), the ''%%===%%'' operator will return ''%%true%%'' if the two operands reference the same object.
+For non-trivial values (e.g., objects, closures, resources, etc.), the ''%%===%%'' operator will return ''%%true%%'' if the two operands reference the same instances.
 
 For example, if two different DateTime records reference the exact same date and are stored in a record, the records will not be considered equal:
 
@@ -360,7 +401,7 @@ $dateRecord2 = Date($date2);
 echo $dateRecord1 === $dateRecord2; // Outputs: false
 </code>
 
-However, this can be worked around by being a bit creative (see: mental model):
+However, this can be worked around by being a bit creative (see: mental model) as only the values passed in the constructor are compared:
 
 <code php>
 record Date(string $date) {
@@ -371,10 +412,10 @@ record Date(string $date) {
     }
 }
 
-$date1 = Date('2024-07-19');
-$date2 = Date('2024-07-19');
+$date1 = &Date('2024-07-19');
+$date2 = &Date('2024-07-19');
 
-echo $date1->datetime === $date2->datetime; // Outputs: true
+echo $date1->datetime === $date2->datetime ? 'true' : 'false'; // Outputs: true
 </code>
 
 ==== Type hinting ====
@@ -412,21 +453,25 @@ Calling ''%%finalizeRecord()%%'' on a record that has already been finalized wil
 
 === isRecord() ===
 
-The ''%%isRecord()%%'' method is used to determine if an object is a record. It returns ''%%true%%'' if the object is a record,
+The ''%%isRecord()%%'' method is used to determine if an object is a record. It returns ''%%true%%'' if the object is a record.
 
 === getInlineConstructor() ===
 
 The ''%%getInlineConstructor()%%'' method is used to get the inline constructor of a record as a ''%%ReflectionFunction%%''. This can be used to inspect inlined properties and their types.
 
+Invoking the ''%%invoke()%%'' method on the ''%%ReflectionFunction%%'' will create a finalized record.
+
 === getTraditionalConstructor() ===
 
 The ''%%getTraditionalConstructor()%%'' method is used to get the traditional constructor of a record as a ''%%ReflectionMethod%%''. This can be useful to inspect the constructor for further initialization.
 
+Invoking the ''%%invoke()%%'' method on the ''%%ReflectionMethod%%'' on a finalized record will throw an exception.
+
 === makeMutable() ===
 
 The ''%%makeMutable()%%'' method is used to create a new instance of a record with mutable properties. The returned instance doesn’t provide any value semantics and should only be used for testing purposes or when there is no other option.
 
-A mutable record can be finalized again using ''%%finalizeRecord()%%'' and to the engine, these are regular classes. For example, ''%%var_dump()%%'' will output ''%%object%%'' instead of ''%%record%%''.
+A mutable record can be finalized again using ''%%finalizeRecord()%%''. A mutable record will not be considered a record by ''%%isRecord()%%'' or implement the ''%%\Record%%'' interface. It is a regular object with the same properties and methods as the record. For example, ''%%var_dump()%%'' will output ''%%object%%'' instead of ''%%record%%''.
 
 === isMutable() ===
 
@@ -439,10 +484,10 @@ In cases where custom deserialization is required, a developer can use ''%%Refle
 <code php>
 record Seconds(int $seconds);
 
-$example = Seconds(5);
+$example = &Seconds(5);
 
-$reflector = new ReflectionRecord(ExpirationDate::class);
-$expiration = $reflector->newInstanceWithoutConstructor();
+$reflector = new ReflectionRecord(Seconds::class);
+$expiration = $reflector->newInstanceWithoutConstructor(); // this is a mutable object
 $expiration->seconds = 5;
 assert($example !== $expiration); // true
 $expiration = $reflector->finalizeRecord($expiration);
@@ -464,20 +509,18 @@ record(Point)#1 (2) {
 
 ==== Considerations for implementations ====
 
-A ''%%record%%'' cannot share its name with an existing ''%%record%%'', ''%%class%%'', or ''%%function%%'' because defining a ''%%record%%'' creates both a ''%%class%%'' and a ''%%function%%'' with the same name.
+A ''%%record%%'' cannot share its name with an existing ''%%record%%'', ''%%class%%'', ''%%interface%%'', ''%%trait%%'', or ''%%function%%'', just like a class.
 
 ==== Autoloading ====
 
-This RFC chooses to omit autoloading from the specification for a record. The reason is that instantiating a record calls the function implicitly declared when the record is explicitly declared, PHP doesn’t currently support autoloading functions, and solving function autoloading is out-of-scope for this RFC.
-
-Once function autoloading is implemented in PHP at some hopeful point in the future, said autoloader could locate the record and then autoload it.
-
-The author of this RFC strongly encourages someone to put forward a function autoloading RFC if autoloading is desired for records.
+Records will be autoloaded in the same way as classes.
 
 ===== Backward Incompatible Changes =====
 
 To avoid conflicts with existing code, the ''%%record%%'' keyword will be handled similarly to ''%%enum%%'' to prevent backward compatibility issues.
 
+Since ''%%&%%'' is currently a syntax error when prefixed on a function call, it will be used to denote a record instantiation.
+
 ===== Proposed PHP Version(s) =====
 
 PHP 8.5
@@ -518,25 +561,20 @@ None.
 
 ===== Proposed Voting Choices =====
 
-Include these so readers know where you’re heading and can discuss the proposed voting options.
+2/3 majority.
 
 ===== Patches and Tests =====
 
 TBD
 
 ===== Implementation =====
 
-After the project is implemented, this section should contain
-
-  - the version(s) it was merged into
-  - a link to the git commit(s)
-  - a link to the PHP manual entry for the feature
-  - a link to the language specification section (if any)
+To be completed during a later phase of discussion.
 
 ===== References =====
 
-Links to external references, discussions or RFCs
+  * [[https://en.wikipedia.org/wiki/Value_semantics|Value semantics]]
 
 ===== Rejected Features =====
 
-Keep this updated with features that were discussed on the mail lists.
+TBD