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.

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.

​

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.

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

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

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

$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().

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

$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é.

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

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.

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

// 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
• Trait InteractsWithData
• Trait Conditionable