From 4719a5ad3d657315317ebf672bfb87f33a0a7cce Mon Sep 17 00:00:00 2001 From: Andrew Brown Date: Wed, 23 Apr 2025 11:33:50 -0500 Subject: [PATCH 1/2] clarify how to "set" value objects with custom casts the current wording only accounts for 1 of the 2 scenarios that can occur when using a custom cast with a value object. that Value Object can encompasses either 1 or many values on the model. the current documentation addresses the example of an `Address`, which would have multiple fields like "line1", "line2", "city", etc. this `set` method should return the array as currently documented. an example of a single value Value Object would be a phone number. a user might want it as an value object rather than a raw number to encapsulate behavior. this `set` method should return a string. there is one distinct advantage to returning a string vs an array. it prevents the cast from being tied to explicit model field names. this allows a field of any name to use the cast: ```php 'phone' => AsPhone::class, 'telephone' => AsPhone::class, ``` if a user returns an array from this simple 1 value cast, the cast loses its flexibility and the above example does not work. --- eloquent-mutators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eloquent-mutators.md b/eloquent-mutators.md index f0bd9c8d67..4bd3aa26dc 100644 --- a/eloquent-mutators.md +++ b/eloquent-mutators.md @@ -736,7 +736,7 @@ class User extends Model ### Value Object Casting -You are not limited to casting values to primitive types. You may also cast values to objects. Defining custom casts that cast values to objects is very similar to casting to primitive types; however, the `set` method should return an array of key / value pairs that will be used to set raw, storable values on the model. +You are not limited to casting values to primitive types. You may also cast values to objects. Defining custom casts that cast values to objects is very similar to casting to primitive types; however, if your value object encompasses more than one storage value, the `set` method must return an array of key / value pairs that will be used to set raw, storable values on the model. If your value object only affects a single field, you should still return a string. As an example, we will define a custom cast class that casts multiple model values into a single `Address` value object. We will assume the `Address` value has two public properties: `lineOne` and `lineTwo`: From 337acf06cf33486d3d9ec8141b59d2066472ea9d Mon Sep 17 00:00:00 2001 From: Taylor Otwell Date: Wed, 23 Apr 2025 11:45:00 -0500 Subject: [PATCH 2/2] Update eloquent-mutators.md --- eloquent-mutators.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eloquent-mutators.md b/eloquent-mutators.md index 4bd3aa26dc..48b025d496 100644 --- a/eloquent-mutators.md +++ b/eloquent-mutators.md @@ -736,7 +736,7 @@ class User extends Model ### Value Object Casting -You are not limited to casting values to primitive types. You may also cast values to objects. Defining custom casts that cast values to objects is very similar to casting to primitive types; however, if your value object encompasses more than one storage value, the `set` method must return an array of key / value pairs that will be used to set raw, storable values on the model. If your value object only affects a single field, you should still return a string. +You are not limited to casting values to primitive types. You may also cast values to objects. Defining custom casts that cast values to objects is very similar to casting to primitive types; however, if your value object encompasses more than one database column, the `set` method must return an array of key / value pairs that will be used to set raw, storable values on the model. If your value object only affects a single column, you should simply return the storable value. As an example, we will define a custom cast class that casts multiple model values into a single `Address` value object. We will assume the `Address` value has two public properties: `lineOne` and `lineTwo`: