[8.x] Added class and method to create cross joined sequences for factories

[thomasowow]

Adds a new CrossJoinSequence class that helps cross joining multiple sequences.

Usage:

User::factory(4)
    ->crossJoinSequence(
        [['first_name' => 'Thomas'], ['first_name' => 'Agent']],
        [['last_name' => 'Anderson'], ['last_name' => 'Smith']],
    )
    ->create();

// Results in

[
    ['first_name' => 'Thomas', 'last_name' => 'Anderson'],
    ['first_name' => 'Thomas', 'last_name' => 'Smith'],
    ['first_name' => 'Agent', 'last_name' => 'Anderson'],
    ['first_name' => 'Agent', 'last_name' => 'Smith'],
]

Current way of achieving this:

->sequence([
    ['first_name' => 'Thomas'],
    ['first_name' => 'Thomas'],
    ['first_name' => 'Agent'],
    ['first_name' => 'Agent']
])
->sequence([
    ['last_name' => 'Anderson'],
    ['last_name' => 'Smith'],
    ['last_name' => 'Anderson'],
    ['last_name' => 'Smith'],
])

More complex example:

new CrossJoinSequence(
    [['a' => 1]],
    [['b' => 1], ['b' => 2]],
    [['c' => 1], ['c' => 2], ['c' => 3]],
);

[
    ['a' => 1, 'b' => 1, 'c' => 1],
    ['a' => 1, 'b' => 1, 'c' => 2],
    ['a' => 1, 'b' => 1, 'c' => 3],
    ['a' => 1, 'b' => 2, 'c' => 1],
    ['a' => 1, 'b' => 2, 'c' => 2],
    ['a' => 1, 'b' => 2, 'c' => 3],
];

[taylorotwell]

Should we name it CrossJoinSequence since it has a clear correlation with Arr::crossJoin? Or does that not make sense?

[Jubeki]

I like the idea. And I think both names MatrixSequence and CossJoinSequence are fine.

What is the expected behaviour of:

new MatrixSequence(
    [['a' => 1]],
    [['b' => 1], ['b' => 2]],
    [['c' => 1], ['a' => 2], ['c' => 3]], // Here is the second element changed.
);

// Later has a higher priority
[
    ['a' => 1, 'b' => 1, 'c' => 1],
    ['a' => 2, 'b' => 1],
    ['a' => 1, 'b' => 1, 'c' => 3],
    ['a' => 1, 'b' => 2, 'c' => 1],
    ['a' => 2, 'b' => 2],
    ['a' => 1, 'b' => 2, 'c' => 3],
];

// Earlier has a higher priority
[
    ['a' => 1, 'b' => 1, 'c' => 1],
    ['a' => 1, 'b' => 1],
    ['a' => 1, 'b' => 1, 'c' => 3],
    ['a' => 1, 'b' => 2, 'c' => 1],
    ['a' => 1, 'b' => 2],
    ['a' => 1, 'b' => 2, 'c' => 3],
];

What do you think about this alternative?

new MatrixSequence([
    'a' => [1],
    'b' => [1, 2],
    'c' => [1, 2, 3],
]);

// Results in
[
    ['a' => 1, 'b' => 1, 'c' => 1],
    ['a' => 1, 'b' => 1, 'c' => 2],
    ['a' => 1, 'b' => 1, 'c' => 3],
    ['a' => 1, 'b' => 2, 'c' => 1],
    ['a' => 1, 'b' => 2, 'c' => 2],
    ['a' => 1, 'b' => 2, 'c' => 3],
];

[taylorotwell]

Marking as draft pending response to feedback.

[thomasowow]

Should we name it CrossJoinSequence since it has a clear correlation with Arr::crossJoin? Or does that not make sense?

CrossJoinSequence was a second choice 👍. However now my Matrix example with Thomas Anderson and Agent Smith seems so unrelated 😿.

new MatrixSequence([
    'a' => [1],
    'b' => [1, 2],
    'c' => [1, 2, 3],
]);

This indeed feels like a nice alternative. It prevents human error and is much easier to read/understand. However for unknown reasons and possibly lack of knowledge about defining a matrix I don't feel that convinced about its signature. Have you seen this somewhere before?

I would at least rename the current class to CrossJoinSequence. Should I also add ->crossJoinSequence as helper method?

[Jubeki]

Sorry @thomasowow I forgot to answer.

I made my example like multiple foreach loops:

foreach ([1] as $a) {
 
    foreach ([1, 2] as $b) {

        foreach ([1, 2, 3] as $c) {

            Model::create([
                'a' => $a,
                'b' => $b,
                'c' => $c,
            ]);

        }

    }

}