[9.x] Add additional uuid testing helpers

[timacdonald]

This PR adds some testing helpers to the generation of UUIDs via the Str helper.

Currently in order to control UUID creation, you need to do the following...

$uuid = Str::uuid();
Str::createUuidsUsing(fn () => $uuid);

// do stuff...

Str::uuid() === Str::uuid() === $uuid;

// cleanup...

Str::createUuidsNormally();

This locks the helper so that it only returns the one UUID throughout the whole process.

I find myself always having to re-learn how this works and that I have to capture a UUID first or needing to fake a specific UUID generation.

With this PR the following is now possible...

Str::freezeUuids();

// do stuff...

Str::uuid() === Str::uuid() === $uuid;

// cleanup...

Str::createUuidsNormally();

You may also pass a closure to only freeze creation for the duration of the closure...

Str::freezeUuids(function ($uuid) {
    // do stuff...
    Str::uuid() === Str::uuid() === $uuid;
});

Finally, it is also possible to provide a sequence of UUIDs to return.

Str::createUuidsUsingSequence([
    $zeroth = Str::uuid(),
    $first = Str::uuid(),
]);

Str::uuid() === $zeroth;
Str::uuid() === $first;
Str::uuid(); // back to random UUIDs

You may specify the keys if there are only certain instances you wish to sequence....

Str::createUuidsUsingSequence([
    0 => ($zeroth = Str::uuid()),
    3 => ($third = Str::uuid()),
]);

Str::uuid() === $zeroth;
Str::uuid(); // random
Str::uuid(); // random
Str::uuid() === $third;

If you would like to throw an exception when there is no more UUIDs in the array, you pass a closure to control what happens when finding an index that has no specified UUID...

Str::createUuidsUsingSequence([
    $zeroth = Str::uuid(),
    $first = Str::uuid(),
], fn () => throw new Exception('Sequence ended'));

Str::uuid() === $zeroth;
Str::uuid() === $first;
Str::uuid(); // THROWS

This closure is also called when there is a missing key if you specify specific keys in the sequence...

Str::createUuidsUsingSequence([
    0 => Str::uuid(),
    3 => Str::uuid(),
], fn () => throw new Exception('Sequence ended'));

Str::uuid() === $zeroth;
Str::uuid(); // THROWS

[timacdonald]

Please feel free to suggest / improve the naming. Went down the rabbit hole of "recycle" like words, but this felt the best at the end of the day for me.

[driesvints]

Str::createUuidsNormally(); => Str::unfreezeUuids

Str::createUuidsUsingSequence => Str::freezeUuidsAs

[ksassnowski]

Any chance to change the callable type hint to something static analysis better understands? The recent updates to the Collections doc blocks were a really nice QoL improvement and I'd love for more code to be annotated like that :)

/**
 * @param null|callable(): UuidInterface $whenMissing
 */

Same for all the other methods that take a callback as a parameter.

[ksassnowski]

Typo in Squence

[ksassnowski]

Is the second assertion necessary? We're already checking that they're the same instance.

[ksassnowski]

Str::createUuidsNormally(); => Str::unfreezeUuids

Str::createUuidsUsingSequence => Str::freezeUuidsAs

I think I prefer Str::createUuidsUsingSequence since the difference between Str::freezeUuidsAs and Str::freezeUuids isn't immediately obvious to me. Laravel also already uses "sequence" to describe basically the same behavior for model factories.

[timacdonald]

If we dig this, I’ll submit another for Str::random();