> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  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.
</Info>

## 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.

```php theme={null}
use Illuminate\Support\InteractsWithTime;

class MyService
{
    use InteractsWithTime;

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

```php theme={null}
$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.

```php theme={null}
$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.

```php theme={null}
$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()`.

```php theme={null}
$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"`).

```php theme={null}
$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:

```php theme={null}
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

```php theme={null}
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:

```php theme={null}
$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](/en/advanced/package-development)
* [The InteractsWithData Trait](/en/advanced/interacts-with-data)
* [The Conditionable Trait](/en/advanced/conditionable)