New to Laravel 8 is the ability to quite literally travel in time using the Wormhole class.

Although this class was only recently implemented on version 8, the time travelling concept is already apparent using the Carbon::setTestNow() which is a feature available in Carbon\Carbon package, and is in fact behind this class. Personally, I was able to utilize this feature when I was working on a Loans Management app, which made simulating past and future scenarios (i.e: loans terms and payments) in my tests quite a breeze.

Let's take a look at how we can make time travelling work in Laravel 8.

The InteractsWithTime trait

In Laravel 8, a new trait for testing has been created as a sort of wrapper for the Wormhole class.

The InteractsWithTime trait is within Illuminate\Foundation\Testing\Concerns namespace (be careful when importing and not to confuse it with other traits with the same name but in a different namespace).

So we can just use it in our test classes like so..

namespace Tests\Feature;

use Tests\TestCase;
use Illuminate\Foundation\Testing\Concerns\InteractsWithTime;

class TimeTravellingTest extends TestCase
{
    use InteractsWithTime;
}

Once we've used it on our test class we then gain access to various utility methods..

// Travel 8 days in the future
$this->travel(8)->days(); // Carbon::now() or now() will result to the current date + 8 days

// Travel 10 minutes in the future
$this->travel(10)->minutes(); // Carbon::now() or now() will result to the current time + 8 minutes

// Travel 5 months in the past
$this->travel(-5)->months(); // Carbon::now() or now() will result to the current date - 5 months

We can also travel to a specific date..

$this->travelTo('2019-02-14 12:00:00'); // Carbon::now() or now() will result to '2019-02-14 12:00:00'

Just make sure to ALWAYS GO BACK TO THE PRESENT after doing time travelling to not get stuck in the past or present.

$this->travelBack(); // Carbon::now() or now() will result to the current date

That means we can also time travel, execute a callback and return to the current date consecutively..

// Option 1..
$this->travel(8)->days(function () {
    dd(now()); // This will result to the current date + 8 days
    // After executing this callback, now() will automatically go back to the current date
});

// Option 2..
$this->travelTo('2019-02-14 12:00:00', function () {
    // Carbon::now() or now() will result to '2019-02-14 12:00:00'
    echo 'Happy Valentines Day!';

    // After executing this callback, Carbon::now() or now()
    // will automatically go back to the current date
});

The Wormhole::class

The Wormhole::class is namespaced within Illuminate\Foundation\Testing. Looking at it, its just a single file class that accepts an integer value.

This means we can just new it up like a traditional php class, give it a value and call the methods within it, like so..

$wormhole = new Wormhole(8);
$wormhole->days(); // Carbon::now() or now() will result to the current date + 8 days
Wormhole::back(); // Go back to the present time..

And again we can execute a callback within the Wormhole method..

$wormhole = new Wormhole(8);
$wormhole->days(function () {
    dd(now()); // This will result to the current date + 8 days
    // After executing this callback, now() will automatically go back to the current date
});

This is useful if you wish to do time travelling outside your tests and don't want to use the trait.

And there you have it, time travelling in Laravel is now online.

Hope you learned something from this article. Cheers!