<?xml version="1.0" encoding="utf-8"?> <!-- $Revision$ --> <refentry xml:id="function.strftime" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <refnamediv> <refname>strftime</refname> <refpurpose>Format a local time/date according to locale settings</refpurpose> </refnamediv> <refsect1 role="description"> &reftitle.description; <methodsynopsis> <type>string</type><methodname>strftime</methodname> <methodparam><type>string</type><parameter>format</parameter></methodparam> <methodparam choice="opt"><type>int</type><parameter>timestamp</parameter><initializer>time()</initializer></methodparam> </methodsynopsis> <para> Format the time and/or date according to locale settings. Month and weekday names and other language-dependent strings respect the current locale set with <function>setlocale</function>. </para> <para> Not all conversion specifiers may be supported by your C library, in which case they will not be supported by PHP's <function>strftime</function>. Additionally, not all platforms support negative timestamps, so your date range may be limited to no earlier than the Unix epoch. This means that %e, %T, %R and, %D (and possibly others) - as well as dates prior to <literal>Jan 1, 1970</literal> - will not work on Windows, some Linux distributions, and a few other operating systems. For Windows systems, a complete overview of supported conversion specifiers can be found at <link xlink:href="&url.strftime.win32;"><acronym>MSDN</acronym></link>. </para> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; <para> <variablelist> <varlistentry> <term><parameter>format</parameter></term> <listitem> <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></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>%a</literal></entry> <entry>An abbreviated textual representation of the day</entry> <entry><literal>Sun</literal> through <literal>Sat</literal></entry> </row> <row> <entry><literal>%A</literal></entry> <entry>A full textual representation of the day</entry> <entry><literal>Sunday</literal> through <literal>Saturday</literal></entry> </row> <row> <entry><literal>%d</literal></entry> <entry>Two-digit day of the month (with leading zeros)</entry> <entry><literal>01</literal> to <literal>31</literal></entry> </row> <row> <entry><literal>%e</literal></entry> <entry> Day of the month, with a space preceding single digits. Not implemented as described on Windows. See below for more information. </entry> <entry><literal> 1</literal> to <literal>31</literal></entry> </row> <row> <entry><literal>%j</literal></entry> <entry>Day of the year, 3 digits with leading zeros</entry> <entry><literal>001</literal> to <literal>366</literal></entry> </row> <row> <entry><literal>%u</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>%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 align="center"><emphasis>Week</emphasis></entry> <entry>---</entry> <entry>---</entry> </row> <row> <entry><literal>%U</literal></entry> <entry>Week number of the given year, starting with the first Sunday as the first week</entry> <entry><literal>13</literal> (for the 13th full week of the year)</entry> </row> <row> <entry><literal>%V</literal></entry> <entry>ISO-8601:1988 week number of the given year, starting with the first week of the year with at least 4 weekdays, with Monday being the start of the week</entry> <entry><literal>01</literal> through <literal>53</literal> (where 53 accounts for an overlapping week)</entry> </row> <row> <entry><literal>%W</literal></entry> <entry>A numeric representation of the week of the year, starting with the first Monday as the first week</entry> <entry><literal>46</literal> (for the 46th week of the year beginning with a Monday)</entry> </row> <row> <entry align="center"><emphasis>Month</emphasis></entry> <entry>---</entry> <entry>---</entry> </row> <row> <entry><literal>%b</literal></entry> <entry>Abbreviated month name, based on the locale</entry> <entry><literal>Jan</literal> through <literal>Dec</literal></entry> </row> <row> <entry><literal>%B</literal></entry> <entry>Full month name, based on the locale</entry> <entry><literal>January</literal> through <literal>December</literal></entry> </row> <row> <entry><literal>%h</literal></entry> <entry>Abbreviated month name, based on the locale (an alias of %b)</entry> <entry><literal>Jan</literal> through <literal>Dec</literal></entry> </row> <row> <entry><literal>%m</literal></entry> <entry>Two digit representation of the month</entry> <entry><literal>01</literal> (for January) through <literal>12</literal> (for December)</entry> </row> <row> <entry align="center"><emphasis>Year</emphasis></entry> <entry>---</entry> <entry>---</entry> </row> <row> <entry><literal>%C</literal></entry> <entry>Two digit representation of the century (year divided by 100, truncated to an integer)</entry> <entry><literal>19</literal> for the 20th Century</entry> </row> <row> <entry><literal>%g</literal></entry> <entry>Two digit representation of the year going by ISO-8601:1988 standards (see %V)</entry> <entry>Example: <literal>09</literal> for the week of January 6, 2009</entry> </row> <row> <entry><literal>%G</literal></entry> <entry>The full four-digit version of %g</entry> <entry>Example: <literal>2008</literal> for the week of January 3, 2009</entry> </row> <row> <entry><literal>%y</literal></entry> <entry>Two digit representation of the year</entry> <entry>Example: <literal>09</literal> for 2009, <literal>79</literal> for 1979</entry> </row> <row> <entry><literal>%Y</literal></entry> <entry>Four digit representation for the year</entry> <entry>Example: <literal>2038</literal></entry> </row> <row> <entry align="center"><emphasis>Time</emphasis></entry> <entry>---</entry> <entry>---</entry> </row> <row> <entry><literal>%H</literal></entry> <entry>Two digit representation of the hour in 24-hour format</entry> <entry><literal>00</literal> through <literal>23</literal></entry> </row> <row> <entry><literal>%k</literal></entry> <entry>Two digit representation of the hour in 24-hour format, with a space preceding single digits</entry> <entry><literal> 0</literal> through <literal>23</literal></entry> </row> <row> <entry><literal>%I</literal></entry> <entry>Two digit representation of the hour in 12-hour format</entry> <entry><literal>01</literal> through <literal>12</literal></entry> </row> <row> <entry><literal>%l (lower-case 'L')</literal></entry> <entry>Hour in 12-hour format, with a space preceding single digits</entry> <entry><literal> 1</literal> through <literal>12</literal></entry> </row> <row> <entry><literal>%M</literal></entry> <entry>Two digit representation of the minute</entry> <entry><literal>00</literal> through <literal>59</literal></entry> </row> <row> <entry><literal>%p</literal></entry> <entry>UPPER-CASE 'AM' or 'PM' based on the given time</entry> <entry>Example: <literal>AM</literal> for 00:31, <literal>PM</literal> for 22:23</entry> </row> <row> <entry><literal>%P</literal></entry> <entry>lower-case 'am' or 'pm' based on the given time</entry> <entry>Example: <literal>am</literal> for 00:31, <literal>pm</literal> for 22:23</entry> </row> <row> <entry><literal>%r</literal></entry> <entry>Same as "%I:%M:%S %p"</entry> <entry>Example: <literal>09:34:17 PM</literal> for 21:34:17</entry> </row> <row> <entry><literal>%R</literal></entry> <entry>Same as "%H:%M"</entry> <entry>Example: <literal>00:35</literal> for 12:35 AM, <literal>16:44</literal> for 4:44 PM</entry> </row> <row> <entry><literal>%S</literal></entry> <entry>Two digit representation of the second</entry> <entry><literal>00</literal> through <literal>59</literal></entry> </row> <row> <entry><literal>%T</literal></entry> <entry>Same as "%H:%M:%S"</entry> <entry>Example: <literal>21:34:17</literal> for 09:34:17 PM</entry> </row> <row> <entry><literal>%X</literal></entry> <entry>Preferred time representation based on locale, without the date</entry> <entry>Example: <literal>03:59:16</literal> or <literal>15:59:16</literal></entry> </row> <row> <entry><literal>%z</literal></entry> <entry>The time zone offset. Not implemented as described on Windows. See below for more information.</entry> <entry>Example: <literal>-0500</literal> for US Eastern Time</entry> </row> <row> <entry><literal>%Z</literal></entry> <entry>The time zone abbreviation. Not implemented as described on Windows. See below for more information.</entry> <entry>Example: <literal>EST</literal> for Eastern Time</entry> </row> <row> <entry align="center"><emphasis>Time and Date Stamps</emphasis></entry> <entry>---</entry> <entry>---</entry> </row> <row> <entry><literal>%c</literal></entry> <entry>Preferred date and time stamp based on locale</entry> <entry>Example: <literal>Tue Feb 5 00:45:10 2009</literal> for February 5, 2009 at 12:45:10 AM</entry> </row> <row> <entry><literal>%D</literal></entry> <entry>Same as "%m/%d/%y"</entry> <entry>Example: <literal>02/05/09</literal> for February 5, 2009</entry> </row> <row> <entry><literal>%F</literal></entry> <entry>Same as "%Y-%m-%d" (commonly used in database datestamps)</entry> <entry>Example: <literal>2009-02-05</literal> for February 5, 2009</entry> </row> <row> <entry><literal>%s</literal></entry> <entry>Unix Epoch Time timestamp (same as the <function>time</function> function)</entry> <entry>Example: <literal>305815200</literal> for September 10, 1979 08:40:00 AM</entry> </row> <row> <entry><literal>%x</literal></entry> <entry>Preferred date representation based on locale, without the time</entry> <entry>Example: <literal>02/05/09</literal> for February 5, 2009</entry> </row> <row> <entry align="center"><emphasis>Miscellaneous</emphasis></entry> <entry>---</entry> <entry>---</entry> </row> <row> <entry><literal>%n</literal></entry> <entry>A newline character ("\n")</entry> <entry>---</entry> </row> <row> <entry><literal>%t</literal></entry> <entry>A Tab character ("\t")</entry> <entry>---</entry> </row> <row> <entry><literal>%%</literal></entry> <entry>A literal percentage character ("%")</entry> <entry>---</entry> </row> </tbody> </tgroup> </table> </para> <para> Maximum length of this parameter is 1023 characters. </para> <warning> <simpara> Contrary to ISO-9899:1999, Sun Solaris starts with Sunday as 1. As a result, <literal>%u</literal> may not function as described in this manual. </simpara> </warning> <warning> <para> <emphasis>Windows only:</emphasis> </para> <para> The <literal>%e</literal> modifier is not supported in the Windows implementation of this function. To achieve this value, the <literal>%#d</literal> modifier can be used instead. The example below illustrates how to write a cross platform compatible function. </para> <para> The <literal>%z</literal> and <literal>%Z</literal> modifiers both return the time zone name instead of the offset or abbreviation. </para> </warning> <warning> <simpara> <emphasis>Mac OS X only:</emphasis> The <literal>%P</literal> modifier is not supported in the Mac OS X implementation of this function. </simpara> </warning> </listitem> </varlistentry> &date.timestamp.description; </variablelist> </para> </refsect1> <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> Returns a string formatted according <parameter>format</parameter> using the given <parameter>timestamp</parameter> or the current local time if no timestamp is given. Month and weekday names and other language-dependent strings respect the current locale set with <function>setlocale</function>. </para> </refsect1> <refsect1 role="errors"> &reftitle.errors; &date.timezone.errors.description; <para> As the output is dependent upon the underlying C library, some conversion specifiers are not supported. On Windows, supplying unknown conversion specifiers will result in 5 <constant>E_WARNING</constant> messages and return &false;. On other operating systems you may not get any <constant>E_WARNING</constant> messages and the output may contain the conversion specifiers unconverted. </para> </refsect1> <refsect1 role="changelog"> &reftitle.changelog; <para> <informaltable> <tgroup cols="2"> <thead> <row> <entry>&Version;</entry> <entry>&Description;</entry> </row> </thead> <tbody> &date.timezone.errors.changelog; </tbody> </tgroup> </informaltable> </para> </refsect1> <refsect1 role="examples"> &reftitle.examples; <para> This example will work if you have the respective locales installed in your system. <example> <title><function>strftime</function> locale examples</title> <programlisting role="php"> <![CDATA[ <?php setlocale(LC_TIME, "C"); echo strftime("%A"); setlocale(LC_TIME, "fi_FI"); echo strftime(" in Finnish is %A,"); setlocale(LC_TIME, "fr_FR"); echo strftime(" in French %A and"); setlocale(LC_TIME, "de_DE"); echo strftime(" in German %A.\n"); ?> ]]> </programlisting> </example> </para> <para> <example> <title>ISO 8601:1988 week number example</title> <programlisting role="php"> <![CDATA[ <?php /* December 2002 / January 2003 ISOWk M Tu W Thu F Sa Su ----- ---------------------------- 51 16 17 18 19 20 21 22 52 23 24 25 26 27 28 29 1 30 31 1 2 3 4 5 2 6 7 8 9 10 11 12 3 13 14 15 16 17 18 19 */ // Outputs: 12/28/2002 - %V,%G,%Y = 52,2002,2002 echo "12/28/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/28/2002")) . "\n"; // Outputs: 12/30/2002 - %V,%G,%Y = 1,2003,2002 echo "12/30/2002 - %V,%G,%Y = " . strftime("%V,%G,%Y", strtotime("12/30/2002")) . "\n"; // Outputs: 1/3/2003 - %V,%G,%Y = 1,2003,2003 echo "1/3/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2003")) . "\n"; // Outputs: 1/10/2003 - %V,%G,%Y = 2,2003,2003 echo "1/10/2003 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/10/2003")) . "\n"; /* December 2004 / January 2005 ISOWk M Tu W Thu F Sa Su ----- ---------------------------- 51 13 14 15 16 17 18 19 52 20 21 22 23 24 25 26 53 27 28 29 30 31 1 2 1 3 4 5 6 7 8 9 2 10 11 12 13 14 15 16 */ // Outputs: 12/23/2004 - %V,%G,%Y = 52,2004,2004 echo "12/23/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/23/2004")) . "\n"; // Outputs: 12/31/2004 - %V,%G,%Y = 53,2004,2004 echo "12/31/2004 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("12/31/2004")) . "\n"; // Outputs: 1/2/2005 - %V,%G,%Y = 53,2004,2005 echo "1/2/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/2/2005")) . "\n"; // Outputs: 1/3/2005 - %V,%G,%Y = 1,2005,2005 echo "1/3/2005 - %V,%G,%Y = " . strftime("%V,%G,%Y",strtotime("1/3/2005")) . "\n"; ?> ]]> </programlisting> </example> </para> <para> <example> <title>Cross platform compatible example using the <literal>%e</literal> modifier</title> <programlisting role="php"> <![CDATA[ <?php // Jan 1: results in: '%e%1%' (%%, e, %%, %e, %%) $format = '%%e%%%e%%'; // Check for Windows to find and replace the %e // modifier correctly if (strtoupper(substr(PHP_OS, 0, 3)) == 'WIN') { $format = preg_replace('#(?<!%)((?:%%)*)%e#', '\1%#d', $format); } echo strftime($format); ?> ]]> </programlisting> </example> </para> <para> <example> <title>Display all known and unknown formats.</title> <programlisting role="php"> <![CDATA[ <?php // Describe the formats. $strftimeFormats = array( 'A' => 'A full textual representation of the day', 'B' => 'Full month name, based on the locale', 'C' => 'Two digit representation of the century (year divided by 100, truncated to an integer)', 'D' => 'Same as "%m/%d/%y"', 'E' => '', 'F' => 'Same as "%Y-%m-%d"', 'G' => 'The full four-digit version of %g', 'H' => 'Two digit representation of the hour in 24-hour format', 'I' => 'Two digit representation of the hour in 12-hour format', 'J' => '', 'K' => '', 'L' => '', 'M' => 'Two digit representation of the minute', 'N' => '', 'O' => '', 'P' => 'lower-case "am" or "pm" based on the given time', 'Q' => '', 'R' => 'Same as "%H:%M"', 'S' => 'Two digit representation of the second', 'T' => 'Same as "%H:%M:%S"', 'U' => 'Week number of the given year, starting with the first Sunday as the first week', 'V' => 'ISO-8601:1988 week number of the given year, starting with the first week of the year with at least 4 weekdays, with Monday being the start of the week', 'W' => 'A numeric representation of the week of the year, starting with the first Monday as the first week', 'X' => 'Preferred time representation based on locale, without the date', 'Y' => 'Four digit representation for the year', 'Z' => 'The time zone offset/abbreviation option NOT given by %z (depends on operating system)', 'a' => 'An abbreviated textual representation of the day', 'b' => 'Abbreviated month name, based on the locale', 'c' => 'Preferred date and time stamp based on local', 'd' => 'Two-digit day of the month (with leading zeros)', 'e' => 'Day of the month, with a space preceding single digits', 'f' => '', 'g' => 'Two digit representation of the year going by ISO-8601:1988 standards (see %V)', 'h' => 'Abbreviated month name, based on the locale (an alias of %b)', 'i' => '', 'j' => 'Day of the year, 3 digits with leading zeros', 'k' => 'Hour in 24-hour format, with a space preceding single digits', 'l' => 'Hour in 12-hour format, with a space preceding single digits', 'm' => 'Two digit representation of the month', 'n' => 'A newline character ("\n")', 'o' => '', 'p' => 'UPPER-CASE "AM" or "PM" based on the given time', 'q' => '', 'r' => 'Same as "%I:%M:%S %p"', 's' => 'Unix Epoch Time timestamp', 't' => 'A Tab character ("\t")', 'u' => 'ISO-8601 numeric representation of the day of the week', 'v' => '', 'w' => 'Numeric representation of the day of the week', 'x' => 'Preferred date representation based on locale, without the time', 'y' => 'Two digit representation of the year', 'z' => 'Either the time zone offset from UTC or the abbreviation (depends on operating system)', '%' => 'A literal percentage character ("%")', ); // Results. $strftimeValues = array(); // Evaluate the formats whilst suppressing any errors. foreach($strftimeFormats as $format => $description){ if (False !== ($value = @strftime("%{$format}"))){ $strftimeValues[$format] = $value; } } // Find the longest value. $maxValueLength = 2 + max(array_map('strlen', $strftimeValues)); // Report known formats. foreach($strftimeValues as $format => $value){ echo "Known format : '{$format}' = ", str_pad("'{$value}'", $maxValueLength), " ( {$strftimeFormats[$format]} )\n"; } // Report unknown formats. foreach(array_diff_key($strftimeFormats, $strftimeValues) as $format => $description){ echo "Unknown format : '{$format}' ", str_pad(' ', $maxValueLength), ($description ? " ( {$description} )" : ''), "\n"; } ?> ]]> </programlisting> &example.outputs.similar; <screen> <![CDATA[ Known format : 'A' = 'Friday' ( A full textual representation of the day ) Known format : 'B' = 'December' ( Full month name, based on the locale ) Known format : 'H' = '11' ( Two digit representation of the hour in 24-hour format ) Known format : 'I' = '11' ( Two digit representation of the hour in 12-hour format ) Known format : 'M' = '24' ( Two digit representation of the minute ) Known format : 'S' = '44' ( Two digit representation of the second ) Known format : 'U' = '48' ( Week number of the given year, starting with the first Sunday as the first week ) Known format : 'W' = '48' ( A numeric representation of the week of the year, starting with the first Monday as the first week ) Known format : 'X' = '11:24:44' ( Preferred time representation based on locale, without the date ) Known format : 'Y' = '2010' ( Four digit representation for the year ) Known format : 'Z' = 'GMT Standard Time' ( The time zone offset/abbreviation option NOT given by %z (depends on operating system) ) Known format : 'a' = 'Fri' ( An abbreviated textual representation of the day ) Known format : 'b' = 'Dec' ( Abbreviated month name, based on the locale ) Known format : 'c' = '12/03/10 11:24:44' ( Preferred date and time stamp based on local ) Known format : 'd' = '03' ( Two-digit day of the month (with leading zeros) ) Known format : 'j' = '337' ( Day of the year, 3 digits with leading zeros ) Known format : 'm' = '12' ( Two digit representation of the month ) Known format : 'p' = 'AM' ( UPPER-CASE "AM" or "PM" based on the given time ) Known format : 'w' = '5' ( Numeric representation of the day of the week ) Known format : 'x' = '12/03/10' ( Preferred date representation based on locale, without the time ) Known format : 'y' = '10' ( Two digit representation of the year ) Known format : 'z' = 'GMT Standard Time' ( Either the time zone offset from UTC or the abbreviation (depends on operating system) ) Known format : '%' = '%' ( A literal percentage character ("%") ) Unknown format : 'C' ( Two digit representation of the century (year divided by 100, truncated to an integer) ) Unknown format : 'D' ( Same as "%m/%d/%y" ) Unknown format : 'E' Unknown format : 'F' ( Same as "%Y-%m-%d" ) Unknown format : 'G' ( The full four-digit version of %g ) Unknown format : 'J' Unknown format : 'K' Unknown format : 'L' Unknown format : 'N' Unknown format : 'O' Unknown format : 'P' ( lower-case "am" or "pm" based on the given time ) Unknown format : 'Q' Unknown format : 'R' ( Same as "%H:%M" ) Unknown format : 'T' ( Same as "%H:%M:%S" ) Unknown format : 'V' ( ISO-8601:1988 week number of the given year, starting with the first week of the year with at least 4 weekdays, with Monday being the start of the week ) Unknown format : 'e' ( Day of the month, with a space preceding single digits ) Unknown format : 'f' Unknown format : 'g' ( Two digit representation of the year going by ISO-8601:1988 standards (see %V) ) Unknown format : 'h' ( Abbreviated month name, based on the locale (an alias of %b) ) Unknown format : 'i' Unknown format : 'k' ( Hour in 24-hour format, with a space preceding single digits ) Unknown format : 'l' ( Hour in 12-hour format, with a space preceding single digits ) Unknown format : 'n' ( A newline character ("\n") ) Unknown format : 'o' Unknown format : 'q' Unknown format : 'r' ( Same as "%I:%M:%S %p" ) Unknown format : 's' ( Unix Epoch Time timestamp ) Unknown format : 't' ( A Tab character ("\t") ) Unknown format : 'u' ( ISO-8601 numeric representation of the day of the week ) Unknown format : 'v' ]]> </screen> </example> </para> </refsect1> <refsect1 role="notes"> &reftitle.notes; <note> <simpara> %G and %V, which are based on ISO 8601:1988 week numbers can give unexpected (albeit correct) results if the numbering system is not thoroughly understood. See %V examples in this manual page. </simpara> </note> </refsect1> <refsect1 role="seealso"> &reftitle.seealso; <para> <simplelist> <member><link xlink:href="&url.strftime.format.designer;">Online strftime() format design tool</link></member> <member><function>setlocale</function></member> <member><function>mktime</function></member> <member><function>strptime</function></member> <member><function>gmstrftime</function></member> <member><link xlink:href="&spec.strftime;">Open Group specification of <function>strftime</function></link></member> </simplelist> </para> </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 -->