[10.x] Siesta

[timacdonald]

This PR proposes a new utility class that wraps up the native sleep and usleep PHP functions into a "fakeable" and testable class.

The motivation behind this PR is to improve testing of sleeping and while also removing the duration of the sleep from the test itself while maintaining confidence in the test.

Often when an application interacts with a 3rd party library it will need to retry interactions after pausing execution.

An example of this may be a HTTP endpoint. The API may be down for a brief moment. Instead of failing, the application may use a "retry":

Http::retry(3, 500)->post(/* ... */);

When attempting to test the failure / retry logic, a test would take a minimum of 1.5 seconds.

More generally, when using the retry helper, this is also a (minor) annoyance.

return retry(5, function () {
    // Attempt 5 times while resting 100ms between attempts...
}, 100);

To address this, we now use the Siesta helper in a few places throughout the Framework. The helper may the be "faked" in tests and some basic assertions may also be made.

API

Fluent API

// minutes...

Siesta::for(3)->minutes();

Siesta::for(1)->minute();

// seconds...

Siesta::for(3)->seconds();

Siesta::for(1)->second();

// milliseconds...

Siesta::for(30000)->milliseconds();

Siesta::for(1)->millisecond();

// microseconds...

Siesta::for(30000)->microseconds();

Siesta::for(1)->microsecond();

Composed durations

Siesta::for(3)->minutes()
      ->and(5)->seconds()
      ->and(9)->milliseconds();

Siesta until a given time

Siesta::until(now()->addMinute());

1:1 replacement API

// usleep(30000);

Siesta::usleep(30000);

// sleep(2);

Siesta::sleep(2);

// time_sleep_until(1682641623)

Siesta::until(1682641623);

Testing

As mentioned, the motivation here is to improve testing. If an application simply wants tests to not "sleep", then the following could be added to any test that uses Siesta:

protected function setUp(): void
{
    parent::setUp();

    Siesta::fake();
}

It is also possible to make assertions:

public function testItSendsWebhookSuccessfluly()
{
    Siesta::fake();
    Http::fake(['https://laravel.com' => Http::response('', 200)]);

    Webhook::send('https://laravel.com');

    Siesta::assertInsomniac(); // too much?! 😅
}

public function testItRetriesWithBackoffForFailedWebhooks()
{
    $attempts = 0;
    Siesta::fake();
    Http::fake(['https://laravel.com' => function () use (&$attempts) {
        $attempts++;

        return $attempts++ === 3
            ? Http::response('', 200)
            : Http::response('', 500);
    }]);


    Webhook::send('https://laravel.com');

    $this->assertSame(3, $attempts);
    Siesta::assertSleptTimes(3);
    Siesta::assertSequence([
        Siesta::for(100)->milliseconds(),
        Siesta::for(200)->milliseconds(),
        Siesta::for(300)->milliseconds(),
    ]);
}

// Full API

Siesta::assertSlept(fn (CarbonInterval $duration): bool => /* ... */);

Siesta::assertSlept(fn (CarbonInterval $duration): bool => /* ... */, $times = 5);

// asserts the number of times Siesta was used...
Siesta::assertSleptTimes(5);

// asserts that even if Siesta was used that zero time was spent sleeping...
Siesta::assertInsomniac();

Now any call to sleep via Siesta will not actually pause execution throughout the testsuite.

Naming alternatives

If the framework doesn't jive with "Siesta":

• Sleep
• Pause
• Rest
• Something else?

…but lowkey “Siesta” is the best option 🙉

Use of Siesta within the Framework

I feel that the places I've used Siesta throughout the framework make sense. If we feel any of them don't make sense, I'm happy to remove any.

📌 Notes

The native time_sleep_until function will throw an error if the time has already passed; we just do not sleep. When testing, you would need to assert that it slept for zero seconds.

---

The native sleep function will cast a float to an int. Our implementation does not do this:

sleep(1.5); // only sleeps for 1 second

Siesta::for(1.5)->seconds(); // sleeps for 1 second and 500 milliseconds

Siesta::sleep(1.5); // sleeps for 1 second and 500 milliseconds

---

The native usleep function may not support values larger than 1000000. Our implementation fixes this by using a combination of sleep and usleep.

---

Although PHP does have the ability to sleep for nanoseconds, via the native time_nanosleep function, I didn't feel the need to add an affordance to this.

An implementation would be possible, however I'm not sure it is worth it. If you need something that fine-grained, even our PHP code in-between things is probably going to be problematic.

---

Warning: Time is hard. We do execute some PHP between sleeps, so this will never be perfect, although computers also aren't great at time, so it is already unreliable to some degree. YOLO.

[thefelipevega]

Thoughts on Rest for the name?

[LasseRafn]

I think there is a typo in the last example regarding float and rounding, it says that Siesta sleeps for 90 seconds when passing 1.5? 👀 or am I misunderstanding something. But I’m loving this idea!

sleep(1.5); // only sleeps for 1 second

Siesta::for(1.5)->seconds(); // sleeps for 90 seconds

Siesta::sleep(1.5); // sleeps for 90 seconds

[timacdonald]

@LasseRafn corrected. thank you! Time is hard. Math is hard. Math + Time = 🫠

[axlon]

Would personally prefer a name like Sleep, Wait or Rest. Otherwise love this!

[antonkomarev]

Rest might add confusion because of the REST.

[fourstacks]

Love it! Would humbly submit Snooze as a name. Does what it says on the tin and sounds slightly weirder every time you say it

[timacdonald]

@fourstacks I actually used Snooze when I first conceptualised this - but realised it conflicted with https://github.com/thomasjohnkane/snooze

[Sammyjo20]

I absolutely love this 😆 I have a few tests for my own that last 5-10 seconds because of a sleep, would be cool to fake it!

[Sammyjo20]

I also agree with @fourstacks I do like Snooze too 🤔

Or even being boring and having Sleep::until() as to not confuse devs too much

[dsazup]

Done this a few times by just creating sleep method and using $this->sleep(5) and mocking that in tests. So really love this idea. But would prefer Sleep::for(5) as the name (or Wait::for(5)). Siesta is a great name, but a bit too fancy imho. 😄

[timacdonald]

11th hour realisation which I can’t implement right now: we need…

Siesta::assertSlept(Siesta::for(1)->second());

that doesn’t care about order.

[nunomaduro]

Because of the complexity of the Siest class, I would rather not introduce it into the existing src code, as is very risky and it could potentially disrupt the current behavior, even if it appears otherwise.

[timacdonald]

I think at a bare minimum we want it used in the retry helper. After that, in order of what I would want to optionally see:

• Timebox
• Cache stuff

[buismaarten]

I actually like Sleep::for(1)->second() more than Siesta::for(1)->second().

[timacdonald]

Draft as there are some final tweaks I wanna make.

[bert-w]

I prefer just a regular Sleep as the class name, that makes the most sense to me. Also a rename for assertInsomniac would be fitting.

I don't think I'll ever need this class myself though since I can't think of many practical usecases where I need complex sleep behaviour like in this Siesta class. But for internal/testing usecases it might be handy.

[innocenzi]

I don't think I'll ever need this class myself though since I can't think of many practical usecases where I need complex sleep behaviour like in this Siesta class. But for internal/testing usecases it might be handy.

Definitely has potential use cases for third-party integrations and retry. Specifically, the ability to remove the sleep calls during testing would be great.

[Sammyjo20]

@timacdonald There are quite a number of people who prefer “sleep” over “siesta”. Have you considered the name change? It’s a great name but I understand people’s feelings against it.

Edit: Perhaps a poll in the PR or maybe a Twitter poll?

[timacdonald]

@Sammyjo20 naming considerations and alternatives are part of the description. I lowkey like "Siesta". If Taylor decides this feature is suitable for the framework and wants a name change, I'm happy to change it. No need for polls.

[henzeb]

I'd suggest the assertSleptTimes to be assertTimesSlept. Otherwise, love it.

[timacdonald]

If we are keen for this feature, but are not keen on the __destruct magic, I believe I can maintain the same API without leaning on destruction.

Won't implement it until we are sure we want the feature in the framework.

[bert-w]

This can be simplified imo. In one of my projects I have added a helper that combines sleep() and usleep() so i can do fractional sleep easily like so:

function my_sleep($microseconds)
    {
        if ($microseconds <= 0) {
            return;
        }
        if ($usleep = $microseconds % 1000000) {
            usleep($usleep);
        }

        if ($sleep = ($microseconds - $usleep) / 1000000) {
            sleep($sleep);
        }
    }

Then you can call that method (maybe even expose it as public/static since it is very handy) and be done with it. The CarbonInterval $duration property in your class is probably too complex since you can just use a microseconds integer instead. We are mostly talking about times in that neighborhood anyway (maybe up to a few seconds).

[NickSdot]

Copying this over from Twitter. My bad for not keeping it in the PR.🙏

Context:
#46904 (review)

https://twitter.com/timacdonald87/status/1653151918863302656?s=46&t=zY_3ch9pBvnnjyXjsgTbnQ

I see where you are coming from, @timacdonald

I still believe it’s possible to use it wrong.

Actually, imho, there should/must be some enforcement of calling minutes() or whatever else calls pullPending() before the method and() can be chained again.

Let’s say I do something ‚weird‘ like:

$siesta = Siesta::for(2)->minutes();

if($bigWhateverAmountHereOne) {
 // and(2)
}

if($bigWhateverAmountHereTwo) {
 // and(5)
}

$siesta->minutes()

Theoretically, because both if(//) can be true, I can mess it up. And I believe this shouldn’t be possible.

There should be a check in and() that there is no pending values, and otherwise throw an error.

Disclaimer: on my phone and not able to actually playing around with it. So it’s all theoretical. 🙏

Appreciate your work, Tim! ❤️

[Angel5a]

@NickSdot, I think, there is no need on exceptions. Just add every add() to accumulator should be ok. Siesta class (or Sleep if smb wish), shouldn't be responsible on watching for errors in your code.

[NickSdot]

@NickSdot, I think, there is no need on exceptions. Just add every add() to accumulator should be ok.

@Angel5a at first I was thinking that too, as my initial note on it shows. But it allows to accumulate time without defining which unit the time has.

Siesta class (or Sleep if smb wish), shouldn't be responsible on watching for errors in your code.

Whether or not the class should be responsible to allow or disallow me to write wrong code is a good question -- I tend to the latter, but also understand why you see it different. Tim and team will have their take on it, I guess.

[taylorotwell]

Renamed to Sleep. Added assertNeverSlept as alias for assertInsomniac (but kept insomniac method since it's a nice Easter egg). 🥚

[timacdonald]

Appreciate all the feedback from everyone ❤️. I hope the feature comes in handy.

Also: On the day of release I'll be all like...

use Illuminate\Support\Sleep as Siesta;

😎