Trait InteractsWithTime

Explicación y uso del trait de utilidades para cálculos de tiempo empleado en colas, caché y schedulers.

​

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
    }
}

Si pasas una fecha pasada, devuelve 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

Si lo llamas sin argumentos (por defecto 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)

​

runTimeForHumans() — tiempo de ejecución en formato legible

Convierte la diferencia entre un tiempo de inicio y otro de fin registrados con microtime(true) en una cadena legible.

$start = microtime(true);

// ... procesamiento ...

echo $this->runTimeForHumans($start); // p. ej.: "42.15ms" o "1s 234ms"

Por debajo de 1000 ms devuelve milisegundos con decimales como 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();

Como el namespace es distinto del 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.

Si quieres crear métodos que acepten 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

• Desarrollo de paquetes
• Trait InteractsWithData
• Trait Conditionable