Trait InteractsWithTime

Guida al trait di utilità per il calcolo del tempo usato in queue, cache e scheduling, con esempi pratici.

​

Cos’è InteractsWithTime

Illuminate\Support\InteractsWithTime è un trait che raccoglie i calcoli di tempo, ritardo e durata. All’interno del framework Laravel oltre 40 classi usano use InteractsWithTime;: è impiegato in un’ampia gamma di componenti come cache, queue, console e connessioni al database.

Il codice sorgente si trova in src/Illuminate/Support/InteractsWithTime.php. È composto solo da metodi protected e si presuppone l’uso dall’interno della classe.

​

Esempi di utilizzo nel framework

Classe	Scopo
Cache\ArrayStore / DatabaseStore ecc.	Calcolo del TTL (tempo di scadenza)
Cache\RateLimiter	Istante di reset del rate limit
Queue\Console\RestartCommand	Timestamp di restart dei worker
Database\Connection	Misurazione del tempo di esecuzione delle query
Console\View\Components\Task	Visualizzazione del tempo di esecuzione dei task
Redis\Limiters\DurationLimiterBuilder	Calcolo della durata per il rate limit su Redis

​

Descrizione dei metodi

​

secondsUntil() — ottiene i secondi rimanenti

Restituisce i secondi rimanenti fino al datetime o al ritardo indicato. L’argomento può essere DateTimeInterface, DateInterval o un intero di secondi.

use Illuminate\Support\InteractsWithTime;

class MyService
{
    use InteractsWithTime;

    public function scheduleAt(\DateTime $target): int
    {
        return $this->secondsUntil($target); // secondi da adesso a $target
    }
}

Se passi un datetime nel passato, restituisce 0 (non diventa negativo).

$seconds = $this->secondsUntil(now()->addMinutes(5)); // 300
$seconds = $this->secondsUntil(now()->subMinutes(5)); // 0 (passato = 0)
$seconds = $this->secondsUntil(60);                   // 60 (l'intero viene interpretato come secondi)

​

availableAt() — timestamp UNIX di disponibilità

Restituisce il timestamp UNIX ottenuto sommando il ritardo all’istante corrente. È usato per calcolare il delay dei job in coda e le scadenze della cache.

$timestamp = $this->availableAt(60);              // timestamp UNIX tra 60 secondi
$timestamp = $this->availableAt(new \DateTime('2026-12-31')); // timestamp UNIX del datetime indicato
$timestamp = $this->availableAt(new \DateInterval('PT5M'));    // tra 5 minuti

Chiamato senza argomenti (default 0) restituisce il timestamp dell’istante corrente.

​

parseDateInterval() — converte DateInterval in DateTime

Se riceve un’istanza DateInterval, la aggiunge all’istante corrente e restituisce un’istanza Carbon. DateTimeInterface e i valori interi vengono restituiti così come sono.

$delay = $this->parseDateInterval(new \DateInterval('P1D')); // Carbon di domani
$delay = $this->parseDateInterval(now()->addHour());         // DateTimeInterface resta invariato
$delay = $this->parseDateInterval(3600);                     // 3600 (intero invariato)

secondsUntil() e availableAt() chiamano internamente questo metodo.

​

currentTime() — timestamp UNIX dell’istante corrente

Semplice wrapper che restituisce Carbon::now()->getTimestamp(). È usato come istante di riferimento in secondsUntil().

$now = $this->currentTime(); // int (timestamp UNIX)

​

runTimeForHumans() — durata di esecuzione in formato leggibile

Converte in una stringa leggibile la differenza tra l’istante iniziale e quello finale registrati con microtime(true).

$start = microtime(true);

// ... elaborazione ...

echo $this->runTimeForHumans($start); // esempio: "42.15ms" oppure "1s 234ms"

Sotto i 1000ms restituisce millisecondi con decimali come 42.15ms; da 1000ms in su usa la forma abbreviata forHumans() di CarbonInterval (1s 234ms, ecc.).

Passando l’istante finale come secondo argomento puoi convertire un intervallo già misurato.

$elapsed = $this->runTimeForHumans($start, $end);

​

Utilizzo nello sviluppo di pacchetti

​

Uniformare il TTL nei driver di cache

Utile per creare metodi come put(key, value, ttl) che accettano int, DateInterval o DateTime come ttl.

use Illuminate\Support\InteractsWithTime;

class MyStore
{
    use InteractsWithTime;

    public function put(string $key, mixed $value, mixed $ttl): void
    {
        $seconds = $this->secondsUntil($ttl);

        // salva nello storage effettivo con $seconds (int)
        $this->storage[$key] = [
            'value'      => $value,
            'expires_at' => $this->availableAt($ttl),
        ];
    }
}

​

Mostrare il tempo di esecuzione di un comando console

Puoi usarlo nell’handle() di un comando Artisan per mostrare all’utente il tempo di elaborazione.

use Illuminate\Console\Command;
use Illuminate\Support\InteractsWithTime;

class ProcessDataCommand extends Command
{
    use InteractsWithTime;

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

        // ... elaborazione ...

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

​

InteractsWithTime per i test

Illuminate\Foundation\Testing\Concerns\InteractsWithTime è una cosa diversa: fornisce i metodi travel*() per manipolare il tempo nei test (viene automaticamente incluso in TestCase).

// avanza il tempo nei test (Testing\Concerns\InteractsWithTime)
$this->travel(5)->days();
$this->travelTo(now()->addMonth());
$this->travelBack();

Attenzione a non confonderlo con Illuminate\Support\InteractsWithTime (oggetto di questa pagina): il namespace è diverso.

​

Riepilogo

Metodo	Valore di ritorno	Uso principale
secondsUntil($delay)	int	Ottenere i secondi rimanenti
availableAt($delay)	int	Calcolo del timestamp di inizio validità
parseDateInterval($delay)	DateTimeInterface|int	Conversione DateInterval → Carbon
currentTime()	int	Timestamp UNIX corrente
runTimeForHumans($start, $end)	string	Visualizzazione leggibile del tempo di esecuzione

Se vuoi creare metodi che accettino indifferentemente int, DateInterval o DateTimeInterface, basta use di questo trait e non dovrai reimplementare la logica di conversione.

​

Pagine correlate

• Sviluppo di pacchetti
• Trait InteractsWithData
• Trait Conditionable