mirror of
https://github.com/php/doc-en.git
synced 2026-03-27 17:22:10 +01:00
e057f1f552
Actually, most (or even all) datetime functions returned false prior to PHP 8.0.0, where they now throw an error. Besides ZPP failures which we certainly do not want to document explicitly, that also happened in case the objects have not been properly initialized, which is so close to ZPP failures, that we don't want to document that either. Co-authored-by: Alexander Menshchikov <amenshchikov@gmail.com> Closes GH-1358.
514 lines
18 KiB
XML
514 lines
18 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<refentry xml:id="datetime.format" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<refnamediv>
|
|
<refname>DateTimeInterface::format</refname>
|
|
<refname>DateTimeImmutable::format</refname>
|
|
<refname>DateTime::format</refname>
|
|
<refname>date_format</refname>
|
|
<refpurpose>Returns date formatted according to given format</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<para>&style.oop;</para>
|
|
<methodsynopsis role="DateTimeInterface">
|
|
<modifier>public</modifier> <type>string</type><methodname>DateTimeInterface::format</methodname>
|
|
<methodparam><type>string</type><parameter>format</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<methodsynopsis role="DateTimeImmutable">
|
|
<modifier>public</modifier> <type>string</type><methodname>DateTimeImmutable::format</methodname>
|
|
<methodparam><type>string</type><parameter>format</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<methodsynopsis role="DateTime">
|
|
<modifier>public</modifier> <type>string</type><methodname>DateTime::format</methodname>
|
|
<methodparam><type>string</type><parameter>format</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>&style.procedural;</para>
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>date_format</methodname>
|
|
<methodparam><type>DateTimeInterface</type><parameter>object</parameter></methodparam>
|
|
<methodparam><type>string</type><parameter>format</parameter></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Returns date formatted according to given format.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<variablelist>
|
|
&date.datetime.description;
|
|
<varlistentry>
|
|
<term><parameter>format</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The format of the outputted date <type>string</type>. See the formatting
|
|
options below. There are also several
|
|
<link linkend="datetimeinterface.constants.types">predefined date constants</link>
|
|
that may be used instead, so for example <constant>DATE_RSS</constant>
|
|
contains the format string <literal>'D, d M Y H:i:s'</literal>.
|
|
</para>
|
|
<para>
|
|
<table>
|
|
<title>The following characters are recognized in the
|
|
<parameter>format</parameter> parameter string</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry><parameter>format</parameter> character</entry>
|
|
<entry>Description</entry>
|
|
<entry>Example returned values</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry align="center"><emphasis>Day</emphasis></entry>
|
|
<entry>---</entry>
|
|
<entry>---</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>d</literal></entry>
|
|
<entry>Day of the month, 2 digits with leading zeros</entry>
|
|
<entry><literal>01</literal> to <literal>31</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>D</literal></entry>
|
|
<entry>A textual representation of a day, three letters</entry>
|
|
<entry><literal>Mon</literal> through <literal>Sun</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>j</literal></entry>
|
|
<entry>Day of the month without leading zeros</entry>
|
|
<entry><literal>1</literal> to <literal>31</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>l</literal> (lowercase 'L')</entry>
|
|
<entry>A full textual representation of the day of the week</entry>
|
|
<entry><literal>Sunday</literal> through <literal>Saturday</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>N</literal></entry>
|
|
<entry>ISO 8601 numeric representation of the day of the week</entry>
|
|
<entry><literal>1</literal> (for Monday) through <literal>7</literal> (for Sunday)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>S</literal></entry>
|
|
<entry>English ordinal suffix for the day of the month, 2 characters</entry>
|
|
<entry>
|
|
<literal>st</literal>, <literal>nd</literal>, <literal>rd</literal> or
|
|
<literal>th</literal>. Works well with <literal>j</literal>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>w</literal></entry>
|
|
<entry>Numeric representation of the day of the week</entry>
|
|
<entry><literal>0</literal> (for Sunday) through <literal>6</literal> (for Saturday)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>z</literal></entry>
|
|
<entry>The day of the year (starting from 0)</entry>
|
|
<entry><literal>0</literal> through <literal>365</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry align="center"><emphasis>Week</emphasis></entry>
|
|
<entry>---</entry>
|
|
<entry>---</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>W</literal></entry>
|
|
<entry>ISO 8601 week number of year, weeks starting on Monday</entry>
|
|
<entry>Example: <literal>42</literal> (the 42nd week in the year)</entry>
|
|
</row>
|
|
<row>
|
|
<entry align="center"><emphasis>Month</emphasis></entry>
|
|
<entry>---</entry>
|
|
<entry>---</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>F</literal></entry>
|
|
<entry>A full textual representation of a month, such as January or March</entry>
|
|
<entry><literal>January</literal> through <literal>December</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>m</literal></entry>
|
|
<entry>Numeric representation of a month, with leading zeros</entry>
|
|
<entry><literal>01</literal> through <literal>12</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>M</literal></entry>
|
|
<entry>A short textual representation of a month, three letters</entry>
|
|
<entry><literal>Jan</literal> through <literal>Dec</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>n</literal></entry>
|
|
<entry>Numeric representation of a month, without leading zeros</entry>
|
|
<entry><literal>1</literal> through <literal>12</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>t</literal></entry>
|
|
<entry>Number of days in the given month</entry>
|
|
<entry><literal>28</literal> through <literal>31</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry align="center"><emphasis>Year</emphasis></entry>
|
|
<entry>---</entry>
|
|
<entry>---</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>L</literal></entry>
|
|
<entry>Whether it's a leap year</entry>
|
|
<entry><literal>1</literal> if it is a leap year, <literal>0</literal> otherwise.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>o</literal></entry>
|
|
<entry>ISO 8601 week-numbering year. This has the same value as
|
|
<literal>Y</literal>, except that if the ISO week number
|
|
(<literal>W</literal>) belongs to the previous or next year, that year
|
|
is used instead.</entry>
|
|
<entry>Examples: <literal>1999</literal> or <literal>2003</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>X</literal></entry>
|
|
<entry>An expanded full numeric representation of a year, at least 4 digits,
|
|
with <literal>-</literal> for years BCE, and <literal>+</literal>
|
|
for years CE.</entry>
|
|
<entry>Examples: <literal>-0055</literal>, <literal>+0787</literal>,
|
|
<literal>+1999</literal>, <literal>+10191</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>x</literal></entry>
|
|
<entry>An expanded full numeric representation if requried, or a
|
|
standard full numeral representation if possible (like
|
|
<literal>Y</literal>). At least four digits. Years BCE are prefixed
|
|
with a <literal>-</literal>. Years beyond (and including)
|
|
<literal>10000</literal> are prefixed by a
|
|
<literal>+</literal>.</entry>
|
|
<entry>Examples: <literal>-0055</literal>, <literal>0787</literal>,
|
|
<literal>1999</literal>, <literal>+10191</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>Y</literal></entry>
|
|
<entry>A full numeric representation of a year, at least 4 digits,
|
|
with <literal>-</literal> for years BCE.</entry>
|
|
<entry>Examples: <literal>-0055</literal>, <literal>0787</literal>,
|
|
<literal>1999</literal>, <literal>2003</literal>,
|
|
<literal>10191</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>y</literal></entry>
|
|
<entry>A two digit representation of a year</entry>
|
|
<entry>Examples: <literal>99</literal> or <literal>03</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry align="center"><emphasis>Time</emphasis></entry>
|
|
<entry>---</entry>
|
|
<entry>---</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>a</literal></entry>
|
|
<entry>Lowercase Ante meridiem and Post meridiem</entry>
|
|
<entry><literal>am</literal> or <literal>pm</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>A</literal></entry>
|
|
<entry>Uppercase Ante meridiem and Post meridiem</entry>
|
|
<entry><literal>AM</literal> or <literal>PM</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>B</literal></entry>
|
|
<entry>Swatch Internet time</entry>
|
|
<entry><literal>000</literal> through <literal>999</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>g</literal></entry>
|
|
<entry>12-hour format of an hour without leading zeros</entry>
|
|
<entry><literal>1</literal> through <literal>12</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>G</literal></entry>
|
|
<entry>24-hour format of an hour without leading zeros</entry>
|
|
<entry><literal>0</literal> through <literal>23</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>h</literal></entry>
|
|
<entry>12-hour format of an hour with leading zeros</entry>
|
|
<entry><literal>01</literal> through <literal>12</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>H</literal></entry>
|
|
<entry>24-hour format of an hour with leading zeros</entry>
|
|
<entry><literal>00</literal> through <literal>23</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>i</literal></entry>
|
|
<entry>Minutes with leading zeros</entry>
|
|
<entry><literal>00</literal> to <literal>59</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>s</literal></entry>
|
|
<entry>Seconds with leading zeros</entry>
|
|
<entry><literal>00</literal> through <literal>59</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>u</literal></entry>
|
|
<entry>
|
|
Microseconds. Note that
|
|
<function>date</function> will always generate
|
|
<literal>000000</literal> since it takes an <type>int</type>
|
|
parameter, whereas <methodname>DateTime::format</methodname> does
|
|
support microseconds if <classname>DateTime</classname> was
|
|
created with microseconds.
|
|
</entry>
|
|
<entry>Example: <literal>654321</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>v</literal></entry>
|
|
<entry>
|
|
Milliseconds. Same note applies as for
|
|
<literal>u</literal>.
|
|
</entry>
|
|
<entry>Example: <literal>654</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry align="center"><emphasis>Timezone</emphasis></entry>
|
|
<entry>---</entry>
|
|
<entry>---</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>e</literal></entry>
|
|
<entry>Timezone identifier</entry>
|
|
<entry>Examples: <literal>UTC</literal>, <literal>GMT</literal>, <literal>Atlantic/Azores</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>I</literal> (capital i)</entry>
|
|
<entry>Whether or not the date is in daylight saving time</entry>
|
|
<entry><literal>1</literal> if Daylight Saving Time, <literal>0</literal> otherwise.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>O</literal></entry>
|
|
<entry>Difference to Greenwich time (GMT) without colon between hours and minutes</entry>
|
|
<entry>Example: <literal>+0200</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>P</literal></entry>
|
|
<entry>Difference to Greenwich time (GMT) with colon between hours and minutes</entry>
|
|
<entry>Example: <literal>+02:00</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>p</literal></entry>
|
|
<entry>
|
|
The same as <literal>P</literal>, but returns <literal>Z</literal> instead of <literal>+00:00</literal>
|
|
(available as of PHP 8.0.0)
|
|
</entry>
|
|
<entry>Examples: <literal>Z</literal> or <literal>+02:00</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>T</literal></entry>
|
|
<entry>Timezone abbreviation, if known; otherwise the GMT offset.</entry>
|
|
<entry>Examples: <literal>EST</literal>, <literal>MDT</literal>, <literal>+05</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>Z</literal></entry>
|
|
<entry>Timezone offset in seconds. The offset for timezones west of UTC is always
|
|
negative, and for those east of UTC is always positive.</entry>
|
|
<entry><literal>-43200</literal> through <literal>50400</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry align="center"><emphasis>Full Date/Time</emphasis></entry>
|
|
<entry>---</entry>
|
|
<entry>---</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>c</literal></entry>
|
|
<entry>ISO 8601 date</entry>
|
|
<entry>2004-02-12T15:19:21+00:00</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>r</literal></entry>
|
|
<entry><link xlink:href="&url.rfc;2822">RFC 2822</link>/<link xlink:href="&url.rfc;5322">RFC 5322</link> formatted date</entry>
|
|
<entry>Example: <literal>Thu, 21 Dec 2000 16:01:07 +0200</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>U</literal></entry>
|
|
<entry>Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT)</entry>
|
|
<entry>See also <function>time</function></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</para>
|
|
<para>
|
|
Unrecognized characters in the format string will be printed
|
|
as-is. The <literal>Z</literal> format will always return
|
|
<literal>0</literal> when using <function>gmdate</function>.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Since this function only accepts <type>int</type> timestamps the
|
|
<literal>u</literal> format character is only useful when using the
|
|
<function>date_format</function> function with user based timestamps
|
|
created with <function>date_create</function>.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
Returns the formatted date string on success.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="changelog">
|
|
&reftitle.changelog;
|
|
<informaltable>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>&Version;</entry>
|
|
<entry>&Description;</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>8.2.0</entry>
|
|
<entry>
|
|
The format characters <literal>X</literal> and <literal>x</literal>
|
|
have been added.
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>8.0.0</entry>
|
|
<entry>
|
|
The format character <literal>p</literal> has been added.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title><function>DateTimeInterface::format</function> example</title>
|
|
<para>&style.oop;</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$date = new DateTimeImmutable('2000-01-01');
|
|
echo $date->format('Y-m-d H:i:s');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
<para>&style.procedural;</para>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$date = date_create('2000-01-01');
|
|
echo date_format($date, 'Y-m-d H:i:s');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
2000-01-01 00:00:00
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
<example>
|
|
<title>More examples</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
// set the default timezone to use.
|
|
date_default_timezone_set('UTC');
|
|
|
|
// now
|
|
$date = new DateTimeImmutable();
|
|
|
|
// Prints something like: Wednesday
|
|
echo $date->format('l'), "\n";
|
|
|
|
// Prints something like: Wednesday 19th of October 2022 08:40:48 AM
|
|
echo $date->format('l jS \o\f F Y h:i:s A'), "\n";
|
|
|
|
/* use the constants in the format parameter */
|
|
// prints something like: Wed, 19 Oct 2022 08:40:48 +0000
|
|
echo $date->format(DateTimeInterface::RFC2822), "\n";
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
You can prevent a recognized character in the format string from being
|
|
expanded by escaping it with a preceding backslash. If the character with
|
|
a backslash is already a special sequence, you may need to also escape
|
|
the backslash.
|
|
<example>
|
|
<title>Escaping characters while formatting</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
$date = new DateTimeImmutable();
|
|
|
|
// prints something like: Wednesday the 19th
|
|
echo $date->format('l \t\h\e jS');
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
To format dates in other languages,
|
|
<methodname>IntlDateFormatter::format</methodname>
|
|
can be used instead of <methodname>DateTimeInterface::format</methodname>.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="notes">
|
|
&reftitle.notes;
|
|
<para>
|
|
This method does not use locales. All output is in English.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<simplelist>
|
|
<member><methodname>IntlDateFormatter::format</methodname></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|