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
}
}
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
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)
microtime(true).
$start = microtime(true);
// ... elaborazione ...
echo $this->runTimeForHumans($start); // esempio: "42.15ms" oppure "1s 234ms"
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
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();
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 |
int, DateInterval o DateTimeInterface, basta use di questo trait e non dovrai reimplementare la logica di conversione.
Pagine correlate
