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
}
}
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
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)
microtime(true)) en une chaîne lisible.
$start = microtime(true);
// ... traitement ...
echo $this->runTimeForHumans($start); // ex. : "42.15ms" ou "1s 234ms"
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
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();
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 |
int, DateInterval ou DateTimeInterface, use de ce trait vous évite de réimplémenter la logique de conversion.
Pages associées
