README

Freeze, accelerate, slow down time and many more with Carbon.

You can use it with any PSR-compatible clock system and framework or with any time mocking system.

Carbonite allows you to write unit tests as you would tell a story for times concerns.

Professionally supported nesbot/carbon is now available

Install

composer require --dev kylekatarnls/carbonite

We install Carbonite with --dev because it's designed for tests. You watched enough Sci-Fi movies to know time travel paradoxes are too dangerous for production.

If your config matches the requirements:

PHP >= 8.2
Carbon >= 3.0.2

It will install the latest version of this package, if you need to support older PHP versions (up to 7.2), Carbon 2, or to use annotations over attributes, then install the version 1.x:

composer require --dev kylekatarnls/carbonite:^1

Then you can browse the corresponding Carbonite v1 documentation.

Usage

<?php

use Carbon\Carbon;
use Carbon\Carbonite;

function scanEpoch() {
    switch (Carbon::now()->year) {
        case 1944:
            return 'WW2';
        case 1946:
            return 'War is over';
        case 2255:
            return 'The Discovery is flying!';
    }
}

Carbonite::freeze('1944-05-05');

echo scanEpoch(); // output: WW2

Carbonite::elapse('2 years');

echo scanEpoch(); // output: War is over

Carbonite::jumpTo('2255-01-01 00:00:00');

echo scanEpoch(); // output: The Discovery is flying!

Carbonite::speed(3); // Times passes now thrice as fast
sleep(15); // If 15 seconds passes in the real time

// Then 45 seconds passed in our fake timeline:
echo Carbon::now(); // output: 2255-01-01 00:00:45

You can also use CarbonImmutable, both will be synchronized.

And as Carbonite directly handle any date created with Carbon, it will work just fine for properties like created_at, updated_at or any custom date field in your Laravel models or any framework using Carbon.

Example of Laravel unit test

Example of Laravel feature test

Example of raw PHPUnit test

Available methods

freeze

Carbonite::freeze($toMoment = 'now', float $speed = 0.0): void

Freeze the time to a given moment (now by default).

// Assuming now is 2005-04-01 15:56:23

Carbonite::freeze(); // Freeze our fake timeline on current moment 2005-04-01 15:56:23

// You run a long function, so now is 2005-04-01 15:56:24
echo Carbon::now(); // output: 2005-04-01 15:56:23
// Time is frozen for any relative time in Carbon

Carbonite::freeze('2010-05-04');

echo Carbon::now()->isoFormat('MMMM [the] Do'); // output: May the 4th

This is particularly useful to avoid the small microseconds/seconds gaps that appear randomly in unit tests when you do date-time comparison.

For example:

$now = Carbon::now()->addSecond();

echo (int) Carbon::now()->diffInSeconds($now); // output: 0

// because first Carbon::now() is a few microseconds before the second one,
// so the final diff is a bit less than 1 second (for example 0.999262)

Carbonite::freeze();

$now = Carbon::now()->addSecond();

echo Carbon::now()->diffInSeconds($now); // output: 1

// Time is frozen so the whole thing behaves as if it was instantaneous

The first argument can be a string, a DateTime/DateTimeImmutable, Carbon/CarbonImmutable instance. But it can also be a DateInterval/CarbonInterval (to add to now) or a DatePeriod/CarbonPeriod to jump to the start of this period.

As a second optional parameter you can choose the new time speed after the freeze (0 by default).

Carbonite::freeze('2010-05-04', 2); // Go to 2010-05-04 then make the time pass twice as fast.

See speed() method.

speed

Carbonite::speed(float $speed = null): float

Called without arguments Carbonite::speed() gives you the current speed of the fake timeline (0 if frozen).

With an argument, it will set the speed to the given value:

// Assuming now is 19 October 1977 8pm
Carbonite::freeze();
// Sit in the movie theater
Carbonite::speed(1 / 60); // Now every minute flies away like it's just a second
// 121 minutes later, now is 19 October 1977 10:01pm
// But it's like it's just 8:02:01pm in your timeline
echo Carbon::now()->isoFormat('h:mm:ssa'); // output: 8:02:01pm

// Now it's 19 October 1977 11:00:00pm
Carbonite::jumpTo('19 October 1977 11:00:00pm');
Carbonite::speed(3600); // and it's like every second was an hour
// 4 seconds later, now it's 19 October 1977 11:00:04pm
// it's like it's already 3am the next day
echo Carbon::now()->isoFormat('YYYY-MM-DD h:mm:ssa'); // output: 1977-10-20 3:00:00am

fake

Carbonite::fake(CarbonInterface $realNow): CarbonInterface

Get fake now instance from real now instance.

// Assuming now is 2020-03-14 12:00

Carbonite::freeze('2019-12-23'); // Set fake timeline to last December 23th (midnight)
Carbonite::speed(1); // speed = 1 means each second elapsed in real file, elpase 1 second in the fake timeline

// Then we can see what date and time it would be in the fake time line
// if we were let's say March the 16th in real life:

echo Carbonite::fake(Carbon::parse('2020-03-16 14:00')); // output: 2019-12-25 02:00:00
// Cool it would be Christmas (2am) in our fake timeline

accelerate

accelerate(float $factor): float

Speeds up the time in the fake timeline by the given factor; and returns the new speed. accelerate(float $factor): float

Carbonite::speed(2);

echo Carbonite::accelerate(3); // output: 6

decelerate

decelerate(float $factor): float

Slows down the time in the fake timeline by the given factor; and returns the new speed. decelerate(float $factor): float

Carbonite::speed(5);

echo Carbonite::decelerate(2); // output: 2.5

unfreeze

unfreeze(): void

Unfreeze the fake timeline.

// Now it's 8:00am
Carbonite::freeze();
echo Carbonite::speed(); // output: 0

// Now it's 8:02am
// but time is frozen
echo Carbon::now()->format('g:i'); // output: 8:00

Carbonite::unfreeze();
echo Carbonite::speed(); // output: 1

// Our timeline restart where it was paused
// so now it's 8:03am
echo Carbon::now()->format('g:i'); // output: 8:01

elapse

elapse($duration, float $speed = null): void

Add the given duration to the fake timeline keeping the current speed.

Carbonite::freeze('2000-01-01');
Carbonite::elapse('1 month');
echo Carbon::now()->format('Y-m-d'); // output: 2000-02-01
Carbonite::elapse(CarbonInterval::year());
echo Carbon::now()->format('Y-m-d'); // output: 2001-02-01
Carbonite::elapse(new DateInterval('P1M3D'));
echo Carbon::now()->format('Y-m-d'); // output: 2001-03-04

A second parameter can be passed to change the speed after the jump. By default, speed is not changed.

rewind

rewind($duration, float $speed = null): void

Subtract the given duration to the fake timeline keeping the current speed.

Carbonite::freeze('2000-01-01');
Carbonite::rewind('1 month');
echo Carbon::now()->format('Y-m-d'); // output: 1999-12-01
Carbonite::rewind(CarbonInterval::year());
echo Carbon::now()->format('Y-m-d'); // output: 1998-12-01
Carbonite::rewind(new DateInterval('P1M3D'));
echo Carbon::now()->format('Y-m-d'); // output: 1998-10-29

A second parameter can be passed to change the speed after the jump. By default, speed is not changed.

do

do($moment, callable $action)

Trigger a given $action in a frozen instant $testNow. And restore previous moment and speed once it's done, rather it succeeded or threw an error or an exception.

Returns the value returned by the given $action.

Carbonite::freeze('2000-01-01', 1.5);
Carbonite::do('2020-12-23', static function () {
    echo Carbon::now()->format('Y-m-d H:i:s.u'); // output: 2020-12-23 00:00:00.000000
    usleep(200);
    // Still the same output as time is frozen inside the callback
    echo Carbon::now()->format('Y-m-d H:i:s.u'); // output: 2020-12-23 00:00:00.000000
    echo Carbonite::speed(); // output: 0
});
// Now the speed is 1.5 on 2000-01-01 again
echo Carbon::now()->format('Y-m-d'); // output: 2000-01-01
echo Carbonite::speed(); // output: 1.5

Carbonite::do() is a good way to isolate a test and use a particular date as "now" then be sure to restore the previous state. If there is no previous Carbonite state (if you didn't do any freeze, jump, speed, etc.) then Carbon::now() will just no longer be mocked at all.

doNow

doNow(callable $action)

Trigger a given $action in the frozen current instant. And restore previous speed once it's done, rather it succeeded or threw an error or an exception.

Returns the value returned by the given $action.

// Assuming now is 17 September 2020 8pm
Carbonite::doNow(static function () {
    echo Carbon::now()->format('Y-m-d H:i:s.u'); // output: 2020-09-17 20:00:00.000000
    usleep(200);
    // Still the same output as time is frozen inside the callback
    echo Carbon::now()->format('Y-m-d H:i:s.u'); // output: 2020-09-17 20:00:00.000000
    echo Carbonite::speed(); // output: 0
});
// Now the speed is 1 again
echo Carbonite::speed(); // output: 1

It's actually a shortcut for Carbonite::do('now', callable $action).

Carbonite::doNow() is a good way to isolate a test, stop the time for this test then be sure to restore the previous state. If there is no previous Carbonite state (if you didn't do any freeze, jump, speed, etc.) then Carbon::now() will just no longer be mocked at all.

release

release(): void

Go back to the present and normal speed.

// Assuming now is 2019-05-24
Carbonite::freeze('2000-01-01');
echo Carbon::now()->format('Y-m-d'); // output: 2000-01-01
echo Carbonite::speed(); // output: 0

Carbonite::release();
echo Carbon::now()->format('Y-m-d'); // output: 2019-05-24
echo Carbonite::speed(); // output: 1

addSynchronizer

addSynchronizer(callable $synchronizer): void

The callback receives the default \Carbon\FactoryImmutable as parameter.

removeSynchronizer

removeSynchronizer(callable $synchronizer): void

Remove a callback that has been registered with addSynchronizer().

mock

mock($testNow): void

Set the "real" now moment, it's a mock inception. It means that when you call release() you will no longer go back to present but you will fallback to the mocked now. And the mocked now will also determine the base speed to consider. If this mocked instance is static, then "real" time will be frozen and so the fake timeline too no matter the speed you chose.

This is a very low-level feature used for the internal unit tests of Carbonite and you probably won't need this methods in your own code and tests, you more likely need the freeze() or jumpTo() method.

Example with PSR-20 clock and frameworks such as Symfony

Symfony 7 DatePoint or service using any framework having a clock system that can be mocked can be synchronized with Carbon\FactoryImmutable.

use Carbon\Carbonite;
use Carbon\FactoryImmutable;
use Psr\Clock\ClockInterface;
use Symfony\Component\Clock\DatePoint;

// \Symfony\Component\Clock\Clock is automatically synchronized
// So DatePoint and services linked to it will be mocked

Carbonite::freeze('2000-01-01');

$date = new DatePoint();
echo $date->format('Y-m-d'); // output: 2000-01-01

// Having a service using PSR Clock, you can also test it
// With any Carbonite method by passing Carbonite::getClock()
class MyService
{
    private $clock;

    public function __construct(ClockInterface $clock)
    {
        $this->clock = $clock;
    }
    
    public function getDate()
    {
        return $this->clock->now()->format('Y-m-d');
    }
}

$service = new MyService(Carbonite::getClock());
Carbonite::freeze('2025-12-20');
echo $service->getDate(); // output: 2025-12-20

If you have any other time-mocking system, you can synchronize them with freeze and jumpTo attribute using addSynchronizer in the bootstrap file of you test, for instance if you use Timecop-PHP:

use Carbon\Carbonite;
use Carbon\FactoryImmutable;

Carbonite::addSynchronizer(function (FactoryImmutable $factory) {
    Timecop::travel($factory->now()->timestamp);
});

PHPUnit example

use Carbon\BespinTimeMocking;
use Carbon\Carbonite;
use Carbon\CarbonPeriod;
use PHPUnit\Framework\TestCase;

class MyProjectTest extends TestCase
{
    // Will handle attributes on each method before running it
    // and release the time after each test
    use BespinTimeMocking;

    public function testHolidays()
    {
        $holidays = CarbonPeriod::create('2019-12-23', '2020-01-06', CarbonPeriod::EXCLUDE_END_DATE);
        Carbonite::jumpTo('2019-12-22');

        $this->assertFalse($holidays->isStarted());

        Carbonite::elapse('1 day');

        $this->assertTrue($holidays->isInProgress());

        Carbonite::jumpTo('2020-01-05 22:00');

        $this->assertFalse($holidays->isEnded());

        Carbonite::elapse('2 hours');

        $this->assertTrue($holidays->isEnded());

        Carbonite::rewind('1 microsecond');

        $this->assertFalse($holidays->isEnded());
    }
}

PHP 8 attributes can also be used for convenience. Enable it using BespinTimeMocking trait or Bespin::up() on a given test suite:

PHP Attributes

use Carbon\BespinTimeMocking;
use Carbon\Carbon;
use Carbon\Carbonite;
use Carbon\Carbonite\Attribute\Freeze;
use Carbon\Carbonite\Attribute\JumpTo;
use Carbon\Carbonite\Attribute\Speed;
use PHPUnit\Framework\TestCase;

class PHP8Test extends TestCase
{
    // Will handle attributes on each method before running it
    // and release the time after each test
    use BespinTimeMocking;

    #[Freeze("2019-12-25")]
    public function testChristmas()
    {
        // Here we are the 2019-12-25, time is frozen.
        self::assertSame('12-25', Carbon::now()->format('m-d'));
        self::assertSame(0.0, Carbonite::speed());
    }

    #[JumpTo("2021-01-01")]
    public function testJanuaryFirst()
    {
        // Here we are the 2021-01-01, but time is NOT frozen.
        self::assertSame('01-01', Carbon::now()->format('m-d'));
        self::assertSame(1.0, Carbonite::speed());
    }

    #[Speed(10)]
    public function testSpeed()
    {
        // Here we start from the real date-time, but during
        // the test, time elapse 10 times faster.
        self::assertSame(10.0, Carbonite::speed());
    }

    #[Release]
    public function testRelease()
    {
        // If no attributes have been used, Bespin::up() will use:
        // Carbonite::freeze('now')
        // But you can still use #[Release] to get a test with
        // real time
    }
}

See Carbonite v1 documentation for annotations support.

`fakeAsync()` for PHP

If you're familiar with fakeAsync() and tick() of Angular testing tools, then you can get the same syntax in your PHP tests using:

use Carbon\Carbonite;

function fakeAsync(callable $fn): void {
    Carbonite::freeze();
    $fn();
    Carbonite::release();
}

function tick(int $milliseconds): void {
    Carbonite::elapse("$milliseconds milliseconds");
}

And use it as below:

use Carbon\Carbon;

fakeAsync(function () {
    $now = Carbon::now();
    tick(2000);

    echo $now->diffForHumans(); // output: 2 seconds ago
});

Data Provider

When applying use BespinTimeMocking; on a PHPUnit TestCase and using #[DataProvider], @dataProvider, #[TestWith] or @testWith you can insert Freeze, JumpTo, Release or Speed, they will be used to configure time mocking before starting the test then removed from the passed parameters:

#[TestWith([new Freeze('2024-05-25'), '2024-05-24'])]
#[TestWith([new Freeze('2023-01-01'), '2022-12-31'])]
public function testYesterday(string $date): void
{
    self::assertSame($date, Carbon::yesterday()->format('Y-m-d'));
}

#[DataProvider('getDataSet')]
public function testNow(string $date): void
{
    self::assertSame($date, Carbon::now()->format('Y-m-d'));
}

public static function getDataSet(): array
{
    return [
        ['2024-05-25', new Freeze('2024-05-25')],
        ['2023-12-14', new Freeze('2024-05-25')],
    ];
}

You can combine it with periods, for instance to test that something works every day of the month:

#[DataProvider('getDataSet')]
public function testDataProvider(): void
{
    $now = CarbonImmutable::now();
    self::assertSame($now->day, $now->addMonth()->day);
}

public static function getDataSet(): iterable
{
    yield from Carbon::parse('2023-01-01')
        ->daysUntil('2023-01-31')
        ->map(static fn ($date) => [new Freeze($date)]);
}

The test above will be for each day of January and will fail on 29th, 30th and 31st because it overflows from February to March.

The DataGroup helper allows you to build data providers with multiple sets using the same time mock:

#[DataProvider('getDataSet')]
public function testDataProvider(string $date, int $days): void
{
    self::assertSame(
        $date,
        Carbon::now()->addDays($days)->format('Y-m-d')
    );
}

public static function getDataSet(): iterable
{
    yield from DataGroup::for(new Freeze('2024-05-25'), [
        ['2024-05-27', 2],
        ['2024-06-01', 7],
        ['2024-06-08', 14],
    ]);

    yield from DataGroup::for(new Freeze('2023-12-30'), [
        ['2023-12-31', 1],
        ['2024-01-06', 7],
        ['2024-02-03', 35],
    ]);

    yield from DataGroup::matrix([
        new Freeze('2024-05-25'),
        new Freeze('2023-12-14'),
    ], [
        'a' => ['2024-05-25'],
        'bb' => ['2023-12-14'],
    ]);
}

And also to build a matrix to test each time config with each set:

#[DataProvider('getDataSet')]
public function testDataProvider(string $text): void
{
    // This test will be run 4 times:
    // - With current time mocked to 2024-05-25 and $text = "abc"
    // - With current time mocked to 2024-05-25 and $text = "def"
    // - With current time mocked to 2023-12-14 and $text = "abc"
    // - With current time mocked to 2023-12-14 and $text = "def"
}

public static function getDataSet(): DataGroup
{
    return DataGroup::matrix([
        new Freeze('2024-05-25'),
        new Freeze('2023-12-14'),
    ], [
        ['abc'],
        ['def'],
    ]);
}

A default DataGroup::withVariousDates() is provided to mock time a various moment that are known to trigger edge-cases such as end of day, end of February, etc.

#[DataProvider('getDataSet')]
public function testDataProvider(): void
{
}

public static function getDataSet(): DataGroup
{
    return DataGroup::withVariousDates();
}

It can be crossed with a dataset (so to test each set with each date), timezone to be used can be changed (with a single one or a list of multiple ones so to test each of them) and extra dates and times can be added:

#[DataProvider('getDataSet')]
public function testDataProvider(string $text, int $number): void
{
}

public static function getDataSet(): DataGroup
{
    return DataGroup::withVariousDates(
        [
            ['abc', 4],
            ['def', 6],
        ],
        ['America/Chicago', 'Pacific/Auckland'],
        ['2024-12-25', '2024-12-26'],
        ['12:00', '02:30']
    );
}

You can also pick date to mock time randomly between 2 bounds:

#[DataProvider('getDataSet')]
public function testDataProvider(): void
{
    // Will run 5 times, each time with now randomly picked between
    // 2024-06-01 00:00 and 2024-09-20 00:00
    // For instance: 2024-07-16 22:45:12.251637
}

public static function getDataSet(): DataGroup
{
    return DataGroup::between('2024-06-01', '2024-09-20', 5);
}

Random date picking can also be used with a dataset:

#[DataProvider('getDataSet')]
public function testDataProvider(string $letter): void
{
    // Will run with $letter = 'a' and now picked randomly
    // Will run with $letter = 'b' and now picked randomly
    // Will run with $letter = 'c' and now picked randomly
}

public static function getDataSet(): DataGroup
{
    return DataGroup::between('2024-06-01', '2024-09-20', ['a', 'b', 'c']);
}

Custom attributes

You can create your own time mocking attributes implementing UpInterface:

use Carbon\Carbonite;
use Carbon\Carbonite\Attribute\UpInterface;

#[\Attribute]
final class AtUserCreation implements UpInterface
{
    public function __construct(private string $username) {}

    public function up() : void
    {
        // Let's assume as an example that the code below is how to get
        // user creation as a Carbon or DateTime from a username in your app.
        $creationDate = User::where('Name', $username)->first()->created_at;
        Carbonite::freeze($creationDate);
    }
}

Then you can use the following attribute like this in your test:

#[AtUserCreation('Robin')]
public function testUserAge(): void
{
    Carbon::sleep(3);
    $ageInSeconds = (int) User::where('Name', $username)->first()->created_at->diffInSeconds();

    self::assertSame(3, $ageInSeconds);
}

kylekatarnls / carbonite

Maintainers

Details

README

Install

Usage

Available methods

freeze

speed

fake

accelerate

decelerate

unfreeze

jumpTo

elapse

rewind

do

doNow

release

addSynchronizer

removeSynchronizer

mock

Example with PSR-20 clock and frameworks such as Symfony

PHPUnit example

PHP Attributes

`fakeAsync()` for PHP

Data Provider

Custom attributes

kylekatarnls / carbonite

Maintainers

Details

README

Install

Usage

Available methods

freeze

speed

fake

accelerate

decelerate

unfreeze

jumpTo

elapse

rewind

do

doNow

release

addSynchronizer

removeSynchronizer

mock

Example with PSR-20 clock and frameworks such as Symfony

PHPUnit example

PHP Attributes

fakeAsync() for PHP

Data Provider

Custom attributes

`fakeAsync()` for PHP