# date

(PHP 4, PHP 5, PHP 7)

date — 格式化一个本地时间／日期

### 说明

date ( string `$format` [, int `$timestamp` ] ) : string

返回将整数 `timestamp` 按照给定的格式字串而产生的字符串。如果没有给出时间戳则使用本地当前时间。换句话说，`timestamp` 是可选的，默认值为 time()。

Tip

自 PHP 5.1.1 起有几个有用的常量可用作标准的日期／时间格式来指定 `format` 参数。

Tip

自 PHP 5.1 起在 $_SERVER['REQUEST_TIME'] 中保存了发起该请求时刻的时间戳。

> Note:

> 有效的时间戳典型范围是格林威治时间 1901 年 12 月 13 日 20:45:54 到 2038 年 1 月 19 日 03:14:07。（此范围符合 32 位有符号整数的最小值和最大值）。不过在 PHP 5.1 之前此范围在某些系统（如 Windows）中限制为从 1970 年 1 月 1 日到 2038 年 1 月 19 日。

> Note:

> 要将字符串表达的时间转换成时间戳，应该使用 strtotime()。此外一些数据库有一些函数将其时间格式转换成时间戳（例如 MySQL 的 » UNIX_TIMESTAMP 函数）。

格式字串可以识别以下 `format` 参数的字符串
`format` 字符 | 说明 | 返回值例子
--- | --- | ---
日 | --- | ---
d | 月份中的第几天，有前导零的 2 位数字 | 01 到 31
D | 星期中的第几天，文本表示，3 个字母 | Mon 到 Sun
j | 月份中的第几天，没有前导零 | 1 到 31
l（“L”的小写字母） | 星期几，完整的文本格式 | Sunday 到 Saturday
N | ISO-8601 格式数字表示的星期中的第几天（PHP 5.1.0 新加） | 1（表示星期一）到 7（表示星期天）
S | 每月天数后面的英文后缀，2 个字符 | st，nd，rd 或者 th。可以和 j 一起用
w | 星期中的第几天，数字表示 | 0（表示星期天）到 6（表示星期六）
z | 年份中的第几天 | 0 到 365
星期 | --- | ---
W | ISO-8601 格式年份中的第几周，每周从星期一开始（PHP 4.1.0 新加的） | 例如：42（当年的第 42 周）
月 | --- | ---
F | 月份，完整的文本格式，例如 January 或者 March | January 到 December
m | 数字表示的月份，有前导零 | 01 到 12
M | 三个字母缩写表示的月份 | Jan 到 Dec
n | 数字表示的月份，没有前导零 | 1 到 12
t | 指定的月份有几天 | 28 到 31
年 | --- | ---
L | 是否为闰年 | 如果是闰年为 1，否则为 0
o | ISO-8601 格式年份数字。这和 Y 的值相同，只除了如果 ISO 的星期数（W）属于前一年或下一年，则用那一年。（PHP 5.1.0 新加） | Examples: 1999 or 2003
Y | 4 位数字完整表示的年份 | 例如：1999 或 2003
y | 2 位数字表示的年份 | 例如：99 或 03
时间 | --- | ---
a | 小写的上午和下午值 | am 或 pm
A | 大写的上午和下午值 | AM 或 PM
B | Swatch Internet 标准时 | 000 到 999
g | 小时，12 小时格式，没有前导零 | 1 到 12
G | 小时，24 小时格式，没有前导零 | 0 到 23
h | 小时，12 小时格式，有前导零 | 01 到 12
H | 小时，24 小时格式，有前导零 | 00 到 23
i | 有前导零的分钟数 | 00 到 59>
s | 秒数，有前导零 | 00 到 59>
u | 毫秒 （PHP 5.2.2 新加）。需要注意的是 date() 函数总是返回 000000 因为它只接受 integer 参数， 而 DateTime::format() 才支持毫秒。 | 示例: 654321
时区 | --- | ---
e | 时区标识（PHP 5.1.0 新加） | 例如：UTC，GMT，Atlantic/Azores
I | 是否为夏令时 | 如果是夏令时为 1，否则为 0
O | 与格林威治时间相差的小时数 | 例如：+0200
P | 与格林威治时间（GMT）的差别，小时和分钟之间有冒号分隔（PHP 5.1.3 新加） | 例如：+02:00
T | 本机所在的时区 | 例如：EST，MDT（【译者注】在 Windows 下为完整文本格式，例如“Eastern Standard Time”，中文版会显示“中国标准时间”）。
Z | 时差偏移量的秒数。UTC 西边的时区偏移量总是负的，UTC 东边的时区偏移量总是正的。 | -43200 到 43200
完整的日期／时间 | --- | ---
c | ISO 8601 格式的日期（PHP 5 新加） | 2004-02-12T15:19:21+00:00
r | RFC 822 格式的日期 | 例如：Thu, 21 Dec 2000 16:01:07 +0200
U | 从 Unix 纪元（January 1 1970 00:00:00 GMT）开始至今的秒数 | 参见 time()

格式字串中不能被识别的字符将原样显示。Z 格式在使用 gmdate() 时总是返回 0。

Example #1 date() 例子

    <?php
    // 设定要用的默认时区。自 PHP 5.1 可用
    date_default_timezone_set('UTC');

    // 输出类似：Monday
    echo date("l");

    // 输出类似：Monday 15th of August 2005 03:12:46 PM
    echo date('l dS \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));
    ?>

在格式字串中的字符前加上反斜线来转义可以避免它被按照上表解释。如果加上反斜线后的字符本身就是一个特殊序列，那还要转义反斜线。

Example #2 在 date() 中转义字符

    <?php
    // prints something like: Wednesday the 15th
    echo date("l \\t\h\e jS");
    ?>

可以把 date() 和 mktime() 函数结合使用来得到未来或过去的日期。

Example #3 date() 和 mktime() 例子

    <?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);
    ?>

> Note:

> 由于夏令时的缘故，这种方法比简单地在时间戳上加减一天或者一个月的秒数更可靠。

一些使用 date() 格式化日期的例子。注意要转义所有其它的字符，因为目前有特殊含义的字符会产生不需要的结果，而其余字符在 PHP 将来的版本中可能会被用上。当转义时，注意用单引号以避免类似 \n 的字符变成了换行符。

Example #4 date() 格式举例

    <?php
    // 假定今天是：March 10th, 2001, 5:16:18 pm
    $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 z ');  // 05-16-17, 10-03-01, 1631 1618 6 Fripm01
    $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 15:16:08 MST 2001
    $today = date('H:m:s \m \i\s\ \m\o\n\t\h');     // 17:03:17 m is month
    $today = date("H:i:s");                         // 17:16:17
    $today = date("Y-m-d H:i:s");                   // 2001-03-10 17:16:18 （MySQL DATETIME 格式）
    ?>

要格式化其它语种的日期，应该用 setlocale() 和 strftime() 函数来代替 date()。

参见 getlastmod()，gmdate()，mktime()，strftime() 和 time()。

### 参数

`format`

  输出的日期 string 格式。 参见下文中的 格式化选项。 同时，还可以使用 预定义日期常量 ，例如：常量 `DATE_RSS` 表示格式化字符串 'D, d M Y H:i:s'。

  `format` 参数字符串中可识别下列字符
  `format` 字符 | 描述 | 返回值示例
  --- | --- | ---
  天 | --- | ---
  d | 一个月中的第几天，有前导 0 的 2 位数字 | 从 01 到 31
  D | 3 个字符表示的星期几 | 从 Mon 到 Sun
  j | 一个月中的第几天，无前导 0 | 从 1 到 31
  l (lowercase 'L') | 星期几，英文全称 | 从 Sunday 到 Saturday
  N | ISO-8601 规定的数字表示的星期几（PHP 5.1.0 新加 ） | 从 1 （表示星期一）到 7 （表示星期日）
  S | 一个月中的第几天，带有 2 个字符表示的英语序数词。 | st， nd， rd 或者 th。 可以和 j 联合使用。
  w | 数字表示的星期几 | 从 0 （星期日） 到 6 （星期六）
  z | 一年中的第几天，从 0 开始计数 | 从 0 到 365
  周 | --- | ---
  W | ISO-8601 规范的一年中的第几周，周一视为一周开始。（PHP 4.1.0 新加） | 示例： 42 （本年第42周）
  月 | --- | ---
  F | 月份英文全拼，例如：January 或 March | 从 January 到 December
  m | 带有 0 前导的数字表示的月份 | 从 01 到 12
  M | 3 个字符表示的月份的英文简拼 | 从 Jan 到 Dec
  n | 月份的数字表示，无前导 0 | 1 through 12
  t | 给定月份中包含多少天 | 从 28 到 31
  年 | --- | ---
  L | 是否为闰年 | 如果是闰年，则返回 1，反之返回 0。
  o | ISO-8601 规范的年份，同 Y 格式。有一种情况除外：当 ISO 的周数（W）属于前一年或者后一年时，会返回前一年或者后一年的年份数字表达。 属于前一年或者后一年时，会返回前一年或者后一年的年份数字表达。 （PHP 5.1.0 新加） | 示例：1999 或 2003
  Y | 4 位数字的年份 | 示例：1999 或 2003
  y | 2 位数字的年份 | 示例： 99 或 03
  时间 | --- | ---
  a | 上午还是下午，2 位小写字符 | am 或 pm
  A | 上午还是下午，2 位大写字符 | AM 或 PM
  B | 斯沃琪因特网时间 | 从 000 到 999
  g | 小时，12时制，无前导 0 | 从 1 到 12
  G | 小时，24时制，无前导 0 | 从 0 到 23
  h | 小时，12时制，有前导 0 的 2 位数字 | 从 01 到 12
  H | 小时，24时制，有前导 0 的 2 位数字 | 00 through 23
  i | 分钟，有前导 0 的 2 位数字 | 从 00 到 59
  s | 秒，有前导 0 的 2 位数字 | 从 00 到 59
  u | 毫秒 （PHP 5.2.2 新加） | 示例： 654321
  时区 | --- | ---
  e | 时区标识（PHP 5.1.0 新加） | 示例: UTC, GMT, Atlantic/Azores
  I （大写字母 i） | 是否夏令时 | 如果是夏令时则返回 1，反之返回 0。
  O | 和格林威治时间（GMT）的时差，以小时为单位 | 示例： +0200
  P | 和格林威治时间（GMT）的时差，包括小时和分钟，小时和分钟之间使用冒号（:）分隔（PHP 5.1.3 新加） | 示例： +02:00
  T | 时区缩写 | 示例：EST, MDT ...
  Z | 以秒为单位的时区偏移量。UTC 以西的时区返回负数，UTC 以东的时区返回正数。 | 从 -43200 到 50400
  完整的日期/时间 | --- | ---
  c | ISO 8601 日期及时间（PHP 5 新加） | 2004-02-12T15:19:21+00:00
  r | » RFC 2822 格式的日期和时间 | 示例：Thu, 21 Dec 2000 16:01:07 +0200
  U | 自 1970 年 1 月 1 日 0 时 0 分 0 秒（GMT 时间）以来的时间，以秒为单位 | 参见time()

  格式化字符串中的不可识别字符将原样输出。 当使用 gmdate() 函数时， Z 格式永远返回 0。

  > Note:

  > 由于本函数仅接受 integer 类型的时间戳参数，所以 u 格式仅在使用 date_format() 函数并且使用 date_create() 函数创建时间戳时才是有用的。

`timestamp`

  可选的 `timestamp` 参数是一个 integer 的 Unix 时间戳，如未指定，参数值默认为当前本地时间。也就是说，其值默认为 time() 的返回值。

### 返回值

返回格式化后的日期时间的字符串表达。 如果 `timestamp` 参数不是一个有效数值，则返回 `FALSE` 并引发 `E_WARNING` 级别的错误。

### 错误／异常

在每 次调用日期/时间函数时，如果时区无效则会引发 `E_NOTICE` 错误，如果使用系统设定值或 TZ 环境变量，则会引发 `E_STRICT` 或 `E_WARNING` 消息。参见 date_default_timezone_set()。

### 更新日志

版本 | 说明
--- | ---
5.1.0 | 时间戳的有效取值范围为 GMT 时间的 1901 年 12 月 13 日至 GMT 时间的 2038 年 1 月 19 日。 （32 位有符号整数的取值范围）。 但是，在 PHP 5.1.0 之前的版本，在某些系统（例如 Windows）上有效取值范围为 1970 年 1 月 1 日至 2038 年 1 月 19 日。
5.1.0 | 现在发布 `E_STRICT` 和 `E_NOTICE` 时区错误。
5.1.1 | `format` 参数标准的可用日期/时间格式常量见： 常量

### 范例

Example #5 date() 函数示例

    <?php
    // 设置默认时区。PHP 5.1 之后版本可用
    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));

    /* 使用格式常量 */
    // 输出类似： Mon, 15 Aug 2005 15:12:46 UTC
    echo date(DATE_RFC822);

    // 输出类似：2000-07-01T00:00:00+00:00
    echo date(DATE_ATOM, mktime(0, 0, 0, 7, 1, 2000));
    ?>

可以使用反斜线进行转义来阻止函数解析格式字符串中的可识别字符。 如果反斜线和要转义的字符连在一起依然是一个有效的字符序列，那么需要对 反斜线再次进行转义。

Example #6 对 date() 函数中的格式字符串进行转义

    <?php
    // 输出类似： Wednesday the 15th
    echo date('l \t\h\e jS');
    ?>

可以联合使用 date() 和 mktime() 函数 来构造之前或者之后的日期时间。

Example #7 date() 和 mktime() 联合使用示例

    <?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);
    ?>

> Note:

> 由于存在夏令时时间， 所以此方案相对于直接在时间戳上加/减秒数 要更加可靠。

date() 函数格式化的一些示例。 需要注意的是，即使是对于当前来说并不具有特殊含义的字符， 也要像对待具有特殊含义的字符那样进行转义，以避免函数返回非预期的值。 因为可能在将来的 PHP 版本中，这些字符会被赋予特殊的含义。 进行转义的时候，请确保使用单引号，以避免 \n 被解释为换行符号。

Example #8 date() 函数格式化

    <?php
    // 假设今天是 2001 年 3 月 10 日下午 5 点 16 分 18 秒，
    // 并且位于山区标准时间（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
    ?>

如果需要将日期时间格式化为其他语言，你应该使用 setlocale() 和 strftime() 函数 来替代 date() 函数。

### 注释

> Note:

> 使用 strtotime() 函数将一个字符串表达的日期时间转换为时间戳。 另外，一些数据库产品也提供了将日期时间格式转换为时间戳的函数。 （例如 MySQL 中的 » UNIX_TIMESTAMP 函数）。

Tip

从 PHP 5.1 版本开始，请求的开始时间可以从变量 $_SERVER['REQUEST_TIME'] 中获取。

### 参见

- gmdate() - 格式化一个 GMT/UTC 日期／时间
- idate() - 将本地时间日期格式化为整数
- getdate() - 取得日期／时间信息
- getlastmod() - 获取页面最后修改的时间
- mktime() - 取得一个日期的 Unix 时间戳
- strftime() - 根据区域设置格式化本地时间／日期
- time() - 返回当前的 Unix 时间戳
- strtotime() - 将任何字符串的日期时间描述解析为 Unix 时间戳
- 预定义的日期时间常量