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

> Présentation et utilisation du trait utilitaire de calcul temporel employé dans les files d'attente, le cache et la planification.

## Qu'est-ce que InteractsWithTime

`Illuminate\Support\InteractsWithTime` est un trait qui regroupe les calculs de dates, de délais et de temps écoulé. Plus de 40 classes du framework Laravel font `use InteractsWithTime;` et il est employé dans un large éventail de composants : cache, files d'attente, console, connexions à la base de données, etc.

<Info>
  Le code source se trouve dans `src/Illuminate/Support/InteractsWithTime.php`. Il n'expose que des méthodes `protected` et est conçu pour un usage interne aux classes.
</Info>

## Exemples d'utilisation dans le framework

| Classe                                     | Usage                                                 |
| ------------------------------------------ | ----------------------------------------------------- |
| `Cache\ArrayStore` / `DatabaseStore`, etc. | Calcul du TTL (durée de validité)                     |
| `Cache\RateLimiter`                        | Heure de réinitialisation de la limitation            |
| `Queue\Console\RestartCommand`             | Horodatage de redémarrage des workers                 |
| `Database\Connection`                      | Mesure du temps d'exécution des requêtes              |
| `Console\View\Components\Task`             | Affichage du temps d'exécution des tâches de commande |
| `Redis\Limiters\DurationLimiterBuilder`    | Calcul de la durée des limitations Redis              |

## Détail des méthodes

### `secondsUntil()` — nombre de secondes restantes

Retourne le nombre de secondes restant jusqu'à une date/valeur de délai spécifiée. L'argument peut être un `DateTimeInterface`, un `DateInterval` ou un entier représentant des secondes.

```php theme={null}
use Illuminate\Support\InteractsWithTime;

class MyService
{
    use InteractsWithTime;

    public function scheduleAt(\DateTime $target): int
    {
        return $this->secondsUntil($target); // secondes entre maintenant et $target
    }
}
```

Passer une date passée renvoie `0` (jamais un nombre négatif).

```php theme={null}
$seconds = $this->secondsUntil(now()->addMinutes(5)); // 300
$seconds = $this->secondsUntil(now()->subMinutes(5)); // 0 (passé = 0)
$seconds = $this->secondsUntil(60);                   // 60 (l'entier est repris tel quel en secondes)
```

### `availableAt()` — timestamp UNIX de disponibilité

Renvoie un timestamp UNIX correspondant à l'instant actuel additionné du délai indiqué. Utilisé pour les délais de jobs en file d'attente ou le calcul de durées de vie de cache.

```php theme={null}
$timestamp = $this->availableAt(60);              // timestamp UNIX dans 60 secondes
$timestamp = $this->availableAt(new \DateTime('2026-12-31')); // timestamp UNIX de la date indiquée
$timestamp = $this->availableAt(new \DateInterval('PT5M'));    // dans 5 minutes
```

Appelée sans argument (défaut `0`), elle renvoie le timestamp de l'instant présent.

### `parseDateInterval()` — convertit un DateInterval en DateTime

Reçue avec une instance de `DateInterval`, la méthode la convertit en une instance `Carbon` correspondant à l'instant présent additionné de l'intervalle. Les `DateTimeInterface` et les entiers sont renvoyés tels quels.

```php theme={null}
$delay = $this->parseDateInterval(new \DateInterval('P1D')); // Carbon de demain
$delay = $this->parseDateInterval(now()->addHour());         // DateTimeInterface conservé
$delay = $this->parseDateInterval(3600);                     // 3600 (entier conservé)
```

`secondsUntil()` et `availableAt()` appellent cette méthode en interne.

### `currentTime()` — timestamp UNIX actuel

Un simple wrapper qui retourne `Carbon::now()->getTimestamp()`. Utilisé comme instant de référence par `secondsUntil()`.

```php theme={null}
$now = $this->currentTime(); // int (timestamp UNIX)
```

### `runTimeForHumans()` — convertit un temps d'exécution en format lisible

Convertit l'écart entre l'instant de départ et l'instant de fin (mesurés avec `microtime(true)`) en une chaîne lisible.

```php theme={null}
$start = microtime(true);

// ... traitement ...

echo $this->runTimeForHumans($start); // ex. : "42.15ms" ou "1s 234ms"
```

En dessous de 1000 ms, la méthode retourne des millisecondes avec décimales comme `42.15ms` ; au-dessus, elle utilise la forme abrégée `forHumans()` de CarbonInterval (`1s 234ms`, etc.).

Un second argument permet de convertir un intervalle déjà mesuré.

```php theme={null}
$elapsed = $this->runTimeForHumans($start, $end);
```

## Utilisations en développement de packages

### Uniformiser le TTL d'un driver de cache

Utile lorsque vous créez une méthode `put(key, value, ttl)` acceptant indifféremment `int`, `DateInterval` ou `DateTime` comme `ttl`.

```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);

        // Enregistrement dans le stockage réel avec $seconds (int)
        $this->storage[$key] = [
            'value'      => $value,
            'expires_at' => $this->availableAt($ttl),
        ];
    }
}
```

### Afficher le temps d'exécution d'une commande console

Utile pour afficher à l'utilisateur le temps d'exécution dans le `handle()` d'une commande `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);

        // ... traitement ...

        $this->info("Terminé : {$this->runTimeForHumans($start)}");
    }
}
```

## InteractsWithTime côté tests

`Illuminate\Foundation\Testing\Concerns\InteractsWithTime` est un trait distinct qui expose les méthodes `travel*()` permettant de manipuler le temps dans les tests (il est automatiquement intégré à `TestCase`).

```php theme={null}
// Avancer le temps dans un test (Testing\Concerns\InteractsWithTime)
$this->travel(5)->days();
$this->travelTo(now()->addMonth());
$this->travelBack();
```

Son namespace diffère de celui de `Illuminate\Support\InteractsWithTime` (le sujet de cette page) : attention à ne pas les confondre.

## Récapitulatif

| Méthode                          | Retour                   | Usage principal                            |
| -------------------------------- | ------------------------ | ------------------------------------------ |
| `secondsUntil($delay)`           | `int`                    | Récupérer les secondes restantes           |
| `availableAt($delay)`            | `int`                    | Calculer un timestamp d'entrée en validité |
| `parseDateInterval($delay)`      | `DateTimeInterface\|int` | Convertir DateInterval → Carbon            |
| `currentTime()`                  | `int`                    | Timestamp UNIX courant                     |
| `runTimeForHumans($start, $end)` | `string`                 | Temps d'exécution lisible                  |

Si vous souhaitez concevoir une méthode acceptant indifféremment `int`, `DateInterval` ou `DateTimeInterface`, `use` de ce trait vous évite de réimplémenter la logique de conversion.

## Pages associées

* [Développement de packages](/fr/advanced/package-development)
* [Trait InteractsWithData](/fr/advanced/interacts-with-data)
* [Trait Conditionable](/fr/advanced/conditionable)


## Related topics

- [Trait InteractsWithData](/fr/advanced/interacts-with-data.md)
- [Broadcasting](/fr/broadcasting.md)
- [Laravel Horizon](/fr/horizon.md)
- [Attributs PHP](/fr/advanced/php-attributes.md)
- [Queues et jobs](/fr/queues.md)