<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $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</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) though <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>%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 preceeding 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>Either the time zone offset from UTC or the abbreviation (depends
on operating system)</entry>
<entry>Example: <literal>-0500</literal> or <literal>EST</literal> for Eastern Time</entry>
</row>
<row>
<entry><literal>%Z</literal></entry>
<entry>The time zone offset/abbreviation option NOT given by %z (depends
on operating system)</entry>
<entry>Example: <literal>-0500</literal> or <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 local</entry>
<entry>Example: <literal>Tue Feb 5 00:45:10 2009</literal> for
February 4, 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, %u may not function as described in this manual.
</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;
</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>
<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>
</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><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
-->