Trait InteractsWithTime

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.

Desarrollo con IA

Patrones de diseño

Desarrollo de paquetes

Estructura de la aplicación

Novedades de Laravel 13

Profundizando en Eloquent

Extensión de validación

Extensión de autenticación

Seguridad

Pruebas

テスト

Qué es InteractsWithTime

Ejemplos de uso dentro del framework

Métodos

`secondsUntil()` — obtener segundos restantes

`availableAt()` — timestamp UNIX en el que estará disponible

`parseDateInterval()` — convertir un DateInterval en DateTime

`currentTime()` — timestamp UNIX del momento actual

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

Uso en el desarrollo de paquetes

Unificar el TTL en un driver de caché

Mostrar tiempo de ejecución en comandos de consola

InteractsWithTime para pruebas

Resumen

Páginas relacionadas

​Qué es InteractsWithTime

​Ejemplos de uso dentro del framework

​Métodos

​secondsUntil() — obtener segundos restantes

​availableAt() — timestamp UNIX en el que estará disponible

​parseDateInterval() — convertir un DateInterval en DateTime

​currentTime() — timestamp UNIX del momento actual

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

​Uso en el desarrollo de paquetes

​Unificar el TTL en un driver de caché

​Mostrar tiempo de ejecución en comandos de consola

​InteractsWithTime para pruebas

​Resumen

​Páginas relacionadas

Qué es InteractsWithTime

Ejemplos de uso dentro del framework

Métodos

`secondsUntil()` — obtener segundos restantes

`availableAt()` — timestamp UNIX en el que estará disponible

`parseDateInterval()` — convertir un DateInterval en DateTime

`currentTime()` — timestamp UNIX del momento actual

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

Uso en el desarrollo de paquetes

Unificar el TTL en un driver de caché

Mostrar tiempo de ejecución en comandos de consola

InteractsWithTime para pruebas

Resumen

Páginas relacionadas