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();
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 |
use InteractsWithTime; to any class that needs to handle int, DateInterval, and DateTimeInterface delay values interchangeably, without writing the conversion logic yourself.
Related pages
