feat: introduce distribute() method

[nikophil]

I wanted since a lot of time improve a little bit the API around collections, to facilitate complex cases with one-to-many, mainly to be used with sequences.

here is one new method:

• FactoryCollection::distribute($field, $values): it can be use to distribute the values to all factories inside the collection for a given field:

$categories = CatagoryFactory::createSequence(2, [['name' => 'category 1'], ['name' => 'category 2']]);
$contacts = ContactFactory::new()->many(2)->forEach('category', $categories)->create();

[kbond]

This looks cool. Admittedly, I find it hard to reason about. I'd love to see some concrete examples in the docs to help visualize the end result (one with relations).

[kbond]

Do you think this is common enough to warrant a dedicated static method?

[nikophil]

nope you're right, I'll remove it

[nikophil]

This looks cool.

nice :)

Admittedly, I find it hard to reason about.

yeah, this might be for some edge cases only

I'd love to see some concrete examples in the docs to help visualize the end result (one with relations).

I'll add concrete examples in the docs. I have plenty of cases where this could be useful in the project I'm working on

I'm still looking for better names for the first one 🤔
maybe spread('field', $values) ?

[kbond]

Oo I do like spread. Could mapEach be combined into forEach? spread(string, array|callable)?

[nikophil]

Oo I do like spread

let's go for spread() then :)

Could mapEach be combined into forEach? spread(string, array|callable)?

not sure what you mean:

• in the current forEach() (which I will rename to spread()), we take a field, and the second parameter is an array which is spread in each element of the collection for the given field.
• in mapEach(), we give a callable which will be called on each element of the collection, but we will pass to the callable a different parameter for each element.

[kbond]

My bad, I misread the signature for mapEach. Does it make sense for this one to include "spread" in the name?

[nikophil]

Not sure... we actually "spread" the values to a callable which will be used in a array_map()

I'm wondering if mapForEachValue() would be better?

[kbond]

Got it.

I'm wondering if mapForEachValue() would be better?

Feels like a bit of a mouthful. Let's keep this one as is

[smnandre]

I love the feature (and we needed exactly this on the work project :))

But yes we can do better for the API :)

$contacts = ContactFactory::new()->many(2)->forEach('category', $categories)->create();

The many->forEach(singular, plural)->create() really is not a good friend of my brain

You suggest to use spread then

which is spread in each element of the collection for the given field.

... and i'm not sure it really is perfect either...

Iwould suggest .... (and taken from the PR comment)

distribute()

[nikophil]

hi @smnandre

thanks for this proposal, distribute() would be a perfect naming indeed 👍

[nikophil]

ok, I've only kept the distribute() method in this PR. I'll create another PR for the other method, with which I'm not 100% happy.

I've added some docs for the distrubute() method @kbond @smnandre does that make sense to you?

[kbond]

Good call to update this PR to just distribute().

[smnandre]

This is perfect for a start.

I wonder if we could allow some options there in the future

A couple of ideas:

Cycle

categories : A, B
posts: P1, P2, P3

P1: A
P2: B
P3: A

All

categories : A, B, C
posts: P1, P2

P1: A, C
P2: B

Ignore missing

categories : A, B
posts: P1, P2, P3

P1: A
P2: B
P3: 

[nikophil]

yes, we can totally pass a third parameter $strategy or something like that! Let's see what kind of use case will be needed