User:Lucamauri/Sandbox/ParserTime

From mediawiki.org
Jump to navigation Jump to search

Temporary page to improve documentation from https://www.mediawiki.org/wiki/Help:Extension:ParserFunctions##time as discussed in T223453.

#time[edit]

Code Description Current output
(Purge this page's cache to update)
Year
Y 4-digit year. 2021
y 2-digit year. 21
L 1 if it's a leap year, 0 if not. 0
o[note 1] ISO-8601 year of the specified week.[note 2] 2020[note 3]
  1. Requires PHP 5.1.0 and newer and rev:45208.
  2. This has the same value as Y, except that if the ISO week number (W) belongs to the previous or next year, that year is used instead.
  3. Will output literal o if note 1 not fulfilled.
Month
n Month index, not zero-padded. 1
m Month index, zero-padded. 01
M An abbreviation of the month name, in the site language. Jan
F The full month name in the site language. January
xg Output the full month name in the genitive form for site languages that distinguish between genitive and nominative forms. This option is useful for many Slavic languages like Polish, Russian, Belarusian, Czech, Slovak, Slovene, Ukrainian, etc. For Polish:
{{#time:F Y|June 2010|pl}} → czerwiec 2010
(nominative)
{{#time:d xg Y|20 June 2010|pl}} → 20 czerwca 2010
(genitive)
Day of the month or the year
j Day of the month, not zero-padded. 3
d Day of the month, zero-padded. 03
z Day of the year (January 1 = 0).
Note Note: To get the ISO day of the year add 1.
2
Week and day of the week
W ISO 8601 week number, zero-padded. 53
N ISO 8601 day of the week (Monday = 1, Sunday = 7). 7
w Number of the day of the week (Sunday = 0, Saturday = 6). 0
D An abbreviation for the day of the week. Rarely internationalized. Sun
l The full weekday name. Rarely internationalized. Sunday
Hour
a "am" during the morning (00:00:00 → 11:59:59), "pm" otherwise (12:00:00 → 23:59:59). am
A Uppercase version of a above. AM
g Hour in 12-hour format, not zero-padded. 12
h Hour in 12-hour format, zero-padded. 12
G Hour in 24-hour format, not zero-padded. 0
H Hour in 24-hour format, zero-padded. 00
Minutes and seconds
i Minutes past the hour, zero-padded. 12
s Seconds past the minute, zero-padded. 41
U Unix time. Seconds since January 1 1970 00:00:00 GMT. 1609632761
Timezone (as of 1.22wmf2)
e Timezone identifier. UTC
I Whether or not the date is in daylight savings time. 0
O Difference to Greenwich time (GMT) +0000
P Difference to Greenwich time (GMT), with colon +00:00
T Timezone abbreviation. UTC
Z Timezone offset in seconds. 0
Miscellaneous
t Number of days in the current month. 31
c ISO 8601 formatted date, equivalent to Y-m-d"T"H:i:s+00:00. 2021-01-03T00:12:41+00:00
r RFC 5322 formatted date, equivalent to D, j M Y H:i:s +0000, with weekday name and month name not internationalized. Sun, 03 Jan 2021 00:12:41 +0000
Non-Gregorian calendars
Islamic
xmj Day of the month. 19
xmF Full month name. Jumada al-awwal
xmn Month index. 5
xmY Full year. 1442
Iranian (Jalaly)
xit Number of days in the month. 30
xiz Day of the year. 289
xij Day of the month. 14
xiF Full month name. Dey
xin Month index. 10
xiY Full year. 1399
xiy 2-digit year. 99
Hebrew
xjj Day of the month. 19
xjF Full month name. Tevet
xjt Number of days in month. 29
xjx Genitive form of the month name. Tevet
xjn Month number. 4
xjY Full year. 5781
Thai solar
xkY Full year in Thai solar calendar.
Note Note: For years before 1941 the dates in Jan-Mar range are not calculated properly.
2564
Minguo/Juche year
xoY Full year. 110
Japanese nengo
xtY Full year. 令和3
Flags
xn Format the next numeric code as a raw ASCII number. In the Hindi language, {{#time:H, xnH}} produces ०६, 06.
xN Like xn, but as a toggled flag, which endures until the end of the string or until the next appearance of xN in the string.
xr Format the next number as a roman numeral. Only works for numbers up to 10,000
(upto 3,000 in pre MediaWiki 1.20).
{{#time:xrY}} → MMXXI
xh Format the next number as a Hebrew numeral. {{#time:xhY}} → ב'כ"א

This parser function takes a date and/or time (in the Gregorian calendar) and formats it according to the syntax given. A date/time object can be specified; the default is the value of the magic word {{CURRENTTIMESTAMP}} – that is, the time the page was last rendered into HTML.

{{#time: format string }}
{{#time: format string | date/time object }}
{{#time: format string | date/time object | language code }}
{{#time: format string | date/time object | language code | local }}

The list of accepted formatting codes is given in the table to the right. Any character in the formatting string that is not recognized is passed through unaltered; this applies also to blank spaces (the system does not need them for interpreting the codes). There are also two ways to escape characters within the formatting string:

  1. A backslash followed by a formatting character is interpreted as a single literal character
  2. Characters enclosed in double quotes are considered literal characters, and the quotes are removed.

In addition, the digraph xx is interpreted as a single literal "x".

{{#time: Y-m-d }}2021-01-03
{{#time: [[Y]] m d }}2021 01 03
{{#time: [[Y (year)]] }}2021 (21UTCamSun, 03 Jan 2021 00:12:41 +0000)
{{#time: [[Y "(year)"]] }}2021 (year)
{{#time: i's" }}12'41"

The date/time object can be in any format accepted by PHP's strtotime() function. Both absolute (eg 20 December 2000) and relative (eg +20 hours) times are accepted.

{{#time: r|now}}Sun, 03 Jan 2021 00:12:41 +0000
{{#time: r|+2 hours}}Sun, 03 Jan 2021 02:12:41 +0000
{{#time: r|now + 2 hours}}Sun, 03 Jan 2021 02:12:41 +0000
{{#time: r|20 December 2000}}Wed, 20 Dec 2000 00:00:00 +0000
{{#time: r|December 20, 2000}}Wed, 20 Dec 2000 00:00:00 +0000
{{#time: r|2000-12-20}}Wed, 20 Dec 2000 00:00:00 +0000
{{#time: r|2000 December 20}}Error: Invalid time.

The language code in ISO 639-3 (?) allows the string to be displayed in the chosen language

{{#time:d F Y|1988-02-28|nl}}28 februari 1988
{{#time:l|now|uk}}неділя
{{#time:d xg Y|20 June 2010|pl}}20 czerwca 2010

The local parameter specifies if the date/time object refers to the local timezone or to UTC.
This is a boolean parameters: its value is determined by casting the value of the argument (see the official PHP documentation for details on how string are cast to boolean values).

Please note that, if the variable $wgLocaltimezone is set to UTC, there is no difference in the output when local is set to true or false

See the following examples for details:

{{#time: Y F d H:i:s|now|it|0}}2021 gennaio 03 00:12:41
{{#time: Y F d H:i:s|now|it|1}}2021 gennaio 03 00:12:41
{{#time: Y F d H:i:s|+2 hours||0}}2021 January 03 02:12:41
{{#time: Y F d H:i:s|+2 hours||1}}2021 January 03 02:12:41
{{#time:c|2019-05-16T17:05:43+02:00|it}}2019-05-16T15:05:43+00:00
{{#time:c|2019-05-16T17:05:43+02:00|it|0}}2019-05-16T15:05:43+00:00
{{#time:c|2019-05-16T17:05:43+02:00|it|true}}2019-05-16T15:05:43+00:00

If you've calculated a Unix timestamp, you may use it in date calculations by pre-pending an @ symbol.

{{#time: U | now }}1609632761
{{#time: r | @1609632761 }}Sun, 03 Jan 2021 00:12:41 +0000
Warning Warning: Without the @ prefix before numeric timestamp values, the result is an error most of the time, or is an unexpected value:
{{#time: r | 1970-01-01 00:16:39 }}Thu, 01 Jan 1970 00:16:39 +0000
{{#time: U | 1970-01-01 00:16:39 }}999
{{#time: r | @999 }}Thu, 01 Jan 1970 00:16:39 +0000 (correct)
{{#time: r | 999 }}Error: Invalid time. (unsupported year format)
{{#time: r | 1970-01-01 00:16:40 }}Thu, 01 Jan 1970 00:16:40 +0000
{{#time: U | 1970-01-01 00:16:40 }}1000
{{#time: r | @1000 }}Thu, 01 Jan 1970 00:16:40 +0000 (correct)
{{#time: r | 1000 }}Fri, 03 Jan 1000 00:00:00 +0000 (interpreted as a year with current month and day of the month)
{{#time: r | 1970-01-01 02:46:39 }}Thu, 01 Jan 1970 02:46:39 +0000
{{#time: U | 1970-01-01 02:46:39 }}9999
{{#time: r | @9999 }}Thu, 01 Jan 1970 02:46:39 +0000 (correct)
{{#time: r | 9999 }}Sun, 03 Jan 9999 00:00:00 +0000 (interpreted as a year with current month and day of the month)
{{#time: r | 1970-01-01 02:46:40 }}Thu, 01 Jan 1970 02:46:40 +0000
{{#time: U | 1970-01-01 02:46:40 }}10000
{{#time: r | @10000 }}Thu, 01 Jan 1970 02:46:40 +0000 (correct)
{{#time: r | 10000 }}Error: Invalid time. (unsupported year format)
Warning Warning: The range of acceptable input is 1 January 0111 → 31 December 9999. For the years 100 through 110 the output is inconsistent, Y and leap years are like the years 100-110, r, D, l and U are like interpreting these years as 2000-2010.

{{#time: d F Y | 29 Feb 0100 }}01 March 0100
(correct, no leap year), but
{{#time: r | 29 Feb 0100 }}Mon, 01 Mar 0100 00:00:00 +0000 (wrong, even if 100 is interpreted as 2000, because that is a leap year)
{{#time: d F Y | 15 April 10000 }}Error: Invalid time.
{{#time: r | 10000-4-15 }}Sat, 15 Apr 2000 10:00:00 +0000

Year numbers 0-99 are interpreted as 2000-2069 and 1970-1999, except when written in 4-digit format with leading zeros:
{{#time: d F Y | 1 Jan 6 }}01 January 2006
{{#time: d F Y | 1 Jan 06 }}01 January 2006
{{#time: d F Y | 1 Jan 006 }}01 January 2006
{{#time: d F Y | 1 Jan 0006 }}01 January 0006 (4-digit format)

The weekday is supplied for the years 100-110 and from 1753, for the years 111-1752 the r-output shows "Unknown" and the l-output "<>". As a consequence, the r-output is not accepted as input for these years.

Full or partial absolute dates can be specified; the function will "fill in" parts of the date that are not specified using the current values:

{{#time: Y | January 1 }}2021
Warning Warning: The fill-in feature is not consistent; some parts are filled in using the current values, others are not:

{{#time: Y m d H:i:s | June }}2021 06 03 00:00:00 Gives the start of the day, but the current day of the month and the current year.

{{#time: Y m d H:i:s | 2003 }}2003 01 03 00:00:00 Gives the start of the day, but the current day of the year.

A four-digit number is always interpreted as a year, never as hours and minutes:[1]

{{#time: Y m d H:i:s | 1959 }}1959 01 03 00:00:00

A six-digit number is interpreted as hours, minutes and seconds if possible, but otherwise as an error (not, for instance, a year and month):

{{#time: Y m d H:i:s | 195909 }}2021 01 03 19:59:09 Input is treated as a time rather than a year+month code.
{{#time: Y m d H:i:s | 196009 }}Error: Invalid time. Although 19:60:09 is not a valid time, 196009 is not interpreted as September 1960.

The function performs a certain amount of date mathematics:

{{#time: d F Y | January 0 2008 }}31 December 2007
{{#time: d F | January 32 }}Error: Invalid time.
{{#time: d F | February 29 2008 }}29 February
{{#time: d F | February 29 2007 }}01 March
{{#time:Y-F|now -1 months}}2020-December

The total length of the format strings of the calls of #time is limited to 6000 characters[2].

Time Zone issue[edit]

There is a bug in this #time parser function (more specifically in PHP DateTime) that does not allow the passing-in of non-integers as relative time zone offsets. This issue does not apply when using an on-the-hour time zone, such as EDT. For example:

  • {{#time:g:i A | -4 hours }} ==> 8:12 PM

However, Venezuela is on a -4.5 hours time offset from UTC, and thus using its time zone will not normally allow the correct calculation of a relative time zone offset. Here's what happens:

  • {{#time:g:i A | -4.5 hours }} ==> 9:12 AM

To workaround this issue, simply convert the time into minutes or seconds, like this:

  • {{#time:g:i A | -270 minutes }} ==> 7:42 PM
  • {{#time:g:i A | -16200 seconds }} ==> 7:42 PM

(Tim Starling, the developer of this function, provided the exact syntax for this solution.)

#timel[edit]

This function is identical to {{#time: ... }}, when the local parameter is set to true, so it always uses the local time of the wiki (as set in $wgLocaltimezone ).
Syntax of the function is:

{{#timel: format string }}
{{#timel: format string | date/time object }}
{{#timel: format string | date/time object | language code }}
Please note that, if the variable $wgLocaltimezone is set to UTC, there is no difference in the output when local is set to true or false
Example of the use of #time and #timel parser functions from a server where the timezone is not UTC

For instance, see the following examples:

{{#time:c|now|it}}2021-01-03T00:12:41+00:00
{{#time:c|now|it|0}}2021-01-03T00:12:41+00:00
{{#time:c|now|it|1}}2021-01-03T00:12:41+00:00
{{#timel:c|now|it}}2021-01-03T00:12:41+00:00
Warning Warning: Be aware that U for both time and timel will return the same number of seconds since 1970-01-01 00:00:00 UTC on Wikipedias with different timezones than UTC (formerly known as GMT)
U Unix time. Seconds since January 1 1970 00:00:00 GMT.
Z Timezone offset in seconds.
{{#time: U}}1609632761
{{#timel: U}}1609632761
{{#time: Z}}0
{{#timel: Z}}0
  1. Prior to r86805 in 2011 this was not the case.
  2. ExtParserFunctions.php at phabricator.wikimedia.org