Add DefaultClock::travelBy(Duration), add travelTo to replace travel

.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

.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

.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

.gitignore

@@ -1,3 +1,4 @@
+/.idea
 /vendor
 /composer.lock
 /.phpunit.cache

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.
 

src/DefaultClock.php

@@ -67,15 +67,37 @@ 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);
 
         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.
      *

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 testTravelForward(): 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