From 34f614055871b6eeaee55d4af2a92644fe62f827 Mon Sep 17 00:00:00 2001 From: Italo Date: Sat, 12 Apr 2025 20:56:47 -0400 Subject: [PATCH 1/9] Adds `AsColection::map()` section As part of [#55383](https://github.com/laravel/framework/pull/55383). --- eloquent-mutators.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/eloquent-mutators.md b/eloquent-mutators.md index 7aad935399..11486c939f 100644 --- a/eloquent-mutators.md +++ b/eloquent-mutators.md @@ -449,6 +449,26 @@ protected function casts(): array } ``` +If you desire the collection items to be mapped into an specific class instance, or pass each of them to a callable, you may use a second parameter, or the `map()` method if you want to use the base Collection class. + +```php +use App\ValueObjects\Option; +use Illuminate\Database\Eloquent\Casts\AsCollection; +use Illuminate\Support\Fluent; + +/** + * Get the attributes that should be cast. + * + * @return array + */ +protected function casts(): array +{ + return [ + 'options' => AsCollection::map(Option::class) + ]; +} +``` + ### Date Casting From 94d1976f95678868f613a07d2293f3568f0e948e Mon Sep 17 00:00:00 2001 From: Italo Date: Mon, 14 Apr 2025 15:14:06 -0400 Subject: [PATCH 2/9] Added more clarification --- eloquent-mutators.md | 63 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 61 insertions(+), 2 deletions(-) diff --git a/eloquent-mutators.md b/eloquent-mutators.md index 11486c939f..fc02db2af7 100644 --- a/eloquent-mutators.md +++ b/eloquent-mutators.md @@ -449,12 +449,11 @@ protected function casts(): array } ``` -If you desire the collection items to be mapped into an specific class instance, or pass each of them to a callable, you may use a second parameter, or the `map()` method if you want to use the base Collection class. +If you desire the collection items to be mapped into an specific class instance, or pass each of them to a callable, you may use a second parameter, or the `map()` method if you want to use the base Collection class. ```php use App\ValueObjects\Option; use Illuminate\Database\Eloquent\Casts\AsCollection; -use Illuminate\Support\Fluent; /** * Get the attributes that should be cast. @@ -469,6 +468,66 @@ protected function casts(): array } ``` +For better control on how the items should be constructed once inside the collection, you may set a callable that receives the items as an array. Plus, you may implement the `Arrayable` contract to control how the object should be serialized when the Collection is persisted into the database. + +```php +use App\ValueObjects\Option; +use Illuminate\Database\Eloquent\Casts\AsCollection; + +/** + * Get the attributes that should be cast. + * + * @return array + */ +protected function casts(): array +{ + return [ + 'options' => AsCollection::map([Option::class, 'fromArray']), + ]; +} +``` + + +```php +namespace App\ValueObjects; + +class Option implements Arrayable +{ + /** + * Create a new Option instance. + */ + public function __construct( + protected string $name, + protected mixed $value, + protected bool $isLocked = false + ) { + // + } + + /** + * Get the instance as an array. + * + * @return array + */ + public function toArray(): array + { + return [ + 'name' => $this->name, + 'value' => $this->value, + 'is_locked' => $this->isLocked, + ]; + } + + /** + * Create a new instance from an array. + */ + public function fromArray(array $data): static + { + return new static($data['name'], $data['value'], $data['is_locked']); + } +} +``` + ### Date Casting From 7d32651ae4d778916dd7f6e15f96f40852e0b6f1 Mon Sep 17 00:00:00 2001 From: Italo Date: Mon, 14 Apr 2025 15:15:25 -0400 Subject: [PATCH 3/9] More clarification --- eloquent-mutators.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/eloquent-mutators.md b/eloquent-mutators.md index fc02db2af7..f241cc7689 100644 --- a/eloquent-mutators.md +++ b/eloquent-mutators.md @@ -449,7 +449,7 @@ protected function casts(): array } ``` -If you desire the collection items to be mapped into an specific class instance, or pass each of them to a callable, you may use a second parameter, or the `map()` method if you want to use the base Collection class. +If you desire the collection items to be mapped into an specific class instance, you may use a second parameter or the `map()` method if you want to use the base Collection class. ```php use App\ValueObjects\Option; @@ -468,7 +468,7 @@ protected function casts(): array } ``` -For better control on how the items should be constructed once inside the collection, you may set a callable that receives the items as an array. Plus, you may implement the `Arrayable` contract to control how the object should be serialized when the Collection is persisted into the database. +For better control on how the items should be constructed once inside the collection, you may set a callable that receives the items as an array and returns an object. Plus, you may implement the `Arrayable` contract to control how the object should be serialized when the Collection is persisted into the database. ```php use App\ValueObjects\Option; From d08295160346b3cf573eed0063c8c5a76cf848ad Mon Sep 17 00:00:00 2001 From: Italo Date: Tue, 15 Apr 2025 04:10:27 -0400 Subject: [PATCH 4/9] Update eloquent-mutators.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Sebastian Hädrich <11225821+shaedrich@users.noreply.github.com> --- eloquent-mutators.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/eloquent-mutators.md b/eloquent-mutators.md index f241cc7689..8f9b64f8d3 100644 --- a/eloquent-mutators.md +++ b/eloquent-mutators.md @@ -452,6 +452,8 @@ protected function casts(): array If you desire the collection items to be mapped into an specific class instance, you may use a second parameter or the `map()` method if you want to use the base Collection class. ```php + Date: Tue, 15 Apr 2025 04:12:02 -0400 Subject: [PATCH 5/9] Adds openinh PHP on full class --- eloquent-mutators.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/eloquent-mutators.md b/eloquent-mutators.md index 8f9b64f8d3..b02c4bfc0c 100644 --- a/eloquent-mutators.md +++ b/eloquent-mutators.md @@ -452,8 +452,6 @@ protected function casts(): array If you desire the collection items to be mapped into an specific class instance, you may use a second parameter or the `map()` method if you want to use the base Collection class. ```php - Date: Fri, 18 Apr 2025 14:30:06 -0400 Subject: [PATCH 6/9] Better, almost final, clarification. --- eloquent-mutators.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/eloquent-mutators.md b/eloquent-mutators.md index b02c4bfc0c..5254e8b33e 100644 --- a/eloquent-mutators.md +++ b/eloquent-mutators.md @@ -449,7 +449,7 @@ protected function casts(): array } ``` -If you desire the collection items to be mapped into an specific class instance, you may use a second parameter or the `map()` method if you want to use the base Collection class. +Collection items can be mapped into an specific class instance by using a second parameter. or the `map()` method if you want to use the base Collection class. ```php use App\ValueObjects\Option; @@ -468,7 +468,7 @@ protected function casts(): array } ``` -For better control on how the items should be constructed once inside the collection, you may set a callable that receives the items as an array and returns an object. Plus, you may implement the `Arrayable` contract to control how the object should be serialized when the Collection is persisted into the database. +For better control on how the items should be constructed once inside the Collection, you may set a callable that receives the items as an array and returns an object. ```php use App\ValueObjects\Option; @@ -487,13 +487,17 @@ protected function casts(): array } ``` +When serializing the Collection items, you should implement both `Illuminate\Contracts\Support\Arrayable` and `JsonSerializable` interfaces in the items class to control how these should be persisted into the database as JSON. ```php + * @return array{name: string, data: string, is_locked: bool} */ public function toArray(): array { @@ -520,8 +524,20 @@ class Option implements Arrayable ]; } + /** + * Specify data which should be serialized to JSON. + * + * @return array{name: string, data: string, is_locked: bool} + */ + public function jsonSerialize(): array + { + return $this->toArray(); + } + /** * Create a new instance from an array. + * + * @param array{name: string, data: string, is_locked: bool} $data */ public function fromArray(array $data): static { From 114ce4545e427761a2af2fbdd96fe3511e2b7f88 Mon Sep 17 00:00:00 2001 From: Italo Date: Sun, 20 Apr 2025 17:18:29 -0400 Subject: [PATCH 7/9] Minor change to the Option example so it makes sense --- eloquent-mutators.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/eloquent-mutators.md b/eloquent-mutators.md index 5254e8b33e..3f0f70d8f6 100644 --- a/eloquent-mutators.md +++ b/eloquent-mutators.md @@ -503,9 +503,9 @@ class Option implements Arrayable, JsonSerializable * Create a new Option instance. */ public function __construct( - protected string $name, - protected mixed $value, - protected bool $isLocked = false + public string $name, + public mixed $value, + public bool $isLocked = false ) { // } From 47f62657fa817e041818acfada1611effd51abc3 Mon Sep 17 00:00:00 2001 From: Italo Date: Sun, 20 Apr 2025 17:22:21 -0400 Subject: [PATCH 8/9] Better clarification about serialization --- eloquent-mutators.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/eloquent-mutators.md b/eloquent-mutators.md index 3f0f70d8f6..b6274933c5 100644 --- a/eloquent-mutators.md +++ b/eloquent-mutators.md @@ -468,7 +468,7 @@ protected function casts(): array } ``` -For better control on how the items should be constructed once inside the Collection, you may set a callable that receives the items as an array and returns an object. +For better control on how the items should be constructed once inside the Collection, you may set a callable that receives each item as an array. ```php use App\ValueObjects\Option; @@ -487,7 +487,7 @@ protected function casts(): array } ``` -When serializing the Collection items, you should implement both `Illuminate\Contracts\Support\Arrayable` and `JsonSerializable` interfaces in the items class to control how these should be persisted into the database as JSON. +When handling a collection of objects, you should implement both `Illuminate\Contracts\Support\Arrayable` and `JsonSerializable` interfaces in the object class to control how these should be serialized into the database as JSON. ```php Date: Tue, 22 Apr 2025 09:09:17 -0500 Subject: [PATCH 9/9] formatting --- eloquent-mutators.md | 37 ++++--------------------------------- 1 file changed, 4 insertions(+), 33 deletions(-) diff --git a/eloquent-mutators.md b/eloquent-mutators.md index b6274933c5..f0bd9c8d67 100644 --- a/eloquent-mutators.md +++ b/eloquent-mutators.md @@ -449,7 +449,7 @@ protected function casts(): array } ``` -Collection items can be mapped into an specific class instance by using a second parameter. or the `map()` method if you want to use the base Collection class. +The `of` method may be used to indicate collection items should be mapped into a given class via the collection's [`mapInto` method](/docs/{{version}}/collections#method-mapinto): ```php use App\ValueObjects\Option; @@ -463,31 +463,12 @@ use Illuminate\Database\Eloquent\Casts\AsCollection; protected function casts(): array { return [ - 'options' => AsCollection::map(Option::class) + 'options' => AsCollection::of(Option::class) ]; } ``` -For better control on how the items should be constructed once inside the Collection, you may set a callable that receives each item as an array. - -```php -use App\ValueObjects\Option; -use Illuminate\Database\Eloquent\Casts\AsCollection; - -/** - * Get the attributes that should be cast. - * - * @return array - */ -protected function casts(): array -{ - return [ - 'options' => AsCollection::map([Option::class, 'fromArray']), - ]; -} -``` - -When handling a collection of objects, you should implement both `Illuminate\Contracts\Support\Arrayable` and `JsonSerializable` interfaces in the object class to control how these should be serialized into the database as JSON. +When mapping collections to objects, the object should implement the `Illuminate\Contracts\Support\Arrayable` and `JsonSerializable` interfaces to define how their instances should be serialized into the database as JSON: ```php toArray(); } - - /** - * Create a new instance from an array. - * - * @param array{name: string, data: string, is_locked: bool} $data - */ - public function fromArray(array $data): static - { - return new static($data['name'], $data['value'], $data['is_locked']); - } } ```