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

> Erläuterung und Anwendung des Utility-Traits für Zeitberechnungen, das in Queue, Cache und Scheduling verwendet wird.

## Was ist InteractsWithTime?

`Illuminate\Support\InteractsWithTime` ist ein Trait, der Berechnungen zu Zeit, Verzögerung und verstrichener Zeit bündelt. Innerhalb des Laravel-Frameworks verwenden über 40 Klassen `use InteractsWithTime;` — er kommt in einer breiten Palette von Komponenten wie Cache, Queue, Console oder Database Connection zum Einsatz.

<Info>
  Der Quellcode befindet sich unter `src/Illuminate/Support/InteractsWithTime.php`. Er besteht ausschließlich aus `protected`-Methoden und ist darauf ausgelegt, klassenintern aufgerufen zu werden.
</Info>

## Beispiele für die Nutzung im Framework

| Klasse                                     | Verwendungszweck                         |
| ------------------------------------------ | ---------------------------------------- |
| `Cache\ArrayStore` / `DatabaseStore` u. a. | Berechnung von TTL (Ablaufzeit)          |
| `Cache\RateLimiter`                        | Reset-Zeitpunkt für Rate Limits          |
| `Queue\Console\RestartCommand`             | Zeitstempel für den Worker-Neustart      |
| `Database\Connection`                      | Messung der Query-Laufzeit               |
| `Console\View\Components\Task`             | Anzeige der Laufzeit von Console-Tasks   |
| `Redis\Limiters\DurationLimiterBuilder`    | Zeitraumberechnung für Redis-Rate-Limits |

## Erläuterung der Methoden

### `secondsUntil()` — verbleibende Sekunden ermitteln

Gibt die Anzahl der Sekunden bis zu einem angegebenen Zeitpunkt bzw. Verzögerungswert zurück. Als Argument sind `DateTimeInterface`, `DateInterval` oder ein ganzzahliger Sekundenwert erlaubt.

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

class MyService
{
    use InteractsWithTime;

    public function scheduleAt(\DateTime $target): int
    {
        return $this->secondsUntil($target); // Sekunden von jetzt bis $target
    }
}
```

Wenn Sie ein Datum in der Vergangenheit übergeben, wird `0` zurückgegeben (nie negativ).

```php theme={null}
$seconds = $this->secondsUntil(now()->addMinutes(5)); // 300
$seconds = $this->secondsUntil(now()->subMinutes(5)); // 0 (Vergangenheit ergibt 0)
$seconds = $this->secondsUntil(60);                   // 60 (Integer wird als Sekunden übernommen)
```

### `availableAt()` — UNIX-Zeitstempel der Verfügbarkeit

Gibt einen UNIX-Zeitstempel zurück, der sich aus der aktuellen Zeit zzgl. einer Verzögerung ergibt. Wird für Job-Verzögerungen in der Queue und die Berechnung von Cache-Ablaufzeiten genutzt.

```php theme={null}
$timestamp = $this->availableAt(60);              // UNIX-Zeitstempel 60 Sekunden voraus
$timestamp = $this->availableAt(new \DateTime('2026-12-31')); // UNIX-Zeitstempel des angegebenen Datums
$timestamp = $this->availableAt(new \DateInterval('PT5M'));    // 5 Minuten voraus
```

Ohne Argument (Standard `0`) wird der aktuelle Zeitstempel zurückgegeben.

### `parseDateInterval()` — DateInterval in DateTime umwandeln

Erhält die Methode eine `DateInterval`-Instanz, wird diese zur aktuellen Zeit addiert und als `Carbon`-Instanz zurückgegeben. `DateTimeInterface` oder Integer werden unverändert zurückgeliefert.

```php theme={null}
$delay = $this->parseDateInterval(new \DateInterval('P1D')); // Carbon für morgen
$delay = $this->parseDateInterval(now()->addHour());         // DateTimeInterface bleibt gleich
$delay = $this->parseDateInterval(3600);                     // 3600 (Integer bleibt gleich)
```

`secondsUntil()` und `availableAt()` rufen intern diese Methode auf.

### `currentTime()` — aktueller UNIX-Zeitstempel

Ein schlichter Wrapper, der `Carbon::now()->getTimestamp()` zurückgibt. Wird als Referenzzeit für `secondsUntil()` verwendet.

```php theme={null}
$now = $this->currentTime(); // int (UNIX-Zeitstempel)
```

### `runTimeForHumans()` — Laufzeit in lesbarer Form

Wandelt die Differenz zwischen einem mit `microtime(true)` erfassten Start- und Endzeitpunkt in eine lesbare Zeichenkette um.

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

// ... Verarbeitung ...

echo $this->runTimeForHumans($start); // z. B. "42.15ms" oder "1s 234ms"
```

Werte unter 1000 ms werden als Millisekunden mit Kommastellen wie `42.15ms` zurückgegeben; ab 1000 ms verwendet Laravel das Kurzformat des `CarbonInterval::forHumans()` (etwa `1s 234ms`).

Über das zweite Argument können Sie auch einen bereits gemessenen Zeitraum umwandeln.

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

## Einsatz in der Paketentwicklung

### Einheitliche TTL für Cache-Treiber

Nützlich, wenn Sie eine Methode `put(key, value, ttl)` anbieten wollen, deren `ttl` sowohl `int`, `DateInterval` als auch `DateTime` akzeptiert.

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

        // Als $seconds (int) im tatsächlichen Storage speichern
        $this->storage[$key] = [
            'value'      => $value,
            'expires_at' => $this->availableAt($ttl),
        ];
    }
}
```

### Laufzeitanzeige in Console-Commands

Nützlich, um dem Nutzer in der `handle()`-Methode eines `Artisan`-Commands die Verarbeitungszeit anzuzeigen.

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

class ProcessDataCommand extends Command
{
    use InteractsWithTime;

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

        // ... Verarbeitung ...

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

## InteractsWithTime für Tests

`Illuminate\Foundation\Testing\Concerns\InteractsWithTime` ist etwas anderes: Es stellt in Testfällen `travel*()`-Methoden zur Manipulation der Zeit bereit (und ist automatisch in `TestCase` eingebunden).

```php theme={null}
// Zeit im Test vorspulen (Testing\Concerns\InteractsWithTime)
$this->travel(5)->days();
$this->travelTo(now()->addMonth());
$this->travelBack();
```

Der Namensraum unterscheidet sich vom `Illuminate\Support\InteractsWithTime` (dem Thema dieser Seite) — verwechseln Sie beide bitte nicht.

## Zusammenfassung

| Methode                          | Rückgabewert             | Hauptzweck                                 |
| -------------------------------- | ------------------------ | ------------------------------------------ |
| `secondsUntil($delay)`           | `int`                    | Ermittlung verbleibender Sekunden          |
| `availableAt($delay)`            | `int`                    | Berechnung des Verfügbarkeits-Zeitstempels |
| `parseDateInterval($delay)`      | `DateTimeInterface\|int` | Umwandlung DateInterval → Carbon           |
| `currentTime()`                  | `int`                    | aktueller UNIX-Zeitstempel                 |
| `runTimeForHumans($start, $end)` | `string`                 | menschenfreundliche Laufzeitanzeige        |

Wenn Sie eine Methode entwerfen wollen, die als Argument `int`, `DateInterval` oder `DateTimeInterface` akzeptiert, sparen Sie sich mit `use` dieses Traits die erneute Implementierung der Konvertierungslogik.

## Verwandte Seiten

* [Paketentwicklung](/de/advanced/package-development)
* [InteractsWithData-Trait](/de/advanced/interacts-with-data)
* [Conditionable-Trait](/de/advanced/conditionable)


## Related topics

- [InteractsWithData-Trait](/de/advanced/interacts-with-data.md)
- [Broadcasting](/de/broadcasting.md)
- [Fluent-Klasse](/de/advanced/fluent.md)
- [PHP-Attribute](/de/advanced/php-attributes.md)
- [Conditionable-Trait](/de/advanced/conditionable.md)