Update ArrayCaster to accept objects (of the correct class) alongside arrays that get cast like normal

[code-distortion]

Hi Brendt and co. Thanks for your work on this useful project.

I came across a situation that would be helpful to me if it were altered slightly. I hope it's something that's helpful for others too…

---

Usually, I build DTO objects by passing the desired child DTO objects. But sometimes I need these same DTOs to be hydrated from serialised arrays.

When using the ArrayCaster to cast arrays into objects, the elements to be cast must be arrays (otherwise an error is generated).

This PR lets you also pass in objects of the desired type (no cast needed), as well as the original behaviour (which casts the array). This way, both situations are covered.

class Bar extends DataTransferObject
{
    /** @var Foo[] */
    public array $collectionOfFoo;
}

class Baz extends DataTransferObject
{
    /** @var Foo[] */
    #[CastWith(ArrayCaster::class, itemType: Foo::class)]
    public array $collectionOfFoo;
}

class Foo extends DataTransferObject
{
    public string $name;
}

// normal usage without casting
$bar = new Bar(
    collectionOfFoo: [
        new Foo(name: 'a'),
        new Foo(name: 'b'),
        new Foo(name: 'c'),
    ],
);

// normal usage when casting
$bar = new Baz([
    'collectionOfFoo' => [
        ['name' => 'a'],
        ['name' => 'b'],
        ['name' => 'c'],
    ],
]);

// passing objects when Baz is expecting arrays to cast - would normally generate an error
$bar = new Baz(
    collectionOfFoo: [
        new Foo(name: 'a'),
        new Foo(name: 'b'),
        new Foo(name: 'c'),
    ],
);

// a combination of arrays and objects - would normally generate an error
$bar = new Baz([
    'collectionOfFoo' => [
        ['name' => 'a'],
        new Foo(name: 'b'),
        ['name' => 'c'],
    ],
]);

I split the PR up into two commits; The first containing updated tests to show the error, and the second with the updated code. I can squash them if desired.

[daniser]

How about checking that $data is actually array or object of specified type and otherwise throwing an exception?
Like this (taken out into separate method for simplicity):

private function castArray(mixed $value): array
{
    return array_map([$this, 'makeItem'], $value);
}

private function makeItem(mixed $data): mixed
{
    if ($data instanceof $this->itemType) {
        return $data;
    }

    if (is_array($data)) {
        return new $this->itemType(...$data);
    }

    throw new LogicException('Item data must either match specified type or be array.');
}

[code-distortion]

Hi daniser, I like that refactor. I've incorporated it into the PR.

[brendt]

Looks good! Sorry for the delay in merging.