★ A package to control the flow of time

Imagine you're building that your app can notify your user, but you don't want to send more than one notification in a timeframe of five seconds. How are you going to test the time aspect? Do you have to create a test that takes five minutes?

Luckily the answer is "no". If you're using the popular Carbon library, you can set the value that the library considers "now". You can do this using Carbon::setTestNow($now) where $now is a instance of Carbon\Carbon.

In the test suites of my projects and package I often added code like this:

protected function setNow(string $time, $format = 'Y-m-d H:i:s')
{
    $now = Carbon::createFromFormat($format, $time);

    Carbon::setTestNow($now);
}

protected function progressSeconds(int $seconds)
{
    $newNow = now()->addSeconds($seconds);

    Carbon::setTestNow($newNow);
}

protected function progressMinutes(int $minutes)
{
    $newNow = now()->addMinutes($minutes);

    Carbon::setTestNow($newNow);
}

protected function progressHours(int $hours)
{
    $newNow = now()->addHours($hours);

    Carbon::setTestNow($newNow);
}

Because I was tired of coding this over and over again, I decided to a new small, handy package called spatie/test-time. Using the package, you can freeze the time with:

// time will not progress anymore

TestTime::freeze();

Alternatively, you can pass in a carbon instance that will be used as the current time.

TestTime::freeze($carbonInstance);

There's also no need to add separate functions like progressSeconds, progressMinutes and so on... You can progress the time with any of the carbon functions starting with add or sub.

TestTime::addMinute();

TestTime::subHours(5);

// you can also chain calls
TestTime::addMonth(3)->addYear();

Here's an example where I used it in a real world project:

Dogfooding myself with the newly released spatie/test-time package ⏳https://t.co/L0clvjrgRI#php #testing pic.twitter.com/xkDFaXpTsf

— Freek Van der Herten ? (@freekmurze ) June 12, 2019

Happy tinkering with the time!