mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-15 16:38:54 +00:00
abffc3bfab
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@12656 c90b9560-bf6c-de11-be94-00142212c4b1
469 lines
19 KiB
Text
469 lines
19 KiB
Text
<reference id="ref.datetime">
|
|
<title>Date and Time functions</title>
|
|
<titleabbrev>Date/time</titleabbrev>
|
|
|
|
<refentry id="function.checkdate">
|
|
<refnamediv>
|
|
<refname>checkdate</refname>
|
|
<refpurpose>validate a date/time</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>int <function>checkdate</function></funcdef>
|
|
<paramdef>int <parameter>month</parameter></paramdef>
|
|
<paramdef>int <parameter>day</parameter></paramdef>
|
|
<paramdef>int <parameter>year</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns true if the date given is valid; otherwise returns false.
|
|
Checks the validity of the date formed by the arguments. A date is
|
|
considered valid if:
|
|
<itemizedlist>
|
|
<listitem><simpara>
|
|
year is between 0 and 32767 inclusive
|
|
</simpara></listitem>
|
|
<listitem><simpara>
|
|
month is between 1 and 12 inclusive
|
|
</simpara></listitem>
|
|
<listitem><simpara>
|
|
day is within the allowed number of days for the given month.
|
|
Leap years are taken into consideration.
|
|
</simpara></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.date">
|
|
<refnamediv>
|
|
<refname>date</refname>
|
|
<refpurpose>format a local time/date</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>string <function>date</function></funcdef>
|
|
<paramdef>string <parameter>format</parameter></paramdef>
|
|
<paramdef>int
|
|
<parameter>
|
|
<optional>timestamp</optional>
|
|
</parameter>
|
|
</paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns a string formatted according to the given format string
|
|
using the given <parameter>timestamp</parameter> or the current
|
|
local time if no timestamp is given.
|
|
|
|
<para>
|
|
The following characters are recognized in the format string:
|
|
<itemizedlist>
|
|
<listitem><simpara>a - "am" or "pm"</simpara></listitem>
|
|
<listitem><simpara>A - "AM" or "PM"</simpara></listitem>
|
|
<listitem><simpara>d - day of the month, 2 digits with leading zeros; i.e. "01" to "31"</simpara></listitem>
|
|
<listitem><simpara>D - day of the week, textual, 3 letters; i.e. "Fri"</simpara></listitem>
|
|
<listitem><simpara>F - month, textual, long; i.e. "January"</simpara></listitem>
|
|
<listitem><simpara>h - hour, 12-hour format; i.e. "01" to "12"</simpara></listitem>
|
|
<listitem><simpara>H - hour, 24-hour format; i.e. "00" to "23"</simpara></listitem>
|
|
<listitem><simpara>g - hour, 12-hour format without leading zeros; i.e. "1" to "12"</simpara></listitem>
|
|
<listitem><simpara>G - hour, 24-hour format without leading zeros; i.e. "0" to "23"</simpara></listitem>
|
|
<listitem><simpara>i - minutes; i.e. "00" to "59"</simpara></listitem>
|
|
<listitem><simpara>j - day of the month without leading zeros; i.e. "1" to "31"</simpara></listitem>
|
|
<listitem><simpara>l (lowercase 'L') - day of the week, textual, long; i.e. "Friday"</simpara></listitem>
|
|
<listitem><simpara>L - boolean for whether it is a leap year; i.e. "0" or "1"</simpara></listitem>
|
|
<listitem><simpara>m - month; i.e. "01" to "12"</simpara></listitem>
|
|
<listitem><simpara>n - month without leading zeros; i.e. "1" to "12"</simpara></listitem>
|
|
<listitem><simpara>M - month, textual, 3 letters; i.e. "Jan"</simpara></listitem>
|
|
<listitem><simpara>s - seconds; i.e. "00" to "59"</simpara></listitem>
|
|
<listitem><simpara>S - English ordinal suffix, textual, 2 characters; i.e. "th", "nd"</simpara></listitem>
|
|
<listitem><simpara>t - number of days in the given month; i.e. "28" to "31"</simpara></listitem>
|
|
<listitem><simpara>U - seconds since the epoch</simpara></listitem>
|
|
<listitem><simpara>w - day of the week, numeric, i.e. "0" (Sunday) to "6" (Saturday)</simpara></listitem>
|
|
<listitem><simpara>Y - year, 4 digits; i.e. "1999"</simpara></listitem>
|
|
<listitem><simpara>y - year, 2 digits; i.e. "99"</simpara></listitem>
|
|
<listitem><simpara>z - day of the year; i.e. "0" to "365"</simpara></listitem>
|
|
<listitem><simpara>Z - timezone offset in seconds (i.e. "-43200" to "43200")</simpara></listitem>
|
|
</itemizedlist>
|
|
Unrecognized characters in the format string will be printed as-is.
|
|
The "Z" format will always return "0" when using <function>gmdate()</function>.
|
|
|
|
<example>
|
|
<title><function>date</function> example</title>
|
|
<programlisting role="php">
|
|
print (date("l dS of F Y h:i:s A"));
|
|
print ("July 1, 2000 is on a " . date("l", mktime(0,0,0,7,1,2000)));
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
It is possible to use <function>date</function> and
|
|
<function>mktime</function> together to find dates in the future
|
|
or the past.
|
|
|
|
<example>
|
|
<title>
|
|
<function>date</function> and <function>mktime</function> example
|
|
</title>
|
|
<programlisting>
|
|
$tomorrow = mktime(0,0,0,date("m") ,date("d")+1,date("Y"));
|
|
$lastmonth = mktime(0,0,0,date("m")-1,date("d"), date("Y"));
|
|
$nextyear = mktime(0,0,0,date("m"), date("d", date("Y")+1);
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
|
|
<para>
|
|
To format dates in other languages, you should use the
|
|
<function>setlocale</function> and <function>strftime</function>
|
|
functions.
|
|
</para>
|
|
|
|
<para>
|
|
See also <function>gmdate</function> and
|
|
<function>mktime</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.getdate">
|
|
<refnamediv>
|
|
<refname>getdate</refname>
|
|
<refpurpose>get date/time information</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>array <function>getdate</function></funcdef>
|
|
<paramdef>int <parameter>timestamp</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns an associative array containing the date information of the
|
|
timestamp as the following array elements:
|
|
<itemizedlist>
|
|
<listitem><simpara>"seconds" - seconds</simpara></listitem>
|
|
<listitem><simpara>"minutes" - minutes</simpara></listitem>
|
|
<listitem><simpara>"hours" - hours</simpara></listitem>
|
|
<listitem><simpara>"mday" - day of the month</simpara></listitem>
|
|
<listitem><simpara>"wday" - day of the week, numeric</simpara></listitem>
|
|
<listitem><simpara>"mon" - month, numeric</simpara></listitem>
|
|
<listitem><simpara>"year" - year, numeric</simpara></listitem>
|
|
<listitem><simpara>"yday" - day of the year, numeric; i.e. "299"</simpara></listitem>
|
|
<listitem><simpara>"weekday" - day of the week, textual, full; i.e.
|
|
"Friday"</simpara></listitem>
|
|
<listitem><simpara>"month" - month, textual, full; i.e. "January"</simpara></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.gettimeofday">
|
|
<refnamediv>
|
|
<refname>gettimeofday</refname>
|
|
<refpurpose>get current time</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>array <function>gettimeofday</function></funcdef>
|
|
<paramdef>void</paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
This is an interface to gettimeofday(2). It returns an
|
|
associative array containing the data returned from the
|
|
system call.
|
|
<itemizedlist>
|
|
<listitem><simpara>"sec" - seconds</simpara></listitem>
|
|
<listitem><simpara>"usec" - microseconds</simpara></listitem>
|
|
<listitem><simpara>"minuteswest" - minutes west of Greenwich</simpara></listitem>
|
|
<listitem><simpara>"dsttime" - type of dst correction</simpara></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.gmdate">
|
|
<refnamediv>
|
|
<refname>gmdate</refname>
|
|
<refpurpose>format a GMT/CUT date/time</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>string <function>gmdate</function></funcdef>
|
|
<paramdef>string <parameter>format</parameter></paramdef>
|
|
<paramdef>int <parameter>timestamp</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
Identical to the <function>date</function>
|
|
function except that the time returned is Greenwich Mean Time
|
|
(GMT). For example, when run in Finland (GMT +0200), the first
|
|
line below prints "Jan 01 1998 00:00:00", while the second prints
|
|
"Dec 31 1997 22:00:00".
|
|
<example>
|
|
<title><function>gmdate</function> example</title>
|
|
<programlisting role="php">
|
|
echo date( "M d Y H:i:s",mktime(0,0,0,1,1,1998) );
|
|
echo gmdate( "M d Y H:i:s",mktime(0,0,0,1,1,1998) );
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>date</function>,
|
|
<function>mktime</function> and <function>gmmktime</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
|
|
<refentry id="function.gmmktime">
|
|
<refnamediv>
|
|
<refname>gmmktime</refname>
|
|
<refpurpose>get UNIX timestamp for a GMT date</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>int <function>gmmktime</function></funcdef>
|
|
<paramdef>int <parameter>hour</parameter></paramdef>
|
|
<paramdef>int <parameter>minute</parameter></paramdef>
|
|
<paramdef>int <parameter>second</parameter></paramdef>
|
|
<paramdef>int <parameter>month</parameter></paramdef>
|
|
<paramdef>int <parameter>day</parameter></paramdef>
|
|
<paramdef>int <parameter>year</parameter></paramdef>
|
|
<paramdef>int <parameter><optional>is_dst</optional></parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
Identical to <function>mktime</function> except the passed parameters
|
|
represents a GMT date.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.gmstrftime">
|
|
<refnamediv>
|
|
<refname>gmstrftime</refname>
|
|
<refpurpose>format a GMT/CUT time/date according to locale settings</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>string <function>gmstrftime</function></funcdef>
|
|
<paramdef>string <parameter>format</parameter></paramdef>
|
|
<paramdef>int <parameter>timestamp</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
Behaves the same as <function>strftime</function> except that the
|
|
time returned is Greenwich Mean Time (GMT). For example, when run
|
|
in Eastern Standard Time (GMT -0500), the first line below prints
|
|
"Dec 31 1998 20:00:00", while the second prints "Jan 01 1999 01:00:00".
|
|
<example>
|
|
<title><function>gmstrftime</function> example</title>
|
|
<programlisting role="php">
|
|
setlocale ('LC_TIME','en_US');
|
|
echo strftime ("%b %d %Y %H:%M:%S",mktime(20,0,0,12,31,98))."\n";
|
|
echo gmstrftime ("%b %d %Y %H:%M:%S",mktime(20,0,0,12,31,98))."\n";
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>strftime</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.microtime">
|
|
<refnamediv>
|
|
<refname>microtime</refname>
|
|
<refpurpose>return current UNIX timestamp with microseconds</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>string <function>microtime</function></funcdef>
|
|
<void>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns the string "msec sec" where sec is the current time
|
|
measured in the number of seconds since the Unix Epoch (0:00:00
|
|
January 1, 1970 GMT), and msec is the microseconds part. This
|
|
function is only available on operating systems that support the
|
|
gettimeofday() system call.
|
|
</para>
|
|
<para>
|
|
See also <function>time</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.mktime">
|
|
<refnamediv>
|
|
<refname>mktime</refname>
|
|
<refpurpose>get UNIX timestamp for a date</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>int <function>mktime</function></funcdef>
|
|
<paramdef>int <parameter>hour</parameter></paramdef>
|
|
<paramdef>int <parameter>minute</parameter></paramdef>
|
|
<paramdef>int <parameter>second</parameter></paramdef>
|
|
<paramdef>int <parameter>month</parameter></paramdef>
|
|
<paramdef>int <parameter>day</parameter></paramdef>
|
|
<paramdef>int <parameter>year</parameter></paramdef>
|
|
<paramdef>int <parameter><optional>is_dst</optional></parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
<emphasis>Warning:</emphasis> Note the strange order of
|
|
arguments, which differs from the order of arguments in
|
|
a regular UNIX mktime() call and which does not lend
|
|
itself well to leaving out parameters from right to left
|
|
(see below). It is a common error to mix these values up
|
|
in a script.
|
|
<para>
|
|
Returns the Unix timestamp corresponding to the arguments
|
|
given. This timestamp is a long integer containing the number of
|
|
seconds between the Unix Epoch (January 1 1970) and the time
|
|
specified.
|
|
</para><para>
|
|
Arguments may be left out in order from right to left; any
|
|
arguments thus omitted will be set to the current value according
|
|
to the local date and time.
|
|
</para><para>
|
|
<parameter>is_dst</parameter> can be set to 1 if the time
|
|
is during daylight savings time, 0 if it is not, or -1 (the
|
|
default) if it is unknown whether the time is within daylight
|
|
savings time or not.
|
|
</para>
|
|
<note>
|
|
<para><parameter>is_dst</parameter> was added in 3.0.10.</para>
|
|
</note>
|
|
<para>
|
|
<function>mktime</function> is useful for doing date arithmetic and
|
|
validation, as it will automatically calculate the correct value
|
|
for out-of-range input. For example, each of the following lines
|
|
produces the string "Jan-01-1998".
|
|
<example>
|
|
<title><function>mktime</function> example</title>
|
|
<programlisting>
|
|
echo date( "M-d-Y", mktime(0,0,0,12,32,1997) );
|
|
echo date( "M-d-Y", mktime(0,0,0,13,1,1997) );
|
|
echo date( "M-d-Y", mktime(0,0,0,1,1,1998) );
|
|
</programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
See also <function>date</function> and <function>time</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.strftime">
|
|
<refnamediv>
|
|
<refname>strftime</refname>
|
|
<refpurpose>format a local time/date according to locale settings
|
|
</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>string <function>strftime</function></funcdef>
|
|
<paramdef>string <parameter>format</parameter></paramdef>
|
|
<paramdef>int <parameter>timestamp</parameter></paramdef>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns a string formatted according to the given format string
|
|
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>
|
|
The following conversion specifiers are recognized in the format string:
|
|
<itemizedlist>
|
|
<listitem><simpara>%a - abbreviated weekday name according to the current locale</simpara></listitem>
|
|
<listitem><simpara>%A - full weekday name according to the current locale</simpara></listitem>
|
|
<listitem><simpara>%b - abbreviated month name according to the current locale</simpara></listitem>
|
|
<listitem><simpara>%B - full month name according to the current locale</simpara></listitem>
|
|
<listitem><simpara>%c - preferred date and time representation for the current locale</simpara></listitem>
|
|
<listitem><simpara>%d - day of the month as a decimal number (range 00 to 31)</simpara></listitem>
|
|
<listitem><simpara>%H - hour as a decimal number using a 24-hour clock (range 00 to 23)</simpara></listitem>
|
|
<listitem><simpara>%I - hour as a decimal number using a 12-hour clock (range 01 to 12)</simpara></listitem>
|
|
<listitem><simpara>%j - day of the year as a decimal number (range 001 to 366)</simpara></listitem>
|
|
<listitem><simpara>%m - month as a decimal number (range 1 to 12)</simpara></listitem>
|
|
<listitem><simpara>%M - minute as a decimal number</simpara></listitem>
|
|
<listitem><simpara>%p - either `am' or `pm' according to the given time value, or the corresponding strings for the current locale</simpara></listitem>
|
|
<listitem><simpara>%S - second as a decimal number</simpara></listitem>
|
|
<listitem><simpara>%U - week number of the current year as a decimal number, starting with the first Sunday as the first day of the first week</simpara></listitem>
|
|
<listitem><simpara>%W - week number of the current year as a decimal number, starting with the first Monday as the first day of the first week</simpara></listitem>
|
|
<listitem><simpara>%w - day of the week as a decimal, Sunday being 0</simpara></listitem>
|
|
<listitem><simpara>%x - preferred date representation for the current locale without the time</simpara></listitem>
|
|
<listitem><simpara>%X - preferred time representation for the current locale without the date</simpara></listitem>
|
|
<listitem><simpara>%y - year as a decimal number without a century (range 00 to 99)</simpara></listitem>
|
|
<listitem><simpara>%Y - year as a decimal number including the century</simpara></listitem>
|
|
<listitem><simpara>%Z - time zone or name or abbreviation</simpara></listitem>
|
|
<listitem><simpara>%% - a literal `%' character</simpara></listitem>
|
|
</itemizedlist>
|
|
|
|
<example>
|
|
<title><function>strftime</function> example</title>
|
|
<programlisting role="php">
|
|
setlocale ("LC_TIME", "C");
|
|
print(strftime("%A in Finnish is "));
|
|
setlocale ("LC_TIME", "fi_FI");
|
|
print(strftime("%A, in French "));
|
|
setlocale ("LC_TIME", "fr_CA");
|
|
print(strftime("%A and in German "));
|
|
setlocale ("LC_TIME", "de_DE");
|
|
print(strftime("%A.\n"));
|
|
</programlisting>
|
|
</example>
|
|
This example works if you have the respective locales installed
|
|
in your system.
|
|
|
|
<para>
|
|
See also <function>setlocale</function> and
|
|
<function>mktime</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
<refentry id="function.time">
|
|
<refnamediv>
|
|
<refname>time</refname>
|
|
<refpurpose>return current UNIX timestamp</refpurpose>
|
|
</refnamediv>
|
|
<refsect1>
|
|
<title>Description</title>
|
|
<funcsynopsis>
|
|
<funcdef>int <function>time</function></funcdef>
|
|
<void>
|
|
</funcsynopsis>
|
|
<para>
|
|
Returns the current time measured in the number of seconds since
|
|
the Unix Epoch (January 1 1970 00:00:00 GMT).
|
|
</para><para>
|
|
See also <function>date</function>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|
|
|
|
</reference>
|
|
|
|
<!-- 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
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|