From 2543c9af0c9694891f1ac2cd1ce6bfcc93c6f001 Mon Sep 17 00:00:00 2001 From: Paul Holden Date: Thu, 30 Apr 2026 13:13:55 +0100 Subject: [PATCH] Refer to time-related constants and intended use. --- docs/apis/subsystems/time/index.md | 9 +++++++++ versioned_docs/version-4.5/apis/subsystems/time/index.md | 9 +++++++++ versioned_docs/version-5.0/apis/subsystems/time/index.md | 9 +++++++++ versioned_docs/version-5.1/apis/subsystems/time/index.md | 9 +++++++++ 4 files changed, 36 insertions(+) diff --git a/docs/apis/subsystems/time/index.md b/docs/apis/subsystems/time/index.md index e7c2be329..9b33840b7 100644 --- a/docs/apis/subsystems/time/index.md +++ b/docs/apis/subsystems/time/index.md @@ -125,6 +125,15 @@ Moodle provides a range of methods to display a Unix Timestamp in the relevant L - `usergetdate` - Given a Unix Timestamp, returns an array that represents the date-time in user time - `usertime` - Appends the users timezone offset to an integer timestamp +### Relative time {/* #relative-time */} + +1. Time constants + - See the time-related [constants here](https://github.com/moodle/moodle/blob/4da09fd5082b7d0c05331ebeed6fb6dc70fc55ae/public/lib/moodlelib.php#L38-L73). + - These constants should be used when presenting options for relative time in the user interface. + - They should never be used for the actual calculation of relative times because they cannot account for leap years, DST, etc. +1. Calculation of relative time + - In order to calculate relative time, one of the PHP `\DateTime` classes should be used, e.g. [`\DateTimeImmutable`](https://www.php.net/manual/en/class.datetimeimmutable.php). + ## Glossary {/* #glossary */} ### Timezone {/* #timezone */} diff --git a/versioned_docs/version-4.5/apis/subsystems/time/index.md b/versioned_docs/version-4.5/apis/subsystems/time/index.md index e7c2be329..9b33840b7 100644 --- a/versioned_docs/version-4.5/apis/subsystems/time/index.md +++ b/versioned_docs/version-4.5/apis/subsystems/time/index.md @@ -125,6 +125,15 @@ Moodle provides a range of methods to display a Unix Timestamp in the relevant L - `usergetdate` - Given a Unix Timestamp, returns an array that represents the date-time in user time - `usertime` - Appends the users timezone offset to an integer timestamp +### Relative time {/* #relative-time */} + +1. Time constants + - See the time-related [constants here](https://github.com/moodle/moodle/blob/4da09fd5082b7d0c05331ebeed6fb6dc70fc55ae/public/lib/moodlelib.php#L38-L73). + - These constants should be used when presenting options for relative time in the user interface. + - They should never be used for the actual calculation of relative times because they cannot account for leap years, DST, etc. +1. Calculation of relative time + - In order to calculate relative time, one of the PHP `\DateTime` classes should be used, e.g. [`\DateTimeImmutable`](https://www.php.net/manual/en/class.datetimeimmutable.php). + ## Glossary {/* #glossary */} ### Timezone {/* #timezone */} diff --git a/versioned_docs/version-5.0/apis/subsystems/time/index.md b/versioned_docs/version-5.0/apis/subsystems/time/index.md index e7c2be329..9b33840b7 100644 --- a/versioned_docs/version-5.0/apis/subsystems/time/index.md +++ b/versioned_docs/version-5.0/apis/subsystems/time/index.md @@ -125,6 +125,15 @@ Moodle provides a range of methods to display a Unix Timestamp in the relevant L - `usergetdate` - Given a Unix Timestamp, returns an array that represents the date-time in user time - `usertime` - Appends the users timezone offset to an integer timestamp +### Relative time {/* #relative-time */} + +1. Time constants + - See the time-related [constants here](https://github.com/moodle/moodle/blob/4da09fd5082b7d0c05331ebeed6fb6dc70fc55ae/public/lib/moodlelib.php#L38-L73). + - These constants should be used when presenting options for relative time in the user interface. + - They should never be used for the actual calculation of relative times because they cannot account for leap years, DST, etc. +1. Calculation of relative time + - In order to calculate relative time, one of the PHP `\DateTime` classes should be used, e.g. [`\DateTimeImmutable`](https://www.php.net/manual/en/class.datetimeimmutable.php). + ## Glossary {/* #glossary */} ### Timezone {/* #timezone */} diff --git a/versioned_docs/version-5.1/apis/subsystems/time/index.md b/versioned_docs/version-5.1/apis/subsystems/time/index.md index e7c2be329..9b33840b7 100644 --- a/versioned_docs/version-5.1/apis/subsystems/time/index.md +++ b/versioned_docs/version-5.1/apis/subsystems/time/index.md @@ -125,6 +125,15 @@ Moodle provides a range of methods to display a Unix Timestamp in the relevant L - `usergetdate` - Given a Unix Timestamp, returns an array that represents the date-time in user time - `usertime` - Appends the users timezone offset to an integer timestamp +### Relative time {/* #relative-time */} + +1. Time constants + - See the time-related [constants here](https://github.com/moodle/moodle/blob/4da09fd5082b7d0c05331ebeed6fb6dc70fc55ae/public/lib/moodlelib.php#L38-L73). + - These constants should be used when presenting options for relative time in the user interface. + - They should never be used for the actual calculation of relative times because they cannot account for leap years, DST, etc. +1. Calculation of relative time + - In order to calculate relative time, one of the PHP `\DateTime` classes should be used, e.g. [`\DateTimeImmutable`](https://www.php.net/manual/en/class.datetimeimmutable.php). + ## Glossary {/* #glossary */} ### Timezone {/* #timezone */}