> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Info>
  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.
</Info>

## 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.

```php theme={null}
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).

```php theme={null}
$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é.

```php theme={null}
$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.

```php theme={null}
$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()`.

```php theme={null}
$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.

```php theme={null}
$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.

```php theme={null}
$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`.

```php theme={null}
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`.

```php theme={null}
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`).

```php theme={null}
// 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](/es/advanced/package-development)
* [Trait InteractsWithData](/es/advanced/interacts-with-data)
* [Trait Conditionable](/es/advanced/conditionable)


## Related topics

- [Trait InteractsWithData](/es/advanced/interacts-with-data.md)
- [Broadcasting](/es/broadcasting.md)
- [Atributos de PHP](/es/advanced/php-attributes.md)
- [Clase Fluent](/es/advanced/fluent.md)
- [Trait Conditionable](/es/advanced/conditionable.md)