Symfony Clock != DateTime : Pourquoi choisir le futur ?

Introduction

Longtemps, je me suis demandé pourquoi on utilise DateTimeImmutable, DateTime, et toutes ces classes pour gérer le temps. Évidemment, on s’attend à gagner en précision, à pouvoir facilement récupérer des dates de création, de modification, etc.

Mais parfois, on a besoin d’encore plus de précision, comme gérer des millisecondes, manipuler le temps de manière flexible, ou simuler des situations temporelles spécifiques.
C’est exactement là que la Core Team de Symfony a eu l’idée de créer Clock. Une innovation discrète, mais qui change radicalement la façon dont on gère le temps dans nos applications.

DateTime vs Symfony Clock : Pourquoi ça change tout ?

🔍 1. Le problème avec DateTime

DateTime et DateTimeImmutable sont des classes robustes, mais elles ont un gros défaut : elles sont liées directement à l’horloge système. Chaque fois que vous instanciez un objet, il reflète l’heure actuelle, sans possibilité de le contrôler facilement.

Cela pose des soucis, notamment quand vous voulez :

• Tester des comportements temporels complexes (ex : expiration de tokens, délais d’attente)
• Simuler des événements futurs ou passés
• Gérer des environnements distribués où l’heure doit être synchronisée

2. Symfony Clock : Plus qu’une simple horloge

Avec Symfony Clock, on passe à un autre niveau. Ce composant introduit une abstraction du temps, permettant de créer des horloges personnalisées, de figer le temps, ou même de le faire avancer à votre guise.

Exemple basique avec une horloge factice :

use Symfony\Component\Clock\MockClock;

$clock = new MockClock('2023-01-01 00:00:00');
echo $clock->now()->format('Y-m-d H:i:s'); 
// Affiche toujours '2023-01-01 00:00:00' tant qu'on ne modifie pas l'horloge

$clock->sleep(3600); // Avance l'heure d'une heure
echo $clock->now()->format('Y-m-d H:i:s'); 
// Affiche '2023-01-01 01:00:00'

Ce genre de flexibilité est impossible avec DateTime sans recourir à des hacks.

⚡ Exemple concret : Gérer des prestations sur plusieurs jours avec Symfony Clock

 Le besoin :

Imaginons une application qui doit gérer des prestations événementielles (concerts, spectacles, services de nuit, etc.).
Certaines prestations peuvent commencer à 19h00 et se terminer à 3h00 du matin le lendemain. L’objectif est de :

Simuler des scénarios temporels lors des tests (ex : vérifier le comportement à minuit pile)

Vérifier si une prestation est en cours à un instant T

S’assurer qu’il n’y a pas de chevauchement avec d’autres prestations

💡 Modélisation de la prestation

use Symfony\Component\Clock\ClockInterface;

class Event {
    private \DateTimeImmutable $startTime;
    private \DateTimeImmutable $endTime;

    public function __construct(\DateTimeImmutable $startTime, \DateTimeImmutable $endTime) {
        if ($endTime <= $startTime) {
            throw new \InvalidArgumentException('La date de fin doit être postérieure à la date de début.');
        }
        $this->startTime = $startTime;
        $this->endTime = $endTime;
    }

    public function isOngoing(ClockInterface $clock): bool {
        $now = $clock->now();
        return $now >= $this->startTime && $now <= $this->endTime;
    }
}

---

🚀 Utilisation en conditions réelles

Créons une prestation qui commence à 19h00 et se termine à 3h00 le lendemain :

use Symfony\Component\Clock\SystemClock;

$clock = new SystemClock();

$startTime = new \DateTimeImmutable('2024-02-01 19:00:00');
$endTime = new \DateTimeImmutable('2024-02-02 03:00:00');

$event = new Event($startTime, $endTime);

if ($event->isOngoing($clock)) {
    echo "La prestation est en cours !";
} else {
    echo "La prestation n'est pas en cours.";
}

Avantages de l’approche

• Précision totale : Vous gérez facilement des plages horaires qui s’étendent sur plusieurs jours.
• Testabilité : Plus besoin d’attendre des heures réelles pour tester des scénarios complexes.
• Flexibilité : Vous pouvez facilement ajuster l’heure pour simuler des comportements à des moments critiques (ex : juste avant ou après minuit).
• Sécurité : Évite les bugs liés aux fuseaux horaires ou aux transitions jour/nuit.

La fusion parfaite : Symfony Clock + Symfony Workflow = Un code puissant

Maintenant que vous comprenez la puissance de Symfony Clock, imaginez ce que cela peut donner si on le fusionne avec un autre composant clé de Symfony : Symfony Workflow.
Cette combinaison permet de gérer des processus complexes et automatisés, avec des transitions d’état conditionnées par des événements temporels précis.

Pourquoi cette fusion est un game-changer ?

Le composant Workflow de Symfony permet de modéliser des processus métiers sous forme d’états et de transitions (par exemple : un système de validation de commandes, un processus de recrutement, etc.).
En y intégrant Symfony Clock, vous ajoutez une dimension temporelle :

• Activer des transitions automatiquement après un certain délai
• Gérer des états temporaires qui expirent après un temps donné
• Simuler des workflows pour des tests avancés

Exemple concret : Gestion d’une prestation avec un workflow temporel

Imaginons une prestation avec les états suivants :

• Programmé → En cours → Terminé
  Avec des transitions déclenchées automatiquement en fonction de l’heure.

Définition du workflow (services.yaml)

framework:
    workflows:
        prestation_workflow:
            type: 'state_machine'
            supports:
                - App\Entity\Event
            initial_marking: programmé
            places:
                - programmé
                - en_cours
                - terminé
            transitions:
                commencer:
                    from: programmé
                    to: en_cours
                terminer:
                    from: en_cours
                    to: terminé

Ensuite on créer le service :

use Symfony\Component\Workflow\WorkflowInterface;
use Symfony\Component\Clock\ClockInterface;

class EventProcessor {
    private WorkflowInterface $workflow;
    private ClockInterface $clock;

    public function __construct(WorkflowInterface $workflow, ClockInterface $clock) {
        $this->workflow = $workflow;
        $this->clock = $clock;
    }

    public function process(Event $event): void {
        $now = $this->clock->now();

        if ($event->getStartTime() <= $now && $this->workflow->can($event, 'commencer')) {
            $this->workflow->apply($event, 'commencer');
        }

        if ($event->getEndTime() <= $now && $this->workflow->can($event, 'terminer')) {
            $this->workflow->apply($event, 'terminer');
        }
    }
}

Tests ultra-efficaces grâce à MockClock

use Symfony\Component\Clock\MockClock;

$mockClock = new MockClock('2024-02-01 18:00:00'); // Avant le début de l’événement
$event = new Event(new \DateTimeImmutable('2024-02-01 19:00:00'), new \DateTimeImmutable('2024-02-02 03:00:00'));

$processor = new EventProcessor($workflow, $mockClock);
$processor->process($event);

assert($event->getStatus() === 'programmé'); // L'événement n'a pas encore commencé

// Avançons le temps à 20h00
$mockClock->sleep(2 * 3600);
$processor->process($event);

assert($event->getStatus() === 'en_cours'); // ✅ L'événement est maintenant en cours

// Avançons à 4h00 du matin (après la fin de l’événement)
$mockClock->sleep(8 * 3600);
$processor->process($event);

assert($event->getStatus() === 'terminé'); // ✅ L'événement est terminé

La fusion de Symfony Clock avec Symfony Workflow transforme la gestion des processus métier en une machine puissante, précise et totalement automatisée.
Que vous développiez des applications simples ou des architectures complexes, ce duo vous garantit un code plus propre, testable, et robuste.

Le futur du développement Symfony passe par des composants intelligemment combinés. Alors, prêt à automatiser votre temps ?

            +-----------------------+
            |      Programmé        |
            |  (startTime > now)    |
            +----------+------------+
                       |
        [Clock atteint startTime]
                       |
                       v
            +-----------------------+
            |       En cours        |
            | (startTime <= now <=  |
            |      endTime)         |
            +----------+------------+
                       |
        [Clock atteint endTime]
                       |
                       v
            +-----------------------+
            |       Terminé         |
            |   (now > endTime)     |
            +-----------------------+

Conclusion

Symfony, en cherchant un moyen puissant de gérer le temps, s’est penché sur cette problématique avec la Core Team. Lors d’un talk, Nicolas Grekas m’a complètement convaincu de l’intérêt de ce composant, et de sa pertinence face aux limitations de DateTime et DateTimeImmutable.

Que ce soit pour :

• Définir une durée écoulée de manière précise
• Automatiser des transitions d’état dans un workflow complexe
• Ou encore simuler des environnements temporels lors de tests unitaires

… Symfony Clock s’impose comme un outil incontournable. La fusion avec des composants comme Symfony Workflow permet même de repousser les limites de ce qu’on pensait possible en termes d’automatisation et de gestion des processus métiers.

C’est un excellent composant, souvent sous-estimé, qui mérite qu’on lui prête plus d’attention.

Et toi ?  Dans tes projets, combien de fois utilises-tu Date, DateTimeImmutable, sans te poser la question de leur impact sur la testabilité ou la flexibilité de ton code ?
Peut-être est-il temps d’essayer Clock… et de voir à quel point il peut simplifier ta vie de développeur.