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

# InteractsWithTime 트레이트

> 큐·캐시·스케줄링에서 사용되는 시간 계산 유틸리티 트레이트의 해설과 활용법

## InteractsWithTime란

`Illuminate\Support\InteractsWithTime`은, 시간·지연·경과 시간의 계산을 모은 트레이트입니다. Laravel 프레임워크 내에서는 40개 이상의 클래스가 `use InteractsWithTime;`을 사용하고 있으며, 캐시·큐·콘솔·데이터베이스 커넥션 등 폭넓은 컴포넌트에서 사용되고 있습니다.

<Info>
  소스 코드는 `src/Illuminate/Support/InteractsWithTime.php`에 있습니다. `protected` 메서드만으로 구성되어 있으며, 클래스 내부에서 호출하는 용도를 전제로 합니다.
</Info>

## 프레임워크 내의 사용 예

| 클래스                                     | 이용 목적               |
| --------------------------------------- | ------------------- |
| `Cache\ArrayStore` / `DatabaseStore` 등  | TTL(유효 기한)의 계산      |
| `Cache\RateLimiter`                     | 레이트 리밋의 리셋 시각       |
| `Queue\Console\RestartCommand`          | 워커 재시작 타임스탬프        |
| `Database\Connection`                   | 쿼리 실행 시간의 측정        |
| `Console\View\Components\Task`          | 커맨드 태스크의 실행 시간 표시   |
| `Redis\Limiters\DurationLimiterBuilder` | Redis 레이트 리밋의 기간 계산 |

## 메서드 해설

### `secondsUntil()` — 남은 초 수 취득

지정한 일시·지연값까지의 남은 초 수를 반환합니다. 인수에는 `DateTimeInterface`·`DateInterval`·초 수의 정수값 중 하나를 전달할 수 있습니다.

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

class MyService
{
    use InteractsWithTime;

    public function scheduleAt(\DateTime $target): int
    {
        return $this->secondsUntil($target); // 現在から $target までの秒数
    }
}
```

과거의 일시를 전달하면 `0`을 반환합니다(음수가 되지 않습니다).

```php theme={null}
$seconds = $this->secondsUntil(now()->addMinutes(5)); // 300
$seconds = $this->secondsUntil(now()->subMinutes(5)); // 0（過去は 0）
$seconds = $this->secondsUntil(60);                   // 60（整数はそのまま秒数）
```

### `availableAt()` — 이용 가능해지는 UNIX 타임스탬프

현재 시각에 지연을 가산한 UNIX 타임스탬프를 반환합니다. 큐의 잡 지연이나 캐시의 유효 기한 계산에 사용됩니다.

```php theme={null}
$timestamp = $this->availableAt(60);              // 60 秒後の UNIX タイムスタンプ
$timestamp = $this->availableAt(new \DateTime('2026-12-31')); // 指定日時の UNIX タイムスタンプ
$timestamp = $this->availableAt(new \DateInterval('PT5M'));    // 5 分後
```

인수 없이(기본값 `0`)로 호출하면 현재 시각의 타임스탬프를 반환합니다.

### `parseDateInterval()` — DateInterval을 DateTime으로 변환

`DateInterval` 인스턴스를 받으면, 현재 시각에 가산한 `Carbon` 인스턴스로 변환하여 반환합니다. `DateTimeInterface`나 정수값은 그대로 반환합니다.

```php theme={null}
$delay = $this->parseDateInterval(new \DateInterval('P1D')); // 明日の Carbon
$delay = $this->parseDateInterval(now()->addHour());         // DateTimeInterface はそのまま
$delay = $this->parseDateInterval(3600);                     // 3600（整数はそのまま）
```

`secondsUntil()`과 `availableAt()`은 내부에서 이 메서드를 호출합니다.

### `currentTime()` — 현재 시각의 UNIX 타임스탬프

`Carbon::now()->getTimestamp()`를 반환하는 심플한 래퍼입니다. `secondsUntil()`의 기준 시각으로 사용됩니다.

```php theme={null}
$now = $this->currentTime(); // int（UNIX タイムスタンプ）
```

### `runTimeForHumans()` — 실행 시간을 사람이 읽기 쉬운 형식으로

`microtime(true)`로 기록한 시작 시각과 종료 시각의 차이를, 읽기 쉬운 문자열로 변환합니다.

```php theme={null}
$start = microtime(true);

// ... 처리 ...

echo $this->runTimeForHumans($start); // 例: "42.15ms" または "1s 234ms"
```

1000ms 미만은 `42.15ms`처럼 소수점 있는 밀리초, 1000ms 이상은 CarbonInterval의 `forHumans()` 단축 형식(`1s 234ms` 등)으로 반환합니다.

두 번째 인수에 종료 시각을 전달함으로써, 측정된 구간을 변환할 수도 있습니다.

```php theme={null}
$elapsed = $this->runTimeForHumans($start, $end);
```

## 패키지 개발에서의 활용

### 캐시 드라이버의 TTL 통일

`put(key, value, ttl)`의 `ttl`로서 `int`·`DateInterval`·`DateTime` 중 어느 것이라도 받아들이는 메서드를 만들 때 편리합니다.

```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);

        // $seconds（int）で実際のストレージに保存
        $this->storage[$key] = [
            'value'      => $value,
            'expires_at' => $this->availableAt($ttl),
        ];
    }
}
```

### 콘솔 커맨드의 처리 시간 표시

`Artisan` 커맨드의 `handle()`에서 처리 시간을 사용자에게 표시할 때 활용할 수 있습니다.

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

class ProcessDataCommand extends Command
{
    use InteractsWithTime;

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

        // ... 처리 ...

        $this->info("완료: {$this->runTimeForHumans($start)}");
    }
}
```

## 테스트용 InteractsWithTime

`Illuminate\Foundation\Testing\Concerns\InteractsWithTime`은 별개의 것이며, 테스트 케이스에서 시간을 조작하는 `travel*()` 메서드를 제공합니다(`TestCase`에 자동적으로 포함됩니다).

```php theme={null}
// テスト内で時間を進める（Testing\Concerns\InteractsWithTime）
$this->travel(5)->days();
$this->travelTo(now()->addMonth());
$this->travelBack();
```

`Illuminate\Support\InteractsWithTime`(이 페이지의 대상)과는 네임스페이스가 다르므로, 혼동하지 않도록 주의해 주세요.

## 정리

| 메서드                              | 반환값                      | 주요 용도                       |
| -------------------------------- | ------------------------ | --------------------------- |
| `secondsUntil($delay)`           | `int`                    | 남은 초 수의 취득                  |
| `availableAt($delay)`            | `int`                    | 유효 개시 타임스탬프의 계산             |
| `parseDateInterval($delay)`      | `DateTimeInterface\|int` | DateInterval → Carbon으로의 변환 |
| `currentTime()`                  | `int`                    | 현재의 UNIX 타임스탬프              |
| `runTimeForHumans($start, $end)` | `string`                 | 실행 시간의 사람용 표시               |

인수로 `int`·`DateInterval`·`DateTimeInterface` 중 어느 것이라도 받아들이는 메서드를 만들고 싶은 경우, 이 트레이트를 `use`하는 것만으로 변환 로직을 다시 구현하지 않아도 됩니다.

## 관련 페이지

* [패키지 개발](/ko/advanced/package-development)
* [InteractsWithData 트레이트](/ko/advanced/interacts-with-data)
* [Conditionable 트레이트](/ko/advanced/conditionable)


## Related topics

- [InteractsWithData 트레이트](/ko/advanced/interacts-with-data.md)
- [Macroable 트레이트](/ko/advanced/macroable.md)
- [Dumpable 트레이트](/ko/advanced/dumpable.md)
- [Conditionable 트레이트](/ko/advanced/conditionable.md)
- [ForwardsCalls 트레이트](/ko/advanced/forwards-calls.md)