diff --git a/.github/workflows/coding-style.yml b/.github/workflows/coding-style.yml index a1f7528..6afa3c3 100644 --- a/.github/workflows/coding-style.yml +++ b/.github/workflows/coding-style.yml @@ -11,7 +11,7 @@ jobs: steps: - name: Checkout - uses: actions/checkout@v2 + uses: actions/checkout@v4 - name: Setup PHP uses: shivammathur/setup-php@v2 diff --git a/.github/workflows/psalm.yml b/.github/workflows/psalm.yml index 11a1556..7cb1f4b 100644 --- a/.github/workflows/psalm.yml +++ b/.github/workflows/psalm.yml @@ -11,7 +11,7 @@ jobs: steps: - name: Checkout - uses: actions/checkout@v2 + uses: actions/checkout@v4 - name: Setup PHP uses: shivammathur/setup-php@v2 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 95a3f4c..a17dbe4 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -26,7 +26,7 @@ jobs: steps: - name: Checkout - uses: actions/checkout@v2 + uses: actions/checkout@v4 - name: Setup PHP uses: shivammathur/setup-php@v2 diff --git a/README.md b/README.md index d2c15a4..dc682cb 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ All objects read the current time from a `Clock` implementation. The following i - `SystemClock` returns the system time; it's the default clock - `FixedClock`: returns a pre-configured time - `OffsetClock`: adds an offset to another clock -- `ScaleClock`: makes another clock fast forward by a scale factor +- `ScaleClock`: makes another clock fast-forward by a scale factor These classes belong to the `Brick\DateTime\Clock` namespace. @@ -127,7 +127,8 @@ DefaultClock::reset(); // do not forget to reset the clock to the system clock! There are also useful shortcut methods to use clocks in your tests, inspired by [timecop](https://github.com/travisjeffery/timecop): - `freeze()` freezes time to a specific point in time -- `travel()` travels to a specific point in time, but allows time to continue moving forward from there +- `travelTo()` travels to an `Instant` in time, but allows time to continue moving forward from there +- `travelBy()` travels in time by a `Duration`, which may be forward (positive) or backward (negative) - `scale()` makes time move at a given pace #### Freeze the time to a specific point @@ -153,7 +154,7 @@ DefaultClock::reset(); use Brick\DateTime\DefaultClock; use Brick\DateTime\Instant; -DefaultClock::travel(Instant::of(2000000000)); +DefaultClock::travelTo(Instant::of(2000000000)); $a = Instant::now(); sleep(1); $b = Instant::now(); @@ -169,7 +170,7 @@ DefaultClock::reset(); use Brick\DateTime\DefaultClock; use Brick\DateTime\Instant; -DefaultClock::travel(Instant::of(2000000000)); +DefaultClock::travelTo(Instant::of(2000000000)); DefaultClock::scale(60); // 1 second becomes 60 seconds $a = Instant::now(); sleep(1); @@ -181,7 +182,7 @@ echo $b, PHP_EOL; // 2033-05-18T03:34:20.06632Z DefaultClock::reset(); ``` -As you can see, you can even combine `travel()` and `scale()` methods. +As you can see, you can even combine `travelTo()` and `scale()` methods. Be very careful to **`reset()` the DefaultClock after each of your tests!** If you're using PHPUnit, a good place to do this is in the `tearDown()` method. diff --git a/src/DefaultClock.php b/src/DefaultClock.php index 69b58b5..d40b315 100644 --- a/src/DefaultClock.php +++ b/src/DefaultClock.php @@ -67,8 +67,20 @@ public static function freeze(Instant $instant): void * Travels to a specific point in time, but allows time to continue moving forward from there. * * If the current default clock is frozen, you must `reset()` it first, or the time will stay frozen. + * + * @deprecated use travelTo() instead. */ public static function travel(Instant $instant): void + { + self::travelTo($instant); + } + + /** + * Travels to a specific point in time, but allows time to continue moving forward from there. + * + * If the current default clock is frozen, you must `reset()` it first, or the time will stay frozen. + */ + public static function travelTo(Instant $instant): void { $clock = self::get(); $offset = Duration::between($clock->getTime(), $instant); @@ -76,6 +88,16 @@ public static function travel(Instant $instant): void self::set(new OffsetClock($clock, $offset)); } + /** + * Travels in time by a duration, which may be forward (positive) or backward (negative). + * + * If the current default clock is frozen, you must `reset()` it first, or the time will stay frozen. + */ + public static function travelBy(Duration $duration): void + { + self::set(new OffsetClock(self::get(), $duration)); + } + /** * Makes time move at a given pace. * diff --git a/tests/DefaultClockTest.php b/tests/DefaultClockTest.php index 21565cc..824ca1a 100644 --- a/tests/DefaultClockTest.php +++ b/tests/DefaultClockTest.php @@ -6,6 +6,7 @@ use Brick\DateTime\Clock\FixedClock; use Brick\DateTime\DefaultClock; +use Brick\DateTime\Duration; use Brick\DateTime\Instant; /** @@ -30,11 +31,33 @@ public function testTravel(): void DefaultClock::set($fixedClock); self::assertInstantIs(1000, 0, Instant::now()); - DefaultClock::travel(Instant::of(-1000)); + DefaultClock::travelTo(Instant::of(-1000)); self::assertInstantIs(-1000, 0, Instant::now()); + // TODO: Remove deprecated function + DefaultClock::travel(Instant::of(-2000)); + self::assertInstantIs(-2000, 0, Instant::now()); + + $fixedClock->move(2); + self::assertInstantIs(-1998, 0, Instant::now()); + } + + public function testTravelBy(): void + { + $fixedClock = new FixedClock(Instant::of(1000, 0)); + DefaultClock::set($fixedClock); + self::assertInstantIs(1000, 0, Instant::now()); + + // Travel forward + DefaultClock::travelBy(Duration::ofSeconds(1000)); + self::assertInstantIs(2000, 0, Instant::now()); + + // Travel backward + DefaultClock::travelBy(Duration::ofSeconds(-1000)); + self::assertInstantIs(1000, 0, Instant::now()); + $fixedClock->move(2); - self::assertInstantIs(-998, 0, Instant::now()); + self::assertInstantIs(1002, 0, Instant::now()); } public function testScale(): void