Added casts AsCollection for hyperf/database. (#7607)

Co-authored-by: 李铭昕 <715557344@qq.com>

Author: adhikjoshi

src/Model/Casts/AsCollection.php

@@ -0,0 +1,95 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * This file is part of Hyperf.
+ *
+ * @link     https://www.hyperf.io
+ * @document https://hyperf.wiki
+ * @contact  group@hyperf.io
+ * @license  https://github.com/hyperf/hyperf/blob/master/LICENSE
+ */
+
+namespace Hyperf\Database\Model\Casts;
+
+use Hyperf\Collection\Collection;
+use Hyperf\Contract\CastsAttributes;
+use Hyperf\Stringable\Str;
+use InvalidArgumentException;
+
+class AsCollection implements CastsAttributes
+{
+    public function __construct(protected ?string $collectionClass = null, protected ?string $parseCallback = null)
+    {
+    }
+
+    public function get($model, string $key, $value, array $attributes)
+    {
+        if (! isset($attributes[$key])) {
+            return null;
+        }
+
+        $data = Json::decode($attributes[$key]);
+
+        $collectionClass = empty($this->collectionClass) ? Collection::class : $this->collectionClass;
+
+        if (! is_a($collectionClass, Collection::class, true)) {
+            throw new InvalidArgumentException('The provided class must extend [' . Collection::class . '].');
+        }
+
+        if (! is_array($data)) {
+            return null;
+        }
+
+        $instance = new $collectionClass($data);
+
+        if (empty($this->parseCallback)) {
+            return $instance;
+        }
+
+        $parseCallback = Str::parseCallback($this->parseCallback);
+        if (is_callable($parseCallback)) {
+            return $instance->map($parseCallback);
+        }
+
+        return $instance->mapInto($parseCallback[0]);
+    }
+
+    public function set($model, $key, $value, $attributes)
+    {
+        return [$key => Json::encode($value)];
+    }
+
+    /**
+     * Specify the type of object each item in the collection should be mapped to.
+     *
+     * @param array{class-string, string}|class-string $map
+     * @return string
+     */
+    public static function of($map)
+    {
+        return static::using('', $map);
+    }
+
+    /**
+     * Specify the collection type for the cast.
+     *
+     * @param class-string $class
+     * @param array{class-string, string}|class-string $map
+     * @return string
+     */
+    public static function using($class, $map = null)
+    {
+        if (
+            is_array($map)
+            && count($map) === 2
+            && is_string($map[0])
+            && is_string($map[1])
+            && is_callable($map)
+        ) {
+            $map = $map[0] . '@' . $map[1];
+        }
+
+        return static::class . ':' . implode(',', [$class, $map]);
+    }
+}

src/Model/Casts/Json.php

@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * This file is part of Hyperf.
+ *
+ * @link     https://www.hyperf.io
+ * @document https://hyperf.wiki
+ * @contact  group@hyperf.io
+ * @license  https://github.com/hyperf/hyperf/blob/master/LICENSE
+ */
+
+namespace Hyperf\Database\Model\Casts;
+
+use JsonException;
+
+class Json
+{
+    /**
+     * The custom JSON encoder.
+     *
+     * @var null|callable
+     */
+    protected static $encoder;
+
+    /**
+     * The custom JSON decoder.
+     *
+     * @var null|callable
+     */
+    protected static $decoder;
+
+    /**
+     * Encode the given value.
+     */
+    public static function encode(mixed $value, int $flags = 0): false|string
+    {
+        return isset(static::$encoder)
+            ? (static::$encoder)($value, $flags)
+            : json_encode($value, $flags);
+    }
+
+    /**
+     * Decode the given value.
+     *
+     * @param mixed $value The JSON string to decode
+     * @param null|bool $associative When true, JSON objects will be returned as associative arrays; when false, as objects
+     * @return mixed The decoded value, or null if the JSON string is invalid or represents null
+     * @throws JsonException When JSON decoding fails (if custom decoder is not set and JSON_THROW_ON_ERROR is used)
+     *
+     * @note This method returns null both when the JSON string is "null" (valid JSON null)
+     *       and when the JSON string is invalid/malformed (decode failure).
+     *       Use json_last_error() after calling this method to distinguish between these cases.
+     */
+    public static function decode(mixed $value, ?bool $associative = true): mixed
+    {
+        if (isset(static::$decoder)) {
+            return (static::$decoder)($value, $associative);
+        }
+
+        $decoded = json_decode($value, $associative);
+
+        // Check for JSON decode errors
+        // Note: json_decode() returns null both for valid JSON null and decode failures.
+        // Use json_last_error() immediately after this call to distinguish between them.
+        if (json_last_error() !== JSON_ERROR_NONE) {
+            // Return null on decode failure, but error can be checked via json_last_error()
+            return null;
+        }
+
+        return $decoded;
+    }
+
+    /**
+     * Encode all values using the given callable.
+     */
+    public static function encodeUsing(?callable $encoder): void
+    {
+        static::$encoder = $encoder;
+    }
+
+    /**
+     * Decode all values using the given callable.
+     */
+    public static function decodeUsing(?callable $decoder): void
+    {
+        static::$decoder = $decoder;
+    }
+}

tests/DatabaseModelCustomCastingTest.php

@@ -21,6 +21,7 @@
 use Hyperf\Database\Exception\InvalidCastException;
 use Hyperf\Database\Model\Casts\ArrayObject;
 use Hyperf\Database\Model\Casts\AsArrayObject;
+use Hyperf\Database\Model\Casts\AsCollection;
 use Hyperf\Database\Model\CastsValue;
 use Hyperf\Database\Model\Model;
 use HyperfTest\Database\Stubs\ContainerStub;
@@ -391,6 +392,27 @@ public function testArrayObjectSerialization()
         $this->assertEquals($data, $unserialized->config->toArray());
         $this->assertEquals(json_encode($data), $unserialized->getAttributes()['config']);
     }
+
+    public function testCastsAsCollection()
+    {
+        $m = new TestModelWithCustomCast();
+        $m->fill([
+            'as_collection' => [['id' => 1, 'name' => 'hyperf'], ['id' => 2, 'name' => 'swoole']],
+            'as_collection2' => [['id' => 3, 'name' => 'hyperf'], ['id' => 4, 'name' => 'swoole']],
+        ]);
+
+        /** @var Collection $collection */
+        $collection = $m->as_collection;
+
+        $this->assertSame(1, $collection->first()['id']);
+        $this->assertSame(2, $collection->last()['id']);
+
+        /** @var Collection $collection */
+        $collection = $m->as_collection2;
+
+        $this->assertSame(3, $collection->first()->id);
+        $this->assertSame(4, $collection->last()->id);
+    }
 }
 
 class TestModelWithCustomCast extends Model
@@ -415,7 +437,28 @@ class TestModelWithCustomCast extends Model
         'value_object_caster_with_caster_instance' => ValueObjectWithCasterInstance::class,
         'cast_using' => CastUsing::class,
         'invalid_caster' => InvalidCaster::class,
+        'as_collection' => AsCollection::class,
+        'as_collection2' => AsCollection::class,
     ];
+
+    public function getCasts(): array
+    {
+        $casts = parent::getCasts();
+        $casts['as_collection2'] = AsCollection::using(Collection::class, [TestModelValue::class, 'from']);
+        return $casts;
+    }
+}
+
+class TestModelValue
+{
+    public function __construct(public int $id, public string $name)
+    {
+    }
+
+    public static function from(array $item)
+    {
+        return new TestModelValue($item['id'], $item['name']);
+    }
 }
 
 class TestModelWithArrayObjectCast extends Model