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.

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.

​

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.

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

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

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

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

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

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

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

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.

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

// 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
• InteractsWithData-Trait
• Conditionable-Trait