From 47b1b9eca3638dfb43cbc4b22a159d205e7d545b Mon Sep 17 00:00:00 2001
From: Daniel Ziegenberg <daniel@ziegenberg.at>
Date: Wed, 26 Feb 2025 11:40:39 +0100
Subject: [PATCH] MDL-79434 core_calendar: Initial deprecation of
 calendar_sub_month

Signed-off-by: Daniel Ziegenberg <daniel@ziegenberg.at>
---
 .upgradenotes/MDL-79434-2025022414193330.yml |  7 +++++++
 calendar/lib.php                             | 12 -----------
 calendar/tests/calendartype_test.php         |  6 +++++-
 lib/deprecatedlib.php                        | 21 ++++++++++++++++++++
 4 files changed, 33 insertions(+), 13 deletions(-)
 create mode 100644 .upgradenotes/MDL-79434-2025022414193330.yml

diff --git a/.upgradenotes/MDL-79434-2025022414193330.yml b/.upgradenotes/MDL-79434-2025022414193330.yml
new file mode 100644
index 00000000000..f2622347c45
--- /dev/null
+++ b/.upgradenotes/MDL-79434-2025022414193330.yml
@@ -0,0 +1,7 @@
+issueNumber: MDL-79434
+notes:
+  core_calendar:
+    - message: >-
+        Initial deprecation of calendar_sub_month.
+        Use \core_calendar\type_factory::get_calendar_instance()->get_prev_month() instead.
+      type: deprecated
diff --git a/calendar/lib.php b/calendar/lib.php
index 2a6457daf87..a9bd59faf8a 100644
--- a/calendar/lib.php
+++ b/calendar/lib.php
@@ -1626,18 +1626,6 @@ function calendar_add_month($month, $year) {
     return $calendartype->get_next_month($year, $month);
 }
 
-/**
- * Get the previous month.
- *
- * @param int $month the number of the month.
- * @param int $year the number of the year.
- * @return array previous month
- */
-function calendar_sub_month($month, $year) {
-    $calendartype = \core_calendar\type_factory::get_calendar_instance();
-    return $calendartype->get_prev_month($year, $month);
-}
-
 /**
  * Returns the courses to load events for.
  *
diff --git a/calendar/tests/calendartype_test.php b/calendar/tests/calendartype_test.php
index 48dad1af95c..4f63f982cdb 100644
--- a/calendar/tests/calendartype_test.php
+++ b/calendar/tests/calendartype_test.php
@@ -208,7 +208,11 @@ final class calendartype_test extends \advanced_testcase {
         $this->assertEquals($calendar->get_num_days_in_month('1986', '9'), calendar_days_in_month('9', '1986'));
         $this->assertEquals($calendar->get_next_month('1986', '9'), calendar_add_month('9', '1986'));
         $this->assertEquals($calendar->get_prev_month('1986', '9'), calendar_sub_month('9', '1986'));
-
+        $this->assertDebuggingCalled(
+            'Deprecation: calendar_sub_month has been deprecated since 5.0. ' .
+            'Use \core_calendar\type_factory::get_calendar_instance()->get_prev_month() instead. ' .
+            'See MDL-79434 for more information.'
+        );
         // Test the lib/moodle.php functions.
         $this->assertEquals($calendar->get_num_days_in_month('1986', '9'), days_in_month('9', '1986'));
         $this->assertEquals($calendar->get_weekday('1986', '9', '16'), dayofweek('16', '9', '1986'));
diff --git a/lib/deprecatedlib.php b/lib/deprecatedlib.php
index b052f46ed4a..dcff0f35cb1 100644
--- a/lib/deprecatedlib.php
+++ b/lib/deprecatedlib.php
@@ -989,3 +989,24 @@ function calendar_get_link_previous() {
 function calendar_get_link_next() {
     \core\deprecation::emit_deprecation_if_present(__FUNCTION__);
 }
+
+/**
+ * Get the previous month.
+ *
+ * @param int $month the number of the month.
+ * @param int $year the number of the year.
+ * @return array previous month
+ *
+ * @deprecated since 5.0 MDL-79434 Use \core_calendar\type_factory::get_calendar_instance()->get_prev_month() instead,
+ *  but pay regard to the order of arguments!
+ * @todo MDL-84655 Remove this function in Moodle 6.0
+ */
+#[\core\attribute\deprecated(
+    '\core_calendar\type_factory::get_calendar_instance()->get_prev_month()',
+    since: '5.0',
+    mdl: 'MDL-79434'
+)]
+function calendar_sub_month($month, $year) {
+    \core\deprecation::emit_deprecation_if_present(__FUNCTION__);
+    return \core_calendar\type_factory::get_calendar_instance()->get_prev_month($year, $month);
+}