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

.gitignore

@@ -8,3 +8,4 @@
 /tools/ecs/*
 !/tools/ecs/composer.json
 !/tools/ecs/ecs.php
+/.idea

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,9 @@ 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
+- `travel()` travels to an `Instant` in time, but allows time to continue moving forward from there
+- `travelForward()` travels forward by a `Duration`
+- `travelBackward()` travels backward by a `Duration`
 - `scale()` makes time move at a given pace
 
 #### Freeze the time to a specific point

src/DefaultClock.php

@@ -76,6 +76,26 @@ public static function travel(Instant $instant): void
         self::set(new OffsetClock($clock, $offset));
     }
 
+    /**
+     * Travels forward by a duration, 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 travelForward(Duration $duration): void
+    {
+        self::set(new OffsetClock(self::get(), $duration->abs()));
+    }
+
+    /**
+     * Travels backward by a duration, 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 travelBackward(Duration $duration): void
+    {
+        self::set(new OffsetClock(self::get(), $duration->abs()->negated()));
+    }
+
     /**
      * 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;
 
 /**
@@ -37,6 +38,40 @@ public function testTravel(): void
         self::assertInstantIs(-998, 0, Instant::now());
     }
 
+    public function testTravelForward(): void
+    {
+        $fixedClock = new FixedClock(Instant::of(1000, 0));
+        DefaultClock::set($fixedClock);
+        self::assertInstantIs(1000, 0, Instant::now());
+
+        DefaultClock::travelForward(Duration::ofSeconds(1000));
+        self::assertInstantIs(2000, 0, Instant::now());
+
+        // Absolute value of the duration
+        DefaultClock::travelForward(Duration::ofSeconds(-1000));
+        self::assertInstantIs(3000, 0, Instant::now());
+
+        $fixedClock->move(2);
+        self::assertInstantIs(3002, 0, Instant::now());
+    }
+
+    public function testTravelBackward(): void
+    {
+        $fixedClock = new FixedClock(Instant::of(1000, 0));
+        DefaultClock::set($fixedClock);
+        self::assertInstantIs(1000, 0, Instant::now());
+
+        DefaultClock::travelBackward(Duration::ofSeconds(1000));
+        self::assertInstantIs(0, 0, Instant::now());
+
+        // Absolute value of duration
+        DefaultClock::travelBackward(Duration::ofSeconds(-1000));
+        self::assertInstantIs(-1000, 0, Instant::now());
+
+        $fixedClock->move(2);
+        self::assertInstantIs(-998, 0, Instant::now());
+    }
+
     public function testScale(): void
     {
         $fixedClock = new FixedClock(Instant::of(1000, 0));