Qué es InteractsWithTime
Illuminate\Support\InteractsWithTime es un trait que agrupa los cálculos de tiempo, retrasos y tiempos transcurridos. Dentro del framework, más de 40 clases hacen use InteractsWithTime;, y se emplea en componentes tan diversos como caché, colas, consola o conexiones de base de datos.
El código fuente está en src/Illuminate/Support/InteractsWithTime.php. Todos sus métodos son protected, así que están pensados para ser invocados desde el interior de la clase que los usa.
Ejemplos de uso dentro del framework
| Clase | Uso |
|---|
Cache\ArrayStore / DatabaseStore, etc. | Cálculo del TTL (tiempo de vida). |
Cache\RateLimiter | Momento de reinicio del rate limit. |
Queue\Console\RestartCommand | Timestamp de reinicio del worker. |
Database\Connection | Medición del tiempo de ejecución de consultas. |
Console\View\Components\Task | Muestra el tiempo de ejecución de tareas de comando. |
Redis\Limiters\DurationLimiterBuilder | Cálculo del periodo del rate limit en Redis. |
Métodos
secondsUntil() — obtener segundos restantes
Devuelve los segundos que quedan hasta la fecha/hora o retraso indicados. Puede recibir un DateTimeInterface, un DateInterval o un entero de segundos.
use Illuminate\Support\InteractsWithTime;
class MyService
{
use InteractsWithTime;
public function scheduleAt(\DateTime $target): int
{
return $this->secondsUntil($target); // segundos desde ahora hasta $target
}
}
0 (no toma valores negativos).
$seconds = $this->secondsUntil(now()->addMinutes(5)); // 300
$seconds = $this->secondsUntil(now()->subMinutes(5)); // 0 (pasado = 0)
$seconds = $this->secondsUntil(60); // 60 (el entero se usa como segundos)
availableAt() — timestamp UNIX en el que estará disponible
Devuelve el timestamp UNIX resultante de sumar el retraso al momento actual. Se usa para calcular retrasos de jobs en colas o tiempos de expiración de la caché.
$timestamp = $this->availableAt(60); // timestamp UNIX dentro de 60 segundos
$timestamp = $this->availableAt(new \DateTime('2026-12-31')); // timestamp UNIX de esa fecha
$timestamp = $this->availableAt(new \DateInterval('PT5M')); // 5 minutos más tarde
0), devuelve el timestamp del momento actual.
parseDateInterval() — convertir un DateInterval en DateTime
Si recibe una instancia de DateInterval, la convierte en una instancia Carbon sumándola al momento actual. Los DateTimeInterface y enteros los devuelve sin cambios.
$delay = $this->parseDateInterval(new \DateInterval('P1D')); // el Carbon de mañana
$delay = $this->parseDateInterval(now()->addHour()); // los DateTimeInterface tal cual
$delay = $this->parseDateInterval(3600); // 3600 (los enteros tal cual)
secondsUntil() y availableAt() invocan internamente este método.
currentTime() — timestamp UNIX del momento actual
Un wrapper simple que devuelve Carbon::now()->getTimestamp(). Se usa como base temporal en secondsUntil().
$now = $this->currentTime(); // int (timestamp UNIX)
microtime(true) en una cadena legible.
$start = microtime(true);
// ... procesamiento ...
echo $this->runTimeForHumans($start); // p. ej.: "42.15ms" o "1s 234ms"
42.15ms; a partir de 1000 ms usa el formato corto de CarbonInterval::forHumans() (1s 234ms, etc.).
Pasando un segundo argumento con el tiempo final puedes convertir un intervalo ya medido.
$elapsed = $this->runTimeForHumans($start, $end);
Uso en el desarrollo de paquetes
Unificar el TTL en un driver de caché
Es útil cuando construyes un método put(key, value, ttl) en el que ttl puede ser int, DateInterval o DateTime.
use Illuminate\Support\InteractsWithTime;
class MyStore
{
use InteractsWithTime;
public function put(string $key, mixed $value, mixed $ttl): void
{
$seconds = $this->secondsUntil($ttl);
// Guarda en el almacenamiento real con $seconds (int)
$this->storage[$key] = [
'value' => $value,
'expires_at' => $this->availableAt($ttl),
];
}
}
Mostrar tiempo de ejecución en comandos de consola
Puedes aprovecharlo para mostrar al usuario el tiempo de proceso en el handle() de un comando Artisan.
use Illuminate\Console\Command;
use Illuminate\Support\InteractsWithTime;
class ProcessDataCommand extends Command
{
use InteractsWithTime;
public function handle(): void
{
$start = microtime(true);
// ... procesamiento ...
$this->info("Completado: {$this->runTimeForHumans($start)}");
}
}
InteractsWithTime para pruebas
Illuminate\Foundation\Testing\Concerns\InteractsWithTime es otra cosa: ofrece los métodos travel*() para manipular el tiempo en los tests (se incorpora automáticamente a TestCase).
// Avanzar el tiempo en un test (Testing\Concerns\InteractsWithTime)
$this->travel(5)->days();
$this->travelTo(now()->addMonth());
$this->travelBack();
Illuminate\Support\InteractsWithTime (objeto de esta página), no los confundas.
Resumen
| Método | Valor devuelto | Uso principal |
|---|
secondsUntil($delay) | int | Obtener segundos restantes. |
availableAt($delay) | int | Calcular el timestamp desde el que estará disponible. |
parseDateInterval($delay) | DateTimeInterface|int | Convertir DateInterval a Carbon. |
currentTime() | int | Timestamp UNIX actual. |
runTimeForHumans($start, $end) | string | Mostrar el tiempo de ejecución de forma legible. |
int, DateInterval o DateTimeInterface como argumento, con solo hacer use de este trait te ahorras reimplementar la lógica de conversión.
Páginas relacionadas
