bug #60745 [Scheduler] Add warning about comma-separated weekdays in PeriodicalTrigger

wazum · wazum · commit c974e6dc36ee · 2025-07-17T10:03:35.000+02:00
diff --git a/scheduler.rst b/scheduler.rst
@@ -286,6 +286,20 @@ defined by PHP datetime functions::
     RecurringMessage::every('3 weeks', new Message());
     RecurringMessage::every('first Monday of next month', new Message());
 
+.. warning::
+
+    Comma-separated weekdays (e.g., ``'Monday, Thursday, Saturday'``) are not supported
+    by the ``every()`` method. For multiple weekdays, use cron expressions instead:
+
+        // Instead of this (not supported):
+        RecurringMessage::every('Monday, Thursday, Saturday', new Message());
+
+        // Use this:
+        RecurringMessage::cron('5 12 * * 1,4,6', new Message());
+
+        // With timezone (equivalent to the every() method with DateTimeImmutable):
+        RecurringMessage::cron('5 12 * * 1,4,6', new Message(), 'Europe/Warsaw');
+
 .. tip::
 
     You can also define periodic tasks using :ref:`the AsPeriodicTask attribute <scheduler-attributes-periodic-task>`.
