[12.x] Expressive cast configuration and standardization

src/Illuminate/Database/Eloquent/Casts/ArrayObjectCast.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Illuminate\Database\Eloquent\Casts;
+
+use ArrayObject;
+
+class ArrayObjectCast extends IterableCast
+{
+    /**
+     * Instances the target iterable class.
+     *
+     * @param  \Illuminate\Support\Collection  $data
+     * @return \Illuminate\Database\Eloquent\Casts\ArrayObject
+     */
+    protected function makeIterableObject($data)
+    {
+        return new ($this->using)($data->all(), ArrayObject::ARRAY_AS_PROPS);
+    }
+
+    /**
+     * Serializes the given value to an array format.
+     *
+     * @param  mixed  $model
+     * @param  string  $key
+     * @param  \ArrayObject  $value
+     * @param  array  $attributes
+     * @return array
+     */
+    public function serialize($model, string $key, $value, array $attributes)
+    {
+        return $value->getArrayCopy();
+    }
+}

src/Illuminate/Database/Eloquent/Casts/Concerns/NormalizesArguments.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Illuminate\Database\Eloquent\Casts\Concerns;
+
+use InvalidArgumentException;
+
+trait NormalizesArguments
+{
+    /**
+     * Normalize the arguments received by the Cast Attributes.
+     *
+     * @return void
+     */
+    protected function normalize(): void
+    {
+        if (! $this->using) {
+            $this->using = $this->class;
+        } elseif (! is_a($this->using, $this->class, true)) {
+            throw new InvalidArgumentException("The provided class must extend [$this->class].");
+        }
+
+        $this->withoutObjectCaching = filter_var($this->withoutObjectCaching, FILTER_VALIDATE_BOOL);
+
+        $this->encrypt = filter_var($this->encrypt, FILTER_VALIDATE_BOOL);
+    }
+}

src/Illuminate/Database/Eloquent/Casts/IterableCast.php

@@ -0,0 +1,134 @@
+<?php
+
+namespace Illuminate\Database\Eloquent\Casts;
+
+use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\Crypt;
+use Illuminate\Support\Str;
+
+/**
+ * @template TBaseClass of \Illuminate\Database\Eloquent\Casts\ArrayObject|\Illuminate\Support\Collection
+ *
+ * @extends \Illuminate\Contracts\Database\Eloquent\CastsAttributes<TBaseClass, iterable>
+ */
+class IterableCast implements CastsAttributes
+{
+    use Concerns\NormalizesArguments;
+
+    /**
+     * The base iterable class to cast.
+     *
+     * @var class-string<TBaseClass>
+     */
+    public $class;
+
+    /**
+     * Should the resulting object instance not be cached.
+     *
+     * @var string|null
+     */
+    public $withoutObjectCaching;
+
+    /**
+     * Should encrypt the storable value in the database.
+     *
+     * @var string|null
+     */
+    public $encrypt;
+
+    /**
+     * A custom iterable class to hold the items.
+     *
+     * @var class-string<TBaseClass>|null
+     */
+    public $using;
+
+    /**
+     * The callback in "class@method" notation or class name to map items into.
+     *
+     * @var string|null
+     */
+    public $map;
+
+    /**
+     * Create a new Cast Iterable Attribute instance.
+     *
+     * @param  array{class-string<TBaseClass>, string|null, string|null, class-string<TBaseClass>|null, string|null}  $arguments
+     */
+    public function __construct(array $arguments)
+    {
+        [$this->class, $this->withoutObjectCaching, $this->encrypt, $this->using, $this->map] = $arguments;
+
+        $this->normalize();
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function get(Model $model, string $key, mixed $value, array $attributes)
+    {
+        if (! isset($attributes[$key])) {
+            return;
+        }
+
+        $data = $this->encrypt
+            ? Json::decode(Crypt::decryptString($attributes[$key]))
+            : Json::decode($attributes[$key]);
+
+        if (! is_array($data)) {
+            return;
+        }
+
+        $data = new Collection($data);
+
+        if ($this->map) {
+            $data = $this->mapItems($data) ?? $data;
+        }
+
+        return $this->makeIterableObject($data);
+    }
+
+    /**
+     * Maps the items using a callback, if any.
+     *
+     * @param  \Illuminate\Support\Collection  $data
+     * @return \Illuminate\Support\Collection|null
+     */
+    protected function mapItems($data)
+    {
+        $this->map = Str::parseCallback($this->map);
+
+        return is_callable($this->map)
+            ? $data->map($this->map)
+            : $data->mapInto($this->map[0]);
+    }
+
+    /**
+     * Instances the target iterable class.
+     *
+     * @param  \Illuminate\Support\Collection  $data
+     * @return \Illuminate\Support\Collection|\Illuminate\Support\Fluent
+     */
+    protected function makeIterableObject($data)
+    {
+        return new ($this->using)($data->all());
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function set(Model $model, string $key, mixed $value, array $attributes)
+    {
+        if (! is_null($value)) {
+            return [
+                $key => $this->encrypt
+                    ? Crypt::encryptString(Json::encode($value))
+                    : Json::encode($value),
+            ];
+        }
+
+        return null;
+    }
+}

src/Illuminate/Database/Eloquent/Casts/StringableCast.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace Illuminate\Database\Eloquent\Casts;
+
+use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Support\Facades\Crypt;
+
+/**
+ * @template TBaseClass
+ *
+ * @extends \Illuminate\Contracts\Database\Eloquent\CastsAttributes<TBaseClass, \Stringable|string>
+ */
+class StringableCast implements CastsAttributes
+{
+    use Concerns\NormalizesArguments;
+
+    /**
+     * The base iterable class to cast.
+     *
+     * @var class-string<TBaseClass>
+     */
+    public $class;
+
+    /**
+     * Should the resulting object instance not be cached.
+     *
+     * @var string|null
+     */
+    public $withoutObjectCaching;
+
+    /**
+     * Should encrypt the storable value in the database.
+     *
+     * @var string|null
+     */
+    public $encrypt;
+
+    /**
+     * A custom iterable class to hold the item.
+     *
+     * @var class-string<TBaseClass>|null
+     */
+    public $using;
+
+    /**
+     * Create a new Cast Iterable Attribute instance.
+     *
+     * @param  array{class-string<TBaseClass>, string|null, string|null, class-string<TBaseClass>|null}  $arguments
+     */
+    public function __construct(array $arguments)
+    {
+        [$this->class, $this->withoutObjectCaching, $this->encrypt, $this->using] = $arguments;
+
+        $this->normalize();
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function get(Model $model, string $key, mixed $value, array $attributes)
+    {
+        if (! isset($attributes[$key])) {
+            return;
+        }
+
+        return new ($this->using)($this->encrypt
+            ? Crypt::decryptString($attributes[$key])
+            : $attributes[$key]);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function set(Model $model, string $key, mixed $value, array $attributes)
+    {
+        if (! is_null($value)) {
+            return [
+                $key => $this->encrypt
+                    ? Crypt::encryptString($value)
+                    : $value,
+            ];
+        }
+
+        return null;
+    }
+}

src/Illuminate/Database/Eloquent/Casts/To.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace Illuminate\Database\Eloquent\Casts;
+
+use Illuminate\Support\Collection;
+use Illuminate\Support\Fluent;
+use Illuminate\Support\HtmlString;
+use Illuminate\Support\Stringable;
+use Illuminate\Support\Uri;
+
+class To
+{
+    /**
+     * Create a new cast definition for a Stringable instance.
+     *
+     * @return \Illuminate\Database\Eloquent\Casts\ToString<\Illuminate\Support\Stringable>
+     */
+    public static function stringable()
+    {
+        return new ToString(Stringable::class);
+    }
+
+    /**
+     * Create a new cast definition for an HtmlString instance.
+     *
+     * @return \Illuminate\Database\Eloquent\Casts\ToString<\Illuminate\Support\HtmlString>
+     */
+    public static function htmlString()
+    {
+        return new ToString(HtmlString::class);
+    }
+
+    /**
+     * Create a new cast definition for a Uri instance.
+     *
+     * @return \Illuminate\Database\Eloquent\Casts\ToString<\Illuminate\Support\Uri>
+     */
+    public static function uri()
+    {
+        return new ToString(Uri::class);
+    }
+
+    /**
+     * Create a new cast definition for an ArrayObject.
+     *
+     * @return \Illuminate\Database\Eloquent\Casts\ToIterable<\Illuminate\Database\Eloquent\Casts\ArrayObject>
+     */
+    public static function arrayObject()
+    {
+        return new ToIterable(ArrayObject::class);
+    }
+
+    /**
+     * Create a new cast definition for a Collection.
+     *
+     * @return \Illuminate\Database\Eloquent\Casts\ToIterable<\Illuminate\Support\Collection>
+     */
+    public static function collection()
+    {
+        return new ToIterable(Collection::class);
+    }
+
+    /**
+     * Create a new cast definition for a Fluent instance.
+     *
+     * @return \Illuminate\Database\Eloquent\Casts\ToIterable<\Illuminate\Support\Fluent>
+     */
+    public static function fluent()
+    {
+        return new ToIterable(Fluent::class);
+    }
+}