php-doc-en/reference/datetime/functions/strtotime.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.19 $ -->
<!-- splitted from ./en/functions/datetime.xml, last change in rev 1.8 -->
<refentry id="function.strtotime">
 <refnamediv>
  <refname>strtotime</refname>
  <refpurpose>Parse about any English textual datetime description into a Unix timestamp</refpurpose>
 </refnamediv>
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>int</type><methodname>strtotime</methodname>
   <methodparam><type>string</type><parameter>time</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>now</parameter></methodparam>
  </methodsynopsis>
  <simpara>
   The function expects to be given a string containing a US English date
   format and will try to parse that format into a Unix timestamp (the
   number of seconds since January 1 1970 00:00:00 GMT), relative
   to the timestamp given in <parameter>now</parameter>, or the current time
   if none is supplied.
  </simpara>
  <para>
   This function will use the <envar>TZ</envar> environment variable (if
   available) to calculate the timestamp. Since PHP 5.1.0 there are easier
   ways to define the timezone that is used across all date/time functions.
   That process is explained in the
   <function>date_default_timezone_get</function> function page.
  </para>
  <note>
   <para>
    If the number of the year is specified in a two digit format, the values
    between 0-69 are mapped to 2000-2069 and 70-100 to 1970-2000.
   </para>
  </note>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>time</parameter></term>
     <listitem>
      <para>
       The string to parse, according to the GNU <ulink
        url="&url.gnu.man.date-input;">Date Input Formats</ulink>
       syntax. Before PHP 5.0, microseconds weren't allowed in the time, since
       PHP 5.0 they are allowed but ignored.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>now</parameter></term>
     <listitem>
      <para>
       The timestamp used to calculate the returned value.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns a timestamp on success, &false; otherwise. Previous to PHP 5.1.0,
   this function would return <literal>-1</literal> on failure.
  </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>
      <row>
       <entry>5.1.0</entry>
       <entry>
        It now returns &false; on failure, instead of <literal>-1</literal>.
       </entry>
      </row>

      &date.timezone.errors.changelog;

     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>A <function>strtotime</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
echo strtotime("now"), "\n";
echo strtotime("10 September 2000"), "\n";
echo strtotime("+1 day"), "\n";
echo strtotime("+1 week"), "\n";
echo strtotime("+1 week 2 days 4 hours 2 seconds"), "\n";
echo strtotime("next Thursday"), "\n";
echo strtotime("last Monday"), "\n";
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Checking for failure</title>
    <programlisting role="php">
<![CDATA[
<?php
$str = 'Not Good';

// previous to PHP 5.1.0 you would compare with -1, instead of false
if (($timestamp = strtotime($str)) === false) {
    echo "The string ($str) is bogus";
} else {
    echo "$str == " . date('l dS of F Y h:i:s A', $timestamp);
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <warning>
   <para>
    In PHP 5 up to 5.0.2, <literal>"now"</literal> and other relative times
    are wrongly computed from today's midnight. It differs from other
    versions where it is correctly computed from current time.
   </para>
  </warning>
  <warning>
   <para>
    In PHP versions prior to 4.4, <literal>"next"</literal> is incorrectly
    computed as +2. A typical solution to this is to use
    <literal>"+1"</literal>.
   </para>
  </warning>
  <note>
   <para>
    The valid range of a timestamp is typically from Fri, 13 Dec
    1901 20:45:54 GMT to Tue, 19 Jan 2038 03:14:07 GMT. (These are
    the dates that correspond to the minimum and maximum values for
    a 32-bit signed integer.)
    Additionally, not all platforms support negative timestamps, therefore
    your date range may be limited to no earlier than the Unix epoch. This
    means that e.g. dates prior to Jan 1, 1970 will not work on Windows,
    some Linux distributions, and a few other operating systems. PHP 5.1.0 and
    newer versions overcome this limitation though.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>strptime</function></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:"../../../../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
-->