date.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d94400847cec608f93830aa85e0761b97d7cb9bf Maintainer: hirokawa Status: ready -->
<!-- CREDITS: shimooka,takagi,mumumu -->
<refentry xml:id="function.date" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>date</refname>
  <refpurpose>Unixタイムスタンプを書式化する</refpurpose>
 </refnamediv>
  
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>date</methodname>
   <methodparam><type>string</type><parameter>format</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>timestamp</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   指定された引数 <parameter>timestamp</parameter>
   (Unixタイムスタンプ) を、与えられた
   フォーマット文字列によりフォーマットし、日付文字列を返します。
   タイムスタンプが与えられない場合は、現在の時刻が使われます。
   つまり <parameter>timestamp</parameter> はオプションであり
   そのデフォルト値は <function>time</function> の値です。
  </para>
  <warning>
   <para>
    Unixタイムスタンプはタイムゾーンを処理しません。
    タイムゾーン情報が付加された日付/時刻の情報を書式化するには、
    <classname>DateTimeImmutable</classname> クラスや、
    <methodname>DateTimeInterface::format</methodname> を使って下さい。
   </para>
  </warning>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   <varlistentry>
    <term><parameter>format</parameter></term>
    <listitem>
     <para>
      <methodname>DateTimeInterface::format</methodname> が受け入れるフォーマット。
     </para>
      <note>
       <simpara>
        <function>date</function> 関数は、マイクロ秒については常に
        <literal>000000</literal> を生成します。
        というのも、この関数が受け取るパラメータは int 型だからです。
        一方 <classname>DateTimeInterface</classname> 型のオブジェクトをマイクロ秒つきで作成した場合は、
        <methodname>DateTimeInterface::format</methodname> はマイクロ秒にも対応しています。
       </simpara>
      </note>
    </listitem>
   </varlistentry>
   &date.timestamp.description;
  </variablelist>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   フォーマットされた日付を表す文字列を返します。
  </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>8.0.0</entry>
       <entry>
        <parameter>timestamp</parameter> は、nullable になりました。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>date</function> の例</title>
    <programlisting role="php">
<![CDATA[
<?php
// 使用するデフォルトのタイムゾーンを指定します。
date_default_timezone_set('UTC');


// 結果は、たとえば Monday のようになります。
echo date("l");

// 結果は、たとえば Monday 8th of August 2005 03:12:46 PM のようになります。
echo date('l jS \of F Y h:i:s A');

// 結果は July 1, 2000 is on a Saturday となります。
echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000));

/* 書式指定パラメータに、定数を使用します。 */
// 結果は、たとえば Wed, 25 Sep 2013 15:28:57 -0700 のようになります。
echo date(DATE_RFC2822);

// 結果は、たとえば 2000-07-01T00:00:00+00:00 のようになります。
echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000));
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   前にバックスラッシュを付けてエスケープすることにより、
   フォーマット文字列として認識される文字が展開されることを防止することができます。
   バックスラッシュ付きの文字は既に特別なシーケンスであり、
   バックスラッシュもエスケープすることが必要となる可能性があります。
   <example>
    <title><function>date</function> の文字をエスケープする</title>
    <programlisting role="php">
<![CDATA[
<?php
// Wednesday the 15th のように出力
echo date('l \t\h\e jS');
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <function>date</function> と <function>mktime</function>
   の両方を用いて、未来または過去の日付を知ることができます。
   <example>
    <title><function>date</function> と <function>mktime</function> の例</title>
    <programlisting role="php">
<![CDATA[
<?php
$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>
   <note>
    <para>
     サマータイムがあるため、日付や月の秒数を単純にタイムスタンプに
     可減算するよりもより信頼性があります。
    </para>
   </note>
  </para>
  <para>
   <function>date</function> フォーマットのいくつかの例を示します。
   現在の実装で特別な意味がある文字や今後の PHP のバージョンで意味が
   割り付けられるであろう文字については、望ましくない結果を避けるために
   エスケープする必要があることに注意してください。エスケープを
   する際には、改行文字 \n のような文字を回避するために
   シングルクォートを使用してください。
   <example>
    <title><function>date</function> のフォーマット指定</title>
    <programlisting role="php">
<![CDATA[
<?php
// 今日は March 10th, 2001, 5:16:18 pm であり、
// またタイムゾーンは Mountain Standard Time (MST) であるものとします

$today = date("F j, Y, g:i a");                 // March 10, 2001, 5:16 pm
$today = date("m.d.y");                         // 03.10.01
$today = date("j, n, Y");                       // 10, 3, 2001
$today = date("Ymd");                           // 20010310
$today = date('h-i-s, j-m-y, it is w Day');     // 05-16-18, 10-03-01, 1631 1618 6 Satpm01
$today = date('\i\t \i\s \t\h\e jS \d\a\y.');   // it is the 10th day.
$today = date("D M j G:i:s T Y");               // Sat Mar 10 17:16:18 MST 2001
$today = date('H:m:s \m \i\s\ \m\o\n\t\h');     // 17:03:18 m is month
$today = date("H:i:s");                         // 17:16:18
$today = date("Y-m-d H:i:s");                   // 2001-03-10 17:16:18 (MySQL の DATETIME フォーマット)
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   他の言語で日付をフォーマットする用途には、
   <function>date</function> のかわりに
   <methodname>IntlDateFormatter::format</methodname>
   が使えます。
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    日付の文字列表現からタイムスタンプを生成するには、
    <function>strtotime</function> が使用できるでしょう。
    さらに、いくつかのデータベースは（MySQL の
    <link xlink:href="&url.mysql.docs.date;">UNIX_TIMESTAMP</link> 関数の
    ような）日付フォーマットからタイムスタンプへの変換関数を有しています。
   </para>
  </note>
  <tip>
   <para>
    <varname>$_SERVER['REQUEST_TIME']</varname>
    によって、リクエスト開始時のタイムスタンプが取得できます。
   </para>
  </tip>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><methodname>DateTimeImmutable::__construct</methodname></member>
    <member><methodname>DateTimeInterface::format</methodname></member>
    <member><function>gmdate</function></member>
    <member><function>idate</function></member>
    <member><function>getdate</function></member>
    <member><function>getlastmod</function></member>
    <member><function>mktime</function></member>
    <member><methodname>IntlDateFormatter::format</methodname></member>
    <member><function>time</function></member>
    <member><link linkend="datetimeinterface.constants.types">定義済みの定数</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
-->