From 05219bb050cc086c614bedc8b9cc6579498424e4 Mon Sep 17 00:00:00 2001
From: Andreas Dyballa <A.Dyballa@perfect-media-solutions.de>
Date: Fri, 15 Aug 2025 15:28:07 +0200
Subject: [PATCH] contracts: clarify CastsAttributes::set() may receive TGet;
 recommend symmetric casts

- PhpDoc: explain assignment symmetry; set() can receive runtime value (TGet)
- Change @param to TGet|TSet|null
- Note on object caching; encourage symmetric casts (TGet == TSet)
- No runtime behavior changes
---
 Database/Eloquent/CastsAttributes.php | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/Database/Eloquent/CastsAttributes.php b/Database/Eloquent/CastsAttributes.php
index 89cec66..21776bc 100644
--- a/Database/Eloquent/CastsAttributes.php
+++ b/Database/Eloquent/CastsAttributes.php
@@ -5,6 +5,10 @@
 use Illuminate\Database\Eloquent\Model;
 
 /**
+ * Recommendation:
+ * Prefer symmetric casts (TGet == TSet) so "$a = $a = $b"
+ * remain safe and unsurprising.
+ * 
  * @template TGet
  * @template TSet
  */
@@ -24,10 +28,12 @@ public function get(Model $model, string $key, mixed $value, array $attributes);
     /**
      * Transform the attribute to its underlying model values.
      *
-     * @param  \Illuminate\Database\Eloquent\Model  $model
-     * @param  string  $key
-     * @param  TSet|null  $value
-     * @param  array<string, mixed>  $attributes
+     * Important:
+     * Implementations must tolerate receiving the runtime cast value (TGet) here.
+     * As with object caching, `set()` may receive the value returned by `get()` (TGet).
+     * Implementations should therefore accept both TGet and TSet.
+     *
+     * @param  TGet|TSet|null  $value
      * @return mixed
      */
     public function set(Model $model, string $key, mixed $value, array $attributes);