[9.x] Allow random string generation to be controlled

[timacdonald]

This PR is the counterpart #42619, however this PR targets the Str::random() function.

This allows developers to intercept and control the random string generation. This is useful in testing where the Str::random() function has been used directly, rather than via a service, and the develop would like to make an assertion against the result of the Str::random() result.

Take a test for the following function...

class Mailable
{
    public function embed($file)
    {
        $name = Str::random();

        $this->message->embed($file, $name);
  
        return "cid:{$name}";
    }
}

Here is a before an after for the potential tests. You will see that the first test doesn't give us as much confidence as the second.

// before...

$cid = $mailable->attach('foo.jpg');

$this->assertStringStarts('cid:', $cid);
$name = Str::after($cid, 'cid:');
$this->assertSame(16, mb_strlen($name));

// after...

Str::createRandomStringsUsing(fn ($length) => "xyz|{$length}");

$cid = $mailable->attach('foo.jpg');

$this->assertSame('cid:xyz|16', $cid);

Str::createRandomStringsNormally();

It also allows developers to specify a sequence of random strings to return when the Str::random() function is called. This works in the same way seen in #42619.

Str::createRandomStringsUsingSequence(['abc', 'xyz']);
    
Str::random(); // "abc"
Str::random(); // "xyz"
Str::random(); // random
Str::random(); // random

You can also specify the array keys so you only control certain calls...

Str::createRandomStringsUsingSequence([
    0 => 'abc',
 // 1 => generate normally
    2 => 'xyz',
 // 3... => generate normally
]);
    
Str::random(); // "abc"
Str::random(); // random
Str::random(); // "xyz"
Str::random(); // random
Str::random(); // random

Finally, you may pass a closure as the second parameter to control what happens when a random string is being generated, but you have not specified it in the sequence.

Str::createRandomStringsUsingSequence([
    0 => 'abc',
    3 => 'xyz',
], fn () => throw new Exception('Sequence ended.'));

Str::random(); // "abc"
Str::uuid(); // THROWS

Notes

• I didn't provide a Str::freeze() style function like the UUIDs, as I don't believe it adds any value for a raw string, when Str::createRandomStringsUsing(fn () => 'xyz') is easily used.