[12.x] Extends AsCollection to map items into objects or other values

[DarkGhostHunter]

What?

Rework of #55377. This extends AsCollection and AsEncryptedCollection to accept a class to map each item into, or a callable as [class, method] or class@method notation, without or without a custom collection class.

For example, I expect the most common to be using the map() static method to set a Class to map each item into, using the base Collection class.

use Illuminate\Database\Eloquent\Casts\AsCollection;
use Illuminate\Support\Fluent;

public function casts()
{
    return [
        'colors' => AsCollection::map(Fluent::class)
    ];
}

// Same as
Collection::make($this->attributes['colors'])->mapInto(Fluent::class);

If the developer sets an array callable, it gets normalized into class@method notation.

use Illuminate\Database\Eloquent\Casts\AsCollection;
use App\ValueObject\Color;

public function casts()
{
    return [
        'colors' => AsCollection::map([Color::class, 'make']),
    ];
}

// Same as
Collection::make($this->attributes['colors'])->map([Color::class, 'make']);

If the developer wants to use a custom Collection class, the using() can be used with a second parameter and either a class or array callable / class@method.

return [
    'colors' => AsCollection::using(CustomCollection::class, [Color::class, 'make']),
];

// Same as
CustomCollection::make($this->attributes['colors'])->map([Color::class, 'make']);

Caution

Because the nature of the casts declaration, there is no support to using a Closure. The developer can use castUsing() directly with a Closure if desired.

This logic is also extended to the AsEncryptedCollection class, which works in the same way.

use Illuminate\Database\Eloquent\Casts\AsEncryptedCollection;
use App\ValueObject\Color;

public function casts()
{
    return [
        'colors' => AsEncryptedCollection::map([Color::class, 'make']), 
    ];
}

[DarkGhostHunter]

Does make more sense lexically to use of() rather than map()?

AsCollection::of(Option::class);

AsCollection::of([Option::class, 'make']);

[shaedrich]

Does make more sense lexically to use of() rather than map()?

While I think, map() might imply something being mapped on the spot rather than just being assigned and mapped later, of() reads like the first parameter is the actual raw iterable/arrayable being passed to the constructor 🤔

But you raise a good point here. Maybe, it could be something along the lines of mapUsing() or withMapping()/withMapper()

[DarkGhostHunter]

Does make more sense lexically to use of() rather than map()?

While I think, map() might imply something being mapped on the spot rather than just being assigned and mapped later, of() reads like the first parameter is the actual raw iterable/arrayable being passed to the constructor 🤔

But you raise a good point here. Maybe, it could be something along the lines of mapUsing() or withMapping()/withMapper()

What about ofItems() (for classes) and ofMap() (for callables)?

[shaedrich]

Does make more sense lexically to use of() rather than map()?

While I think, map() might imply something being mapped on the spot rather than just being assigned and mapped later, of() reads like the first parameter is the actual raw iterable/arrayable being passed to the constructor 🤔
But you raise a good point here. Maybe, it could be something along the lines of mapUsing() or withMapping()/withMapper()

What about ofItems() (for classes) and ofMap() (for callables)?

To me, ofItems() would have pretty much the same implication as of, however, ofMap() might work 👍🏻

[mathieutu]

This is brilliant, thanks @DarkGhostHunter! I need that right now, and was making a small research before working on to for a PR.