Download the PHP package kylekatarnls/carbonite without Composer

Carbonite

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

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:

Then you can browse the corresponding Carbonite v1 documentation.

Usage

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).

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:

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).

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:

fake

Carbonite::fake(CarbonInterface $realNow): CarbonInterface

Get fake now instance from real now instance.

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

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

unfreeze

unfreeze(): void

Unfreeze the fake timeline.

jumpTo

jumpTo($moment, float $speed = null): void

Jump to a given moment in the fake timeline keeping the current speed.

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

elapse

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

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

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.

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::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.

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.

addSynchronizer

addSynchronizer(callable $synchronizer): void

Register a callback that will be executed every time mock value is changed.

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 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.

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:

PHPUnit example

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

PHP Attributes

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:

And use it as below:

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:

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

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:

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

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.

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:

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

Random date picking can also be used with a dataset:

Custom attributes

You can create your own time mocking attributes implementing UpInterface:

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