The InteractsWithTime Trait

A utility trait for time and delay calculations used across caches, queues, and console components in Laravel.

What is InteractsWithTime?

Illuminate\Support\InteractsWithTime is a trait that centralises time and delay calculations. Over 40 classes in the Laravel framework use it — including every cache store, the rate limiter, queue console commands, the database connection, and console task components.

Source: src/Illuminate/Support/InteractsWithTime.php. All methods are protected, so they are intended to be called from within the class that uses the trait.

Where it is used in the framework

Class	Purpose
Cache\ArrayStore / DatabaseStore / etc.	TTL (expiry) calculation
Cache\RateLimiter	Rate-limit reset timestamps
Queue\Console\RestartCommand	Worker restart timestamp
Database\Connection	Query elapsed time measurement
Console\View\Components\Task	Command task runtime display
Redis\Limiters\DurationLimiterBuilder	Redis rate-limit window calculation

Method reference

secondsUntil() — remaining seconds

Returns the number of seconds until the given delay. Accepts a DateTimeInterface, a DateInterval, or an integer (seconds). Returns 0 for past dates.

use Illuminate\Support\InteractsWithTime;

class MyService
{
    use InteractsWithTime;

    public function timeUntilExpiry(\DateTime $expiresAt): int
    {
        return $this->secondsUntil($expiresAt);
    }
}

$this->secondsUntil(now()->addMinutes(5)); // 300
$this->secondsUntil(now()->subMinutes(5)); // 0  (past → never negative)
$this->secondsUntil(60);                   // 60 (integer is used as-is)

availableAt() — available-at UNIX timestamp

Returns the UNIX timestamp when the delay will have elapsed. Used by caches for expiry times and by queues for delayed dispatch.

$this->availableAt(60);                            // now + 60 s
$this->availableAt(new \DateTime('2026-12-31'));    // specific date
$this->availableAt(new \DateInterval('PT5M'));      // now + 5 min
$this->availableAt();                              // now (default 0 delay)

parseDateInterval() — normalise a delay value

Converts a DateInterval into a Carbon instance (current time + interval). Returns DateTimeInterface and integer values unchanged.

$this->parseDateInterval(new \DateInterval('P1D')); // Carbon: tomorrow
$this->parseDateInterval(now()->addHour());         // DateTimeInterface unchanged
$this->parseDateInterval(3600);                     // 3600 unchanged

secondsUntil() and availableAt() call this method internally.

currentTime() — current UNIX timestamp

A thin wrapper around Carbon::now()->getTimestamp(). Used as the reference point inside secondsUntil().

$now = $this->currentTime(); // int

runTimeForHumans() — human-readable elapsed time

Formats the difference between two microtime(true) values as a readable string. Under 1 000 ms it returns "42.15ms"; at 1 000 ms and above it uses CarbonInterval’s short forHumans() format ("1s 234ms").

$start = microtime(true);

// ... work ...

echo $this->runTimeForHumans($start);        // e.g. "142.30ms"
echo $this->runTimeForHumans($start, $end);  // pre-recorded interval

Using the trait in packages

Accepting flexible TTL types

Cache-like classes often accept int, DateInterval, or DateTime for TTL. InteractsWithTime handles all three:

use Illuminate\Support\InteractsWithTime;

class MyStore
{
    use InteractsWithTime;

    public function put(string $key, mixed $value, mixed $ttl): void
    {
        $seconds    = $this->secondsUntil($ttl);
        $expiresAt  = $this->availableAt($ttl);

        $this->storage[$key] = [
            'value'      => $value,
            'expires_at' => $expiresAt,
        ];
    }
}

Displaying command runtime

use Illuminate\Console\Command;
use Illuminate\Support\InteractsWithTime;

class ProcessDataCommand extends Command
{
    use InteractsWithTime;

    public function handle(): void
    {
        $start = microtime(true);

        // ... work ...

        $this->info("Done in {$this->runTimeForHumans($start)}");
    }
}

The testing variant

Illuminate\Foundation\Testing\Concerns\InteractsWithTime is a different trait — included automatically in TestCase — that provides time-travel helpers for tests:

$this->travel(5)->days();
$this->travelTo(now()->addMonth());
$this->travelBack();

Do not confuse it with Illuminate\Support\InteractsWithTime. The namespaces are different.

Summary

Method	Return	Use case
secondsUntil($delay)	int	Remaining seconds
availableAt($delay)	int	Future UNIX timestamp
parseDateInterval($delay)	DateTimeInterface|int	Normalise delay types
currentTime()	int	Current UNIX timestamp
runTimeForHumans($start, $end)	string	Human-readable elapsed time

Add use InteractsWithTime; to any class that needs to handle int, DateInterval, and DateTimeInterface delay values interchangeably, without writing the conversion logic yourself.

Related pages

• Package Development
• The InteractsWithData Trait
• The Conditionable Trait