From def8d6b58f1786121227b053cd884257d742a628 Mon Sep 17 00:00:00 2001
From: Florent Morselli <florent.morselli@spomky-labs.com>
Date: Tue, 20 May 2025 16:11:40 +0200
Subject: [PATCH] Add runtime schedule modification feature to docs

Document the new ability introduced in Symfony 6.4 to modify schedules dynamically at runtime. This includes recalculating the internal trigger heap for better control over recurring tasks.
---
 scheduler.rst | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/scheduler.rst b/scheduler.rst
index 3f2f8d7d2ac..4c5955a9470 100644
--- a/scheduler.rst
+++ b/scheduler.rst
@@ -890,6 +890,46 @@ code::
     use the ``messenger:consume`` command as explained in the previous
     section.
 
+Modifying the Schedule at Runtime
+---------------------------------
+
+.. versionadded:: 6.4
+
+    Modifying the schedule at runtime and recalculating the heap was introduced in Symfony 6.4.
+
+When a recurring message is added to or removed from the schedule,
+the scheduler automatically restarts and recalculates the internal trigger heap.
+This allows dynamic control over scheduled tasks during runtime.
+code::
+
+    // src/Scheduler/DynamicScheduleProvider.php
+    namespace App\Scheduler;
+
+    #[AsSchedule('uptoyou')]
+    class DynamicScheduleProvider implements ScheduleProviderInterface
+    {
+        private ?Schedule $schedule = null;
+
+        public function getSchedule(): Schedule
+        {
+            return $this->schedule ??= (new Schedule())
+                ->with(
+                    // ...
+                )
+            ;
+        }
+
+        public function clearAndAddMessages(): void
+        {
+            // Clear the current schedule (if any) and add new recurring messages
+            $this->schedule?->clear();
+            $this->schedule?->add(
+                RecurringMessage::cron('@hourly', new DoActionMessage()),
+                RecurringMessage::cron('@daily', new DoAnotherActionMessage()),
+            );
+        }
+    }
+
 Debugging the Schedule
 ----------------------