diff --git a/appendices/examples.xml b/appendices/examples.xml new file mode 100644 index 000000000..2469053b0 --- /dev/null +++ b/appendices/examples.xml @@ -0,0 +1,32 @@ + + + + + 关于手册示例 + + 需要注意的是，为了清晰简洁，PHP 文档中的许多示例都省略了错误和异常处理。 + + + 这并不意味着生产环境代码可以省略错误处理，因为此举可能会引发 TypeError 错误、强制转换失败值（例如将布尔值 &false; 转为空字符串），或是违背代码预设逻辑，进而产生难以排查的隐蔽漏洞。部分扩展库提供了完整示例，其中均包含错误处理逻辑，用以演示该扩展所提供各类函数与方法的规范用法。 + + + diff --git a/reference/datetime/dateerror.xml b/reference/datetime/dateerror.xml new file mode 100644 index 000000000..f81a00486 --- /dev/null +++ b/reference/datetime/dateerror.xml @@ -0,0 +1,84 @@ + + + + + DateError 类 + DateError + + + + +
+ &reftitle.intro; + + 当时区数据库未找到或包含无效数据时抛出。 + + + 该错误不应发生，并且与代码本身无关。根据程序错误或范围相关问题，会抛出两个子异常 + (DateObjectError 和 + DateRangeError)。 + +
+ + +
+ &reftitle.classsynopsis; + + + + + DateError + + + + extends + Error + + + &InheritedProperties; + + + + + &InheritedMethods; + + + + + + + + + +
+ +
+ &reftitle.seealso; + + DateObjectError + DateRangeError + +
+ + + + diff --git a/reference/datetime/dateexception.xml b/reference/datetime/dateexception.xml new file mode 100644 index 000000000..f7a6d4bb6 --- /dev/null +++ b/reference/datetime/dateexception.xml @@ -0,0 +1,82 @@ + + + + + DateException 类 + DateException + + + + +
+ &reftitle.intro; + + Date/Time 异常的父类，适用于由用户输入或需要解析的自由文本参数引发的问题。 + + + 扩展抛出的以下子异常： + + DateInvalidOperationException + DateInvalidTimezoneException + DateMalformedIntervalStringException + DateMalformedPeriodStringException + DateMalformedStringException + + +
+ + +
+ &reftitle.classsynopsis; + + + + + DateException + + + + extends + Exception + + + &InheritedProperties; + + + + + &InheritedMethods; + + + + + + + + + +
+ + + + + diff --git a/reference/datetime/dateinterval/construct.xml b/reference/datetime/dateinterval/construct.xml new file mode 100644 index 000000000..e736f6d9c --- /dev/null +++ b/reference/datetime/dateinterval/construct.xml @@ -0,0 +1,340 @@ + + + + + + DateInterval::__construct + 创建一个新的 DateInterval 对象 + + + + &reftitle.description; + + public DateInterval::__construct + stringduration + + + 创建一个新的 DateInterval 对象。 + + + + + &reftitle.parameters; + + + + duration + + + 时间间隔规范。 + + + 该格式以字母 P 开头，表示 period。 + 每个持续时间段由一个整数值后跟一个周期设计符组成。 + 如果持续时间包含时间部分，则该部分以字母 T 开头。 + + + + + <parameter>duration</parameter> 周期设计符 + + + + + 周期设计符 + 说明 + + + + + Y + 年 + + + M + 月 + + + D + 天 + + + W + + 周。转换为天。 + 在 PHP 8.0.0 之前，不能与 D 组合使用。 + + + + H + 小时 + + + M + 分钟 + + + S + 秒 + + + +
+ + + 以下是一些简单示例。 + 两天为 P2D。 + 两秒为 PT2S。 + 六年五分钟为 P6YT5M。 + + + + 单位必须从左到右按从大到小的顺序输入。 + 因此年在月之前，月在天之前，天在小时之前，依次类推。 + 所以一年四天应表示为 P1Y4D，而非 P4D1Y。 + + + + 该规范也可以使用日期时间格式表示。 + 示例为一年四天：P0001-00-04T00:00:00。 + 但此格式中的值不能超过对应周期的进位点（例如 25 小时是无效的）。 + + + 这些格式基于 ISO 8601 持续时间规范。 + + + + + + + + + &reftitle.errors; + + 当 duration 无法解析为时间间隔时，抛出 + DateMalformedIntervalStringException。 + 在 PHP 8.3 之前，抛出的是 Exception。 + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.3.0 + + 现在在解析失败时抛出 + DateMalformedIntervalStringException， + 而不是 Exception。 + + + + 8.2.0 + + 当通过该方法创建 DateInterval 时， + 仅会显示 y 到 f、 + invert 和 days， + 并新增 from_string 布尔属性。 + + + + 8.0.0 + + W 可以与 D 组合使用。 + + + + + + + + + &reftitle.examples; + + + Constructing and using <classname>DateInterval</classname> objects + +add($interval); + +// Convert interval to string +echo $interval->format("%d"); +]]> + + &example.outputs; + + + + + + + + + <classname>DateInterval</classname> example + + + + &example.outputs.82; + + + int(0) + ["m"]=> + int(0) + ["d"]=> + int(9) + ["h"]=> + int(0) + ["i"]=> + int(0) + ["s"]=> + int(0) + ["f"]=> + float(0) + ["invert"]=> + int(0) + ["days"]=> + bool(false) + ["from_string"]=> + bool(false) +} +]]> + + &example.outputs.8; + + + int(0) + ["m"]=> + int(0) + ["d"]=> + int(9) + ["h"]=> + int(0) + ["i"]=> + int(0) + ["s"]=> + int(0) + ["f"]=> + float(0) + ["weekday"]=> + int(0) + ["weekday_behavior"]=> + int(0) + ["first_last_day_of"]=> + int(0) + ["invert"]=> + int(0) + ["days"]=> + bool(false) + ["special_type"]=> + int(0) + ["special_amount"]=> + int(0) + ["have_weekday_relative"]=> + int(0) + ["have_special_relative"]=> + int(0) +} +]]> + + &example.outputs.7; + + + int(0) + ["m"]=> + int(0) + ["d"]=> + int(2) + ["h"]=> + int(0) + ["i"]=> + int(0) + ["s"]=> + int(0) + ["f"]=> + float(0) + ["weekday"]=> + int(0) + ["weekday_behavior"]=> + int(0) + ["first_last_day_of"]=> + int(0) + ["invert"]=> + int(0) + ["days"]=> + bool(false) + ["special_type"]=> + int(0) + ["special_amount"]=> + int(0) + ["have_weekday_relative"]=> + int(0) + ["have_special_relative"]=> + int(0) +} +]]> + + + + + + + &reftitle.seealso; + + + DateInterval::format + DateTime::add + DateTime::sub + DateTime::diff + + + + + + diff --git a/reference/datetime/dateinterval/createfromdatestring.xml b/reference/datetime/dateinterval/createfromdatestring.xml new file mode 100644 index 000000000..30045f2e8 --- /dev/null +++ b/reference/datetime/dateinterval/createfromdatestring.xml @@ -0,0 +1,281 @@ + + + + + + DateInterval::createFromDateString + 根据字符串的相对部分创建 DateInterval + + + + &reftitle.description; + &style.oop; + + public static DateIntervalDateInterval::createFromDateString + stringdatetime + + &style.procedural; + + DateIntervalfalsedate_interval_create_from_date_string + stringdatetime + + + 使用 DateTimeImmutable 构造函数中使用的日期/时间解析器， + 从解析字符串的相对部分创建一个 DateInterval。 + + + + + &reftitle.parameters; + + + + datetime + + + 含有相对部分的日期。具体来说，将使用用于 + DateTimeImmutable、DateTime + 和 strtotime 的解析器支持的 + 相对格式 来构造 DateInterval。 + + + 如果要使用类似 P7D 的 ISO-8601 格式字符串， + 必须使用 DateInterval::__construct。 + + + + + + + + + &reftitle.returnvalues; + + 成功时返回 DateInterval。 + &return.falseforfailure.style.procedural; + + + + + &reftitle.errors; + + 仅面向对象 API：如果传入无效的日期/时间字符串，将抛出 + DateMalformedStringException。 + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.3.0 + + 当传入无效字符串时，DateInterval::createFromDateString + 现在会抛出 DateMalformedStringException。 + 之前它会返回 false 并发出警告。 + date_interval_create_from_date_string 未作更改。 + + + + 8.2.0 + + 当通过此方法创建 DateInterval 时， + 仅会显示 from_string 和 date_string 属性。 + + + + + + + + + &reftitle.examples; + + + Parsing valid date intervals + + + + + + + + Parsing combinations and negative intervals + +format('%d %h %i'), "\n"; + +$i = DateInterval::createFromDateString('1 year - 10 days'); +echo $i->format('%y %d'), "\n"; +]]> + + &example.outputs; + + + + + + + + Parsing special relative date intervals + + + + &example.outputs.82; + + + bool(true) + ["date_string"]=> + string(22) "last day of next month" +} +object(DateInterval)#2 (2) { + ["from_string"]=> + bool(true) + ["date_string"]=> + string(12) "last weekday" +} +]]> + + &example.outputs.8.similar; + + + int(0) + ["m"]=> + int(1) + ["d"]=> + int(0) + ["h"]=> + int(0) + ["i"]=> + int(0) + ["s"]=> + int(0) + ["f"]=> + float(0) + ["weekday"]=> + int(0) + ["weekday_behavior"]=> + int(0) + ["first_last_day_of"]=> + int(2) + ["invert"]=> + int(0) + ["days"]=> + bool(false) + ["special_type"]=> + int(0) + ["special_amount"]=> + int(0) + ["have_weekday_relative"]=> + int(0) + ["have_special_relative"]=> + int(0) +} +object(DateInterval)#2 (16) { + ["y"]=> + int(0) + ["m"]=> + int(0) + ["d"]=> + int(0) + ["h"]=> + int(0) + ["i"]=> + int(0) + ["s"]=> + int(0) + ["f"]=> + float(0) + ["weekday"]=> + int(0) + ["weekday_behavior"]=> + int(0) + ["first_last_day_of"]=> + int(0) + ["invert"]=> + int(0) + ["days"]=> + bool(false) + ["special_type"]=> + int(1) + ["special_amount"]=> + int(-1) + ["have_weekday_relative"]=> + int(0) + ["have_special_relative"]=> + int(1) +} +]]> + + + + + + + diff --git a/reference/datetime/dateinterval/format.xml b/reference/datetime/dateinterval/format.xml new file mode 100644 index 000000000..b06b542c8 --- /dev/null +++ b/reference/datetime/dateinterval/format.xml @@ -0,0 +1,289 @@ + + + + + + DateInterval::format + 格式化时间间隔 + + + + &reftitle.description; + + public stringDateInterval::format + stringformat + + + 对时间间隔进行格式化。 + + + + + &reftitle.parameters; + + + + format + + + + + 以下字符可在 <parameter>format</parameter> 参数字符串中识别。 + 每个格式字符必须以百分号 (<literal>%</literal>) 为前缀。 + + + + + format 字符 + 说明 + 示例值 + + + + + % + 字面量 % + % + + + Y + 年，数字形式，至少 2 位，带前导零 + 01, 03 + + + y + 年，数字形式 + 1, 3 + + + M + 月，数字形式，至少 2 位，带前导零 + 01, 03, 12 + + + m + 月，数字形式 + 1, 3, 12 + + + D + 天，数字形式，至少 2 位，带前导零 + 01, 03, 31 + + + d + 天，数字形式 + 1, 3, 31 + + + a + 由 DateTime::diff 计算得到的天数总数， + 或者如果未知则为 (unknown) + 4, 18, 8123 + + + H + 小时，数字形式，至少 2 位，带前导零 + 01, 03, 23 + + + h + 小时，数字形式 + 1, 3, 23 + + + I + 分钟，数字形式，至少 2 位，带前导零 + 01, 03, 59 + + + i + 分钟，数字形式 + 1, 3, 59 + + + S + 秒，数字形式，至少 2 位，带前导零 + 01, 03, 57 + + + s + 秒，数字形式 + 1, 3, 57 + + + F + 微秒，数字形式，至少 6 位，带前导零 + 007701, 052738, 428291 + + + f + 微秒，数字形式 + 7701, 52738, 428291 + + + R + 负数时显示 "-"，正数时显示 "+" + -, + + + + r + 负数时显示 "-"，正数时显示空字符串 + -, + + + +
+ + + + + + + + + &reftitle.returnvalues; + + Returns the formatted interval. + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 7.2.12 + F 和 f 格式现在总是为正值。 + + + 7.1.0 + 新增了 F 和 f 格式字符。 + + + + + + + + + &reftitle.examples; + + + <classname>DateInterval</classname> example + + format('%d days'); +]]> + + &example.outputs; + + + + + + + + <classname>DateInterval</classname> and carry over points + + format('%d days'); +]]> + + &example.outputs; + + + + + + + + + <classname>DateInterval</classname> and + <methodname>DateTime::diff</methodname> with the %a and %d modifiers + + + diff($january); + +// %a will output the total number of days. +echo $interval->format('%a total days')."\n"; + +// While %d will only output the number of days not already covered by the +// month. +echo $interval->format('%m month, %d days'); +]]> + + &example.outputs; + + + + + + + + + &reftitle.notes; + + + The DateInterval::format method does not + recalculate carry over points in time strings nor in date segments. This + is expected because it is not possible to overflow values like "32 days" + which could be interpreted as anything from "1 month and 4 days" + to "1 month and 1 day". + + + + + + &reftitle.seealso; + + + DateTime::diff + + + + + + diff --git a/reference/datetime/dateinvalidoperationexception.xml b/reference/datetime/dateinvalidoperationexception.xml new file mode 100644 index 000000000..b31851934 --- /dev/null +++ b/reference/datetime/dateinvalidoperationexception.xml @@ -0,0 +1,78 @@ + + + + + DateInvalidOperationException 类 + DateInvalidOperationException + + + + +
+ &reftitle.intro; + + 当尝试执行不受支持的操作时，由 DateTimeImmutable::sub + 和 DateTime::sub 抛出。 + + + 这种不受支持的操作的一个示例是使用表示相对时间规格的 + DateInterval 对象，例如 next weekday， + 因为无法构造出合理的反向语句。 + +
+ + +
+ &reftitle.classsynopsis; + + + + + DateInvalidOperationException + + + + extends + DateException + + + &InheritedProperties; + + + + + &InheritedMethods; + + + + + + + + + +
+ + + + + diff --git a/reference/datetime/dateinvalidtimezoneexception.xml b/reference/datetime/dateinvalidtimezoneexception.xml new file mode 100644 index 000000000..291ba077e --- /dev/null +++ b/reference/datetime/dateinvalidtimezoneexception.xml @@ -0,0 +1,72 @@ + + + + + DateInvalidTimeZoneException 类 + DateInvalidTimeZoneException + + + + +
+ &reftitle.intro; + + 当传递给 DateTimeZone::__construct 的值不正确时抛出。 + +
+ + +
+ &reftitle.classsynopsis; + + + + + DateInvalidTimeZoneException + + + + extends + DateException + + + &InheritedProperties; + + + + + &InheritedMethods; + + + + + + + + + +
+ + + + + diff --git a/reference/datetime/datemalformedintervalstringexception.xml b/reference/datetime/datemalformedintervalstringexception.xml new file mode 100644 index 000000000..de77c45ed --- /dev/null +++ b/reference/datetime/datemalformedintervalstringexception.xml @@ -0,0 +1,73 @@ + + + + + DateMalformedIntervalStringException 类 + DateMalformedIntervalStringException + + + + +
+ &reftitle.intro; + + 当将无效的 duration 参数传递给 + DateInterval::__construct 时抛出。 + +
+ + +
+ &reftitle.classsynopsis; + + + + + DateMalformedIntervalStringException + + + + extends + DateException + + + &InheritedProperties; + + + + + &InheritedMethods; + + + + + + + + + +
+ + + + + diff --git a/reference/datetime/datemalformedperiodstringexception.xml b/reference/datetime/datemalformedperiodstringexception.xml new file mode 100644 index 000000000..60e594afa --- /dev/null +++ b/reference/datetime/datemalformedperiodstringexception.xml @@ -0,0 +1,73 @@ + + + + + DateMalformedPeriodStringException 类 + DateMalformedPeriodStringException + + + + +
+ &reftitle.intro; + + 当将无效的 isostr 参数传递给 + DatePeriod::__construct 时抛出。 + +
+ + +
+ &reftitle.classsynopsis; + + + + + DateMalformedPeriodStringException + + + + extends + DateException + + + &InheritedProperties; + + + + + &InheritedMethods; + + + + + + + + + +
+ + + + + diff --git a/reference/datetime/datemalformedstringexception.xml b/reference/datetime/datemalformedstringexception.xml new file mode 100644 index 000000000..966204cae --- /dev/null +++ b/reference/datetime/datemalformedstringexception.xml @@ -0,0 +1,79 @@ + + + + + DateMalformedStringException 类 + DateMalformedStringException + + + + +
+ &reftitle.intro; + + 检测到无效的日期/时间字符串时抛出。 + + + 该字符串可以作为 + DateTimeImmutable::__construct、 + DateTimeImmutable::modify、 + DateTime::__construct 或 + DateTime::modify 的值。 + +
+ + +
+ &reftitle.classsynopsis; + + + + + DateMalformedStringException + + + + extends + DateException + + + &InheritedProperties; + + + + + &InheritedMethods; + + + + + + + + + +
+ + + + + diff --git a/reference/datetime/dateobjecterror.xml b/reference/datetime/dateobjecterror.xml new file mode 100644 index 000000000..eb2eb95be --- /dev/null +++ b/reference/datetime/dateobjecterror.xml @@ -0,0 +1,84 @@ + + + + + DateObjectError 类 + DateObjectError + + + + +
+ &reftitle.intro; + + 当 Date/Time 类之一未正确初始化时抛出。 + + + 由于 Date/Time 类不是 final，因此这些类可以被继承。 + 当未调用父类构造函数时，会抛出此错误。这始终是一个编程错误。 + +
+ + +
+ &reftitle.classsynopsis; + + + + + DateObjectError + + + + extends + DateError + + + &InheritedProperties; + + + + + &InheritedMethods; + + + + + + + + + +
+ +
+ &reftitle.seealso; + + DateError + DateRangeError + +
+ + + + + diff --git a/reference/datetime/dateperiod/construct.xml b/reference/datetime/dateperiod/construct.xml new file mode 100644 index 000000000..6f46706cd --- /dev/null +++ b/reference/datetime/dateperiod/construct.xml @@ -0,0 +1,307 @@ + + + + + + DatePeriod::__construct + 创建一个新的 DatePeriod 对象 + + + + &reftitle.description; + + public DatePeriod::__construct + DateTimeInterfacestart + DateIntervalinterval + intrecurrences + intoptions0 + + + public DatePeriod::__construct + DateTimeInterfacestart + DateIntervalinterval + DateTimeInterfaceend + intoptions0 + + + + 以下构造函数变体已被弃用： + + + public DatePeriod::__construct + stringisostr + intoptions0 + + + 应使用静态工厂方法 DatePeriod::createFromISO8601String。 + + + + 创建一个新的 DatePeriod 对象。 + + + DatePeriod 对象可用作迭代器，基于 start 日期、interval 和 end 日期或 recurrences 数量生成多个 DateTimeImmutable 或 DateTime 对象。 + + + 返回对象的类与 start 对象的祖先类相同，或为 DateTimeImmutable，或为 DateTime。 + + + + + &reftitle.parameters; + + + + start + + + 周期的开始日期。默认情况下包含在结果集中。 + + + + + interval + + + 周期内各次重复之间的间隔。 + + + + + recurrences + + + 重复次数。返回结果数量比此值多一个，因为默认情况下包含起始日期。必须大于 0。 + + + + + end + + + 周期的结束日期。默认情况下不包含在结果集中。 + + + + + isostr + + + ISO 8601 重复间隔规范的一个子集。 + + + 以下是 PHP 不支持的一些 ISO 8601 间隔规范特性示例： + + + + + 零次出现 (R0/) + + + + + UTC 以外的时间偏移 (Z)，例如 +02:00。 + + + + + + + options + + + 一个位字段，可用于控制起始日期和结束日期的某些行为。 + + + 使用 DatePeriod::EXCLUDE_START_DATE 可以将起始日期从周期内的重复日期集中排除。 + + + 使用 DatePeriod::INCLUDE_END_DATE 可以将结束日期包含到周期内的重复日期集中。 + + + + + + + + + &reftitle.errors; + + 当 isostr 无法解析为有效的 ISO 8601 周期时，会抛出 DateMalformedPeriodStringException。在 PHP 8.3 之前，此处会抛出 Exception。 + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 8.3.0 + + 现在改为抛出 DateMalformedPeriodStringException，而不是 Exception。 + + + + 8.2.0 + + 新增了 DatePeriod::INCLUDE_END_DATE 常量。 + + + + 7.2.19, 7.3.6, 7.4.0 + + recurrences 现在必须大于 0。 + + + + + + + + + + &reftitle.examples; + + + DatePeriod 示例 + +format('Y-m-d')."\n"; +} +]]> + + &example.outputs; + + + + + + + + 使用 <constant>DatePeriod::EXCLUDE_START_DATE</constant> 的 DatePeriod 示例 + +format('Y-m-d')."\n"; +} +]]> + + &example.outputs; + + + + + + + + 显示一年中所有最后一个周四的 DatePeriod 示例 + +format('l Y-m-d'), "\n"; +} +]]> + + &example.outputs; + + + + + + + + + &reftitle.notes; + + ISO 8601 第 4.5 节“重复时间间隔”中指定的无限次重复不受支持，也就是说传入 "R/..." 作为 isostr 或将 &null; 作为 end 都无效。 + + + + + + diff --git a/reference/datetime/dateperiod/createfromiso8601string.xml b/reference/datetime/dateperiod/createfromiso8601string.xml new file mode 100644 index 000000000..eca9369f5 --- /dev/null +++ b/reference/datetime/dateperiod/createfromiso8601string.xml @@ -0,0 +1,157 @@ + + + + + + DatePeriod::createFromISO8601String + 从 ISO8601 字符串创建一个新的 DatePeriod 对象 + + + + &reftitle.description; + + public static staticDatePeriod::createFromISO8601String + stringspecification + intoptions0 + + + 从 ISO8601 字符串创建一个新的 DatePeriod 对象，该字符串由 specification 指定。 + + + + + &reftitle.parameters; + + + specification + + + ISO 8601 重复间隔规范的一个子集。 + + + 一个被接受的 ISO 8601 间隔规范示例是 + R5/2008-03-01T13:00:00Z/P1Y2M10DT2H30M，它表示： + + + + + 5 次迭代 (R5/) + + + + + 从 2008-03-01T13:00:00Z 开始。 + + + + + 每次迭代为 1 年 2 个月 10 天 2 小时 30 分钟的间隔 + (/P1Y2M10DT2H30M)。 + + + + + + 以下是 PHP 不支持的一些 ISO 8601 间隔规范特性示例： + + + + + 零次出现 (R0/) + + + + + UTC 以外的时间偏移 (Z)，例如 +02:00。 + + + + + + + options + + + 一个位字段，可用于控制起始日期和结束日期的某些行为。 + + + 使用 DatePeriod::EXCLUDE_START_DATE 可以将起始日期从周期内的重复日期集中排除。 + + + 使用 DatePeriod::INCLUDE_END_DATE 可以将结束日期包含到周期内的重复日期集中。 + + + + + + + + &reftitle.returnvalues; + + 创建一个新的 DatePeriod 对象。 + + + 通过此方法创建的 DatePeriod 对象可用作迭代器，用于生成多个 DateTimeImmutable 对象。 + + + + + &reftitle.errors; + + 当 specification 无法解析为有效的 ISO 8601 周期时，会抛出 DateMalformedPeriodStringException。 + + + + + &reftitle.examples; + + + DatePeriod::createFromISO8601String 示例 + +format('Y-m-d'), "\n"; +} +]]> + + &example.outputs; + + + + + + + + + diff --git a/reference/datetime/dateperiod/getdateinterval.xml b/reference/datetime/dateperiod/getdateinterval.xml new file mode 100644 index 000000000..3accc8f0e --- /dev/null +++ b/reference/datetime/dateperiod/getdateinterval.xml @@ -0,0 +1,85 @@ + + + + + + DatePeriod::getDateInterval + + 获取间隔 + + + + + &reftitle.description; + &style.oop; + + public DateIntervalDatePeriod::getDateInterval + + + + 获取表示周期所用间隔的 DateInterval 对象。 + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + 返回一个 DateInterval 对象。 + + + + + &reftitle.examples; + + <methodname>DatePeriod::getDateInterval</methodname> 示例 + +getDateInterval(); +echo $interval->format('%d day'); +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + DatePeriod::getStartDate + DatePeriod::getEndDate + + + + + diff --git a/reference/datetime/dateperiod/getenddate.xml b/reference/datetime/dateperiod/getenddate.xml new file mode 100644 index 000000000..b2808aefe --- /dev/null +++ b/reference/datetime/dateperiod/getenddate.xml @@ -0,0 +1,115 @@ + + + + + + DatePeriod::getEndDate + + 获取结束日期 + + + + + &reftitle.description; + &style.oop; + + public DateTimeInterfacenullDatePeriod::getEndDate + + + + 获取周期的结束日期。 + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + 如果 DatePeriod 没有结束日期，则返回 &null;。例如，当使用 recurrences 参数，或使用不含结束日期的 isostr 参数时。 + + + 如果 DatePeriod 使用 DateTimeImmutable 对象作为 end 参数进行初始化，则返回一个 DateTimeImmutable 对象。 + + + 否则返回一个表示结束日期的克隆 DateTime 对象。 + + + + + &reftitle.examples; + + <methodname>DatePeriod::getEndDate</methodname> 示例 + +getEndDate(); +echo $start->format(DateTime::ISO8601); +]]> + + &example.outputs; + + + + + + <methodname>DatePeriod::getEndDate</methodname>（无结束日期）示例 + +getEndDate()); +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + DatePeriod::getStartDate + DatePeriod::getDateInterval + + + + + diff --git a/reference/datetime/dateperiod/getrecurrences.xml b/reference/datetime/dateperiod/getrecurrences.xml new file mode 100644 index 000000000..463b39266 --- /dev/null +++ b/reference/datetime/dateperiod/getrecurrences.xml @@ -0,0 +1,107 @@ + + + + + + DatePeriod::getRecurrences + 获取重复次数 + + + + &reftitle.description; + &style.oop; + + public intnullDatePeriod::getRecurrences + + + + 获取重复次数。 + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + 通过将 $recurrences 明确传递给 DatePeriod 构造函数设置的重复次数；否则返回 &null;。 + + + + + &reftitle.examples; + + + 不同的 <methodname>DatePeriod::getRecurrences</methodname> 值 + +getRecurrences(), "\n"; + +$period = new DatePeriod($start, $interval, $recurrences); +echo $period->getRecurrences(), "\n"; + +$period = new DatePeriod($start, $interval, $recurrences, DatePeriod::INCLUDE_END_DATE); +echo $period->getRecurrences(), "\n\n"; + +// recurrences not set in the constructor +$period = new DatePeriod($start, $interval, $end); +var_dump($period->getRecurrences()); + +$period = new DatePeriod($start, $interval, $end, DatePeriod::EXCLUDE_START_DATE); +var_dump($period->getRecurrences()); +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + DatePeriod::$recurrences + + + + + diff --git a/reference/datetime/dateperiod/getstartdate.xml b/reference/datetime/dateperiod/getstartdate.xml new file mode 100644 index 000000000..827da4905 --- /dev/null +++ b/reference/datetime/dateperiod/getstartdate.xml @@ -0,0 +1,88 @@ + + + + + + DatePeriod::getStartDate + + 获取起始日期 + + + + + &reftitle.description; + &style.oop; + + public DateTimeInterfaceDatePeriod::getStartDate + + + + 获取周期的起始日期。 + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + 如果 DatePeriod 使用 DateTimeImmutable 对象作为 start 参数进行初始化，则返回一个 DateTimeImmutable 对象。 + + + 否则返回一个 DateTime 对象。 + + + + + &reftitle.examples; + + <methodname>DatePeriod::getStartDate</methodname> 示例 + +getStartDate(); +echo $start->format(DateTime::ISO8601); +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + DatePeriod::getEndDate + DatePeriod::getDateInterval + + + + + diff --git a/reference/datetime/daterangeerror.xml b/reference/datetime/daterangeerror.xml new file mode 100644 index 000000000..91723a34d --- /dev/null +++ b/reference/datetime/daterangeerror.xml @@ -0,0 +1,83 @@ + + + + + DateRangeError 类 + DateRangeError + + + + +
+ &reftitle.intro; + + 当在 32 位平台上，日期对象表示的日期超出 32 位有符号范围时， + 由 DateTime::getTimestamp、 + DateTimeImmutable::getTimestamp 和 + date_timestamp_get 抛出。 + +
+ + +
+ &reftitle.classsynopsis; + + + + + DateRangeError + + + + extends + DateError + + + &InheritedProperties; + + + + + &InheritedMethods; + + + + + + + + + +
+ +
+ &reftitle.seealso; + + DateError + DateObjectError + +
+ + + + + diff --git a/reference/datetime/datetime/createfromimmutable.xml b/reference/datetime/datetime/createfromimmutable.xml new file mode 100644 index 000000000..d7c0ce06b --- /dev/null +++ b/reference/datetime/datetime/createfromimmutable.xml @@ -0,0 +1,103 @@ + + + + + + DateTime::createFromImmutable + 返回封装给定 DateTimeImmutable 对象的新 DateTime 实例 + + + + &reftitle.description; + + public static staticDateTime::createFromImmutable + DateTimeImmutableobject + + + + + &reftitle.parameters; + + + + object + + + 需要转换为可变版本的不可变 DateTimeImmutable 对象。 + 此对象不会被修改，而是创建一个包含相同日期、时间和时区信息的 + DateTime 实例。 + + + + + + + + + &reftitle.returnvalues; + + 返回一个新的 DateTime 实例。 + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 8.0.0 + + 该方法现在会返回当前调用类的实例。在此之前，它始终会创建一个 DateTime 类的新实例。 + + + + + + + + + + &reftitle.examples; + + + 创建一个可变的日期时间对象 + + + + + + + + + diff --git a/reference/datetime/datetime/createfrominterface.xml b/reference/datetime/datetime/createfrominterface.xml new file mode 100644 index 000000000..8a7130190 --- /dev/null +++ b/reference/datetime/datetime/createfrominterface.xml @@ -0,0 +1,81 @@ + + + + + + DateTime::createFromInterface + 返回封装给定 DateTimeInterface 对象的新 DateTime 对象 + + + + &reftitle.description; + + public static DateTimeDateTime::createFromInterface + DateTimeInterfaceobject + + + + + &reftitle.parameters; + + + + object + + + 需要转换为可变版本的 DateTimeInterface 对象。 + 此对象不会被修改，而是创建一个包含相同日期、时间和时区信息的 + DateTime 对象。 + + + + + + + + + &reftitle.returnvalues; + + 返回一个新的 DateTime 实例。 + + + + + &reftitle.examples; + + + Creating a mutable date time object + + + + + + + + diff --git a/reference/datetime/datetimeimmutable.xml b/reference/datetime/datetimeimmutable.xml new file mode 100644 index 000000000..624fb2bcd --- /dev/null +++ b/reference/datetime/datetimeimmutable.xml @@ -0,0 +1,110 @@ + + + + + DateTimeImmutable 类 + DateTimeImmutable + + + + +
+ &reftitle.intro; + + 日期和时间的表示。 + + + 该类的行为与 DateTime 相同，唯一不同的是当 + DateTime::modify 等修改方法被调用时，会返回新对象。 + +
+ + +
+ &reftitle.classsynopsis; + + + + + DateTimeImmutable + + + + implements + DateTimeInterface + + + &InheritedConstants; + + + + + &Methods; + + + + + + + + + + + + +
+ +
+ &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 8.4.0 + + 类常量现已支持类型声明。 + + + + 7.1.0 + + DateTimeImmutable 构造函数现在会在生成的时间值中包含当前微秒数。在此之前，它始终会将微秒数初始化为 0。 + + + + + + +
+ + + &reference.datetime.entities.datetimeimmutable; + + + diff --git a/reference/datetime/datetimeimmutable/add.xml b/reference/datetime/datetimeimmutable/add.xml new file mode 100644 index 000000000..6e10ec6a1 --- /dev/null +++ b/reference/datetime/datetimeimmutable/add.xml @@ -0,0 +1,141 @@ + + + + + + DateTimeImmutable::add + + 返回一个新对象，同时增加天、月、年、小时、分钟和秒 + + + + + &reftitle.description; + + #[\NoDiscard] + public DateTimeImmutableDateTimeImmutable::add + DateIntervalinterval + + + 创建一个新的 DateTimeImmutable 对象，并将指定的 DateInterval 对象添加到此对象中，以表示新的值。 + + + + + &reftitle.parameters; + + + + interval + + + + 一个 DateInterval 对象 + + + + + + + + &reftitle.returnvalues; + + &date.datetimeimmutable.return.modifiedobject; + + + + + &reftitle.examples; + + <function>DateTimeImmutable::add</function> 示例 + &style.oop; + +add(new DateInterval('P10D')); +echo $newDate->format('Y-m-d') . "\n"; +?> +]]> + + + + + 更多 <function>DateTimeImmutable::add</function> 示例 + +add(new DateInterval('PT10H30S')); +echo $newDate->format('Y-m-d H:i:s') . "\n"; + +$date = new DateTimeImmutable('2000-01-01'); +$newDate = $date->add(new DateInterval('P7Y5M4DT4H3M2S')); +echo $newDate->format('Y-m-d H:i:s') . "\n"; +?> +]]> + + &example.outputs; + + + + + + + 添加月份时请注意 + +add($interval); +echo $newDate1->format('Y-m-d') . "\n"; + +$newDate2 = $newDate1->add($interval); +echo $newDate2->format('Y-m-d') . "\n"; +?> +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + DateTimeImmutable::sub + DateTimeImmutable::diff + DateTimeImmutable::modify + + + + diff --git a/reference/datetime/datetimeimmutable/construct.xml b/reference/datetime/datetimeimmutable/construct.xml new file mode 100644 index 000000000..a5016a1f1 --- /dev/null +++ b/reference/datetime/datetimeimmutable/construct.xml @@ -0,0 +1,268 @@ + + + + + + DateTimeImmutable::__construct + date_create_immutable + 返回新的 DateTimeImmutable 对象 + + + + &reftitle.description; + &style.oop; + + public DateTimeImmutable::__construct + stringdatetime"now" + DateTimeZonenulltimezone&null; + + &style.procedural; + + DateTimeImmutablefalsedate_create_immutable + stringdatetime"now" + DateTimeZonenulltimezone&null; + + + 返回新的 DateTimeImmutable 对象。 + + + + + &reftitle.parameters; + + + datetime + + &date.formats.parameter; + + 如果使用 $timezone 参数，在此输入 "now" 以获取当前时间。 + + + + + timezone + + + 一个表示 $datetime 时区的 DateTimeZone 对象。 + + + 如果省略 $timezone 或其值为 &null;，将使用当前时区。 + + + + 当 $datetime 参数为 UNIX 时间戳（例如 @946684800） + 或指定了时区（例如 2010-01-28T15:00:00+02:00 或 + 2010-07-05T06:00:00Z）时， + $timezone 参数和当前时区将被忽略。 + + + + + + + + + &reftitle.returnvalues; + + 返回一个新的 DateTimeImmutable 实例。 + + + + + &reftitle.errors; + + 如果传入无效的日期/时间字符串，将抛出 + DateMalformedStringException。 + 在 PHP 8.3 之前，此异常为 Exception。 + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 8.3.0 + + 如果传入无效字符串，将抛出 + DateMalformedStringException，而不是 + Exception。 + + + + 7.1.0 + 从现在开始，微秒将填充为实际值，而不是 '00000'。 + + + + + + + + + &reftitle.examples; + + <function>DateTimeImmutable::__construct</function> 示例 + &style.oop; + +getMessage(); + exit(1); +} + +echo $date->format('Y-m-d'); +]]> + + &example.outputs; + + + + &style.procedural; + + + + &example.outputs; + + + + + + <function>DateTimeImmutable::__construct</function> 的细节 + +format('Y-m-d H:i:sP') . "\n"; + +// Specified date/time in the specified time zone. +$date = new DateTimeImmutable('2000-01-01', new DateTimeZone('Pacific/Nauru')); +echo $date->format('Y-m-d H:i:sP') . "\n"; + +// Current date/time in your PHP's default time zone. +$date = new DateTimeImmutable(); +echo $date->format('Y-m-d H:i:sP') . "\n"; + +// Current date/time in the specified time zone. +$date = new DateTimeImmutable('now', new DateTimeZone('Pacific/Nauru')); +echo $date->format('Y-m-d H:i:sP') . "\n"; + +// Using a UNIX timestamp. Notice the result is in the UTC time zone. +$date = new DateTimeImmutable('@946684800'); +echo $date->format('Y-m-d H:i:sP') . "\n"; + +// Non-existent values roll over. +$date = new DateTimeImmutable('2000-02-30'); +echo $date->format('Y-m-d H:i:sP') . "\n"; +]]> + + &example.outputs.similar; + + + + + + 可以通过使用 DateTimeImmutable::getLastErrors 检查警告来检测溢出日期。 + + + + + + 更改关联的时区 + +setTimezone($timeZone); + +echo $time->format('Y/m/d H:i:s e'), "\n"; +]]> + + &example.outputs.similar; + + + + + + + 使用相对日期/时间字符串 + +format('Y/m/d H:i:s'), "\n"; +]]> + + &example.outputs.similar; + + + + + + + + + diff --git a/reference/datetime/datetimeimmutable/createfromformat.xml b/reference/datetime/datetimeimmutable/createfromformat.xml new file mode 100644 index 000000000..bb359509f --- /dev/null +++ b/reference/datetime/datetimeimmutable/createfromformat.xml @@ -0,0 +1,732 @@ + + + + + + DateTimeImmutable::createFromFormat + date_create_immutable_from_format + 根据指定格式解析时间字符串 + + + + &reftitle.description; + &style.oop; + + public static DateTimeImmutablefalseDateTimeImmutable::createFromFormat + stringformat + stringdatetime + DateTimeZonenulltimezone&null; + + &style.procedural; + + DateTimeImmutablefalsedate_create_immutable_from_format + stringformat + stringdatetime + DateTimeZonenulltimezone&null; + + + 返回一个新的 DateTimeImmutable 对象，表示由 + datetime 字符串指定的日期和时间，该字符串采用给定的 + format 格式。 + + + + + &reftitle.parameters; + + + format + + + 传入的 string 应该采用的格式。请参阅下方的格式化选项。在大多数情况下，可以使用与 + date 相同的字母。 + + + 所有字段都初始化为当前日期/时间。在大多数情况下，您希望将它们重置为“零”（Unix 纪元，1970-01-01 + 00:00:00 UTC）。您可以通过在 format 的第一个字符中包含 + !，或在末尾包含 | 来实现。 + 有关更多信息，请参阅下文中每个字符的文档。 + + + 格式按从左到右顺序解析，这意味着在某些情况下，格式字符出现的顺序会影响结果。在 + z（一年中的天数）的情况下，必须先解析出年份， + 例如通过 Y 或 y 字符。 + + + 用于解析数字的字母允许的数值范围很宽，超出了逻辑范围。例如， + d（一个月中的日）可接受 00 到 99 的值。 + 唯一的限制是数字位数。当提供超出范围的值时，会使用日期/时间解析器的溢出机制。下方示例展示了部分行为。 + + + 这也意味着对格式字母解析的数据是贪婪的，会读取其格式允许的最大位数。这可能导致 + datetime 字符串中剩余字符不足以解析后续格式字符。本文中的示例也说明了此问题。 + + + + 以下字符在 <parameter>format</parameter> 参数字符串中被识别 + + + + format 字符 + 描述 + 可解析示例值 + + + + + 日 + --- + --- + + + d 和 j + 一个月中的日，可包含或不包含前导零的两位数字 + + 01 到 31 或 + 1 到 31。 (允许使用超过该月天数的两位数， + 这将导致月份溢出。例如，对一月使用 33，结果为 2 月 2 日) + + + + D 和 l + 星期几的文本表示 + + Mon 到 Sun 或 + Sunday 到 Saturday。如果给定的星期名称与解析（或默认）日期对应的星期名称不同， + 则会溢出到具有给定星期名称的下一个日期。有关说明，请参阅下面的示例。 + + + + S + 英文序数后缀，用于表示一个月中的日，2 个字符。处理时忽略它。 + + st, nd, rd 或 + th。 + + + + z + + The day of the year (starting from 0); + must be preceded by Y or y. + + + 0 through 365. (3 digit + numbers higher than the numbers in a year are accepted, in which + case they will make the year overflow. For example using 366 with + 2022, means January 2nd, 2023) + + + + 月 + --- + --- + + + F 和 M + 月份的文本表示，例如 January 或 Sept + + January 到 December 或 + Jan 到 Dec + + + + m 和 n + 月份的数值表示，可包含或不包含前导零 + + 01 到 12 或 + 1 到 12。 + (允许使用超过 12 的两位数，这将导致年份溢出。例如使用 13 表示下一年的一月) + + + + 年 + --- + --- + + + X 和 x + 年份的完整数字表示，最多 19 位，可选地带有 + 或 - 前缀 + 示例：0055、787、 + 1999、-2003、 + +10191 + + + Y + 年份的完整数字表示，最多 4 位 + 示例：25（等同于 0025）、 + 787、1999、2003 + + + y + + 年份的两位数字表示（假定在 1970 至 2069 范围内，含端点） + + + 示例： + 99 或 03 + （分别解释为 1999 和 + 2003） + + + + 时间 + --- + --- + + + a 和 A + 上下午标记 + am 或 pm + + + g 和 h + 小时的 12 小时制表示，可包含或不包含前导零 + + 1 到 12 或 + 01 到 12（允许使用超过 12 的两位数， + 这将导致日期溢出。例如使用 14 表示下一个上午/下午时段的 02） + + + + G 和 H + 小时的 24 小时制表示，可包含或不包含前导零 + + 0 到 23 或 + 00 到 23（允许使用超过 24 的两位数， + 这将导致日期溢出。例如使用 26 表示下一天的 02:00） + + + + i + 带前导零的分钟 + + 00 到 59。（允许使用超过 59 的两位数， + 这将导致小时溢出。例如使用 66 表示下一小时的 :06） + + + + s + 带前导零的秒 + + 00 到 59（允许使用超过 59 的两位数， + 这将导致分钟溢出。例如使用 90 表示下一分钟的 :30） + + + + v + 毫秒数的小数部分（最多三位） + 示例：12（0.12 秒），345（0.345 秒） + + + u + 微秒数的小数部分（最多六位） + 示例：45（0.45 秒），654321（0.654321 秒） + + + 时区 + --- + --- + + + + e、O、p、 + P 和 T + + 时区标识符，或与 UTC 的小时差，或带冒号的小时和分钟偏移，亦或时区缩写 + 示例：UTC、GMT、 + Atlantic/Azores 或 + +0200、+02:00，或 + EST、MDT + + + + 完整日期/时间 + --- + --- + + + U + 自 Unix 纪元以来的秒数（1970 年 1 月 1 日 00:00:00 GMT） + 示例：1292177455 + + + 空白与分隔符 + --- + --- + + + （空格） + 零个或多个空格、制表符、NBSP (U+A0) 或 NNBSP (U+202F) 字符 + 示例："\t"、" " + + + # + + 以下分隔符之一：;、 + :、/、.、 + ,、-、( 或 + ) + + 示例：/ + + + + ;、 + :、/、.、 + ,、-、( 或 + ) + + 指定的字符。 + 示例：- + + + ? + 任意一个字节 + 示例：^（注意，对于 UTF-8 字符，您可能需要多个 ?。此时，使用 * 更合适） + + + * + 直到遇到下一个分隔符或数字前的任意字节 + 示例：在 Y-*-d 中，与字符串 2009-aWord-08 匹配的是 + aWord + + + ! + 将所有字段（年、月、日、时、分、秒、分数和时区信息）重置为类似零的值（ + 小时、分钟、秒和分数为 0， + 月和日为 1，年份为 1970，并使用默认时区） + 如果没有 !，所有字段将设置为当前日期和时间。 + + + | + 如果相应字段尚未被解析，则将所有字段（年、月、日、时、分、秒、分数和时区信息）重置为类似零的值 + Y-m-d| 会将年、月和日设置为解析字符串中找到的信息，并将时、分、秒设置为 0。 + + + + + 如果存在该格式说明符，字符串末尾的多余数据不会导致错误，而是产生警告 + 使用 DateTimeImmutable::getLastErrors 可判断是否存在多余数据。 + + + +
+ + + 格式字符串中无法识别的字符会导致解析失败，并将错误消息附加到返回的结构中。 + 您可以使用 DateTimeImmutable::getLastErrors 查询错误消息。 + + + 若要在 format 中包含字面字符，必须使用反斜线 (\) 转义它们。 + + + 如果 format 不包含字符 !，则生成的日期/时间中未在 + format 中指定的部分将设置为当前系统时间。 + + + 如果 format 包含字符 !，则生成的日期/时间中未在 + format 中提供的部分，以及 ! 左侧的值， + 将设置为 Unix 纪元的对应值。 + + + 如果解析了任意时间字符，则所有其他与时间相关的字段都将设置为 "0"，除非它们也被解析。 + + + Unix 纪元是 1970-01-01 00:00:00 UTC。 + + + + + datetime + + + 表示时间的字符串。 + + + + + timezone + + + 表示所需时区的 DateTimeZone 对象。 + + + 如果省略 timezone 或其值为 &null;，并且 + datetime 不包含时区，则使用当前时区。 + + + + 当 datetime 参数包含 UNIX 时间戳（例如 946684800） + 或指定了时区（例如 2010-01-28T15:00:00+02:00）时， + timezone 参数和当前时区将被忽略。 + + + + + + + + + &reftitle.returnvalues; + + 返回一个新的 DateTimeImmutable 实例&return.falseforfailure;。 + + + + + &reftitle.errors; + + 如果 datetime 包含 NULL 字节，此方法会抛出 ValueError。 + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 8.2.9 + + （空格）说明符现在也支持 NBSP + (U+A0) 和 NNBSP (U+202F) 字符。 + + + + 8.2.0 + + 已添加 X 和 x + format 说明符。 + + + + 8.0.21, 8.1.8, 8.2.0 + + 当 NULL 字节传入 datetime 时， + 现在会抛出 ValueError，之前这些 NULL 字节会被静默忽略。 + + + + 7.3.0 + + 已添加 v format 说明符。 + + + + + + + + + + &reftitle.examples; + + <function>DateTimeImmutable::createFromFormat</function> 示例 + &style.oop; + +format('Y-m-d'); +]]> + + + + + 使用预定义格式常量与 <function>DateTimeImmutable::createFromFormat</function> + &style.oop; + +format('c e') . "\n"; + +$date = DateTimeImmutable::createFromFormat( + DateTimeInterface::RFC3339_EXTENDED, + '2013-10-14T09:00:00.000+02:00' +); +echo $date->format('c e') . "\n"; +]]> + + + 本示例中使用的 格式化常量 + 由一串用于 格式化 + DateTimeImmutable 对象的字符组成。在大多数情况下，这些 + 字母与上文 参数 + 部分中定义的日期/时间元素相对应，但它们通常更宽松。 + + + + + <function>DateTimeImmutable::createFromFormat</function> 的复杂之处 + +format('Y-m-d H:i:s') . "\n"; + +$format = 'Y-m-d H:i:s'; +$date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17'); +echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n"; + +$format = 'Y-m-!d H:i:s'; +$date = DateTimeImmutable::createFromFormat($format, '2009-02-15 15:16:17'); +echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n"; + +$format = '!d'; +$date = DateTimeImmutable::createFromFormat($format, '15'); +echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n"; + +$format = 'i'; +$date = DateTimeImmutable::createFromFormat($format, '15'); +echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n"; +]]> + + &example.outputs.similar; + + + + + + + 包含字面字符的格式字符串 + +format('H:i:s'); +]]> + + &example.outputs.similar; + + + + + + + 溢出行为 + +format(DateTimeImmutable::RFC2822); +]]> + + &example.outputs.similar; + + + + + 虽然结果看起来很奇怪，但它是正确的，因为发生了以下溢出： + + + + + 97 秒溢出为 1 分钟， + 剩下 37 秒。 + + + + + 61 分钟溢出为 1 小时， + 剩下 1 分钟。 + + + + + 35 天溢出为 1 个月， + 剩下 4 天。剩余的天数取决于该月，因为并非每个月的天数相同。 + + + + + 18 个月溢出为 1 年， + 剩下 6 个月。 + + + + + + + 星期名称溢出行为 + +format(DateTime::RFC1123), "\n"; +]]> + + &example.outputs.similar; + + + + + 虽然结果看起来很奇怪，但它是正确的，因为发生了以下溢出： + + + + + 3 Aug 2020 25:00:00 溢出为 (Tue) 4 Aug + 2020 01:00。 + + + + + 应用 Mon 后，日期推进到 + Mon, 10 Aug 2020 01:00:00。相对关键字（如 + Mon）的解释，请参阅 + 相对格式 一节。 + + + + + + + 为了检测日期中的溢出，您可以使用 + DateTimeImmutable::getLastErrors，如果发生溢出， + 结果中会包含警告。 + + + 检测溢出日期 + +format(DateTimeImmutable::RFC2822), "\n\n"; + +var_dump(DateTimeImmutable::getLastErrors()); +]]> + + &example.outputs.similar; + + + int(2) + 'warnings' => + array(1) { + [19] => + string(27) "The parsed date was invalid" + } + 'error_count' => + int(0) + 'errors' => + array(0) { + } +} +]]> + + + + + 贪婪解析行为 + + + + &example.outputs.similar; + + + [month] => + [day] => + [hour] => 60 + [minute] => 10 + [second] => 0 + [fraction] => 0 + [warning_count] => 1 + [warnings] => Array + ( + [5] => The parsed time was invalid + ) + + [error_count] => 1 + [errors] => Array + ( + [4] => A two digit second could not be found + ) + + [is_localtime] => +) +]]> + + + G 格式用于解析 24 小时制小时，可包含或不包含前导零。它要求解析 1 或 2 位数字。 + 由于后面有两个数字，它会贪婪地读取为 60。 + + + 以下 i 和 s 格式字符都要求两位数字。这意味着 10 + 被作为分钟 (i) 解析，剩余的数字不足以解析为秒 (s)。 + + + errors 数组指出了此问题。 + + + 另外，60 小时超出 0-24 的范围， + 这导致 warnings 数组包含时间无效的警告。 + + + + + + + &reftitle.seealso; + + DateTimeImmutable::__construct + DateTimeImmutable::getLastErrors + checkdate + strptime + + + + + diff --git a/reference/datetime/datetimeimmutable/createfrominterface.xml b/reference/datetime/datetimeimmutable/createfrominterface.xml new file mode 100644 index 000000000..1b8443173 --- /dev/null +++ b/reference/datetime/datetimeimmutable/createfrominterface.xml @@ -0,0 +1,79 @@ + + + + + + DateTimeImmutable::createFromInterface + 返回封装给定 DateTimeInterface 对象的新 DateTimeImmutable 对象 + + + + &reftitle.description; + + public static DateTimeImmutableDateTimeImmutable::createFromInterface + DateTimeInterfaceobject + + + + + &reftitle.parameters; + + + + object + + + 需要转换为不可变版本的 DateTimeInterface 对象。此对象不会被修改，而是创建一个包含相同日期、时间和时区信息的 DateTimeImmutable 对象。 + + + + + + + + + &reftitle.returnvalues; + + 返回一个新的 DateTimeImmutable 实例。 + + + + + &reftitle.examples; + + + 创建不可变日期时间对象 + + + + + + + + diff --git a/reference/datetime/datetimeimmutable/createfrommutable.xml b/reference/datetime/datetimeimmutable/createfrommutable.xml new file mode 100644 index 000000000..25a82df70 --- /dev/null +++ b/reference/datetime/datetimeimmutable/createfrommutable.xml @@ -0,0 +1,101 @@ + + + + + + DateTimeImmutable::createFromMutable + 返回封装给定 DateTime 对象的新 DateTimeImmutable 实例 + + + + &reftitle.description; + + public static staticDateTimeImmutable::createFromMutable + DateTimeobject + + + + + &reftitle.parameters; + + + + object + + + 需要转换为不可变版本的可变 DateTime 对象。此对象不会被修改，而是创建一个包含相同日期、时间和时区信息的 DateTimeImmutable 实例。 + + + + + + + + + &reftitle.returnvalues; + + 返回一个新的 DateTimeImmutable 实例。 + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 8.0.0 + + 该方法现在返回当前调用类的实例。此前，它会创建一个新的 DateTimeImmutable 实例。 + + + + + + + + + + &reftitle.examples; + + + 创建不可变日期时间对象 + + + + + + + + + diff --git a/reference/datetime/datetimeimmutable/getlasterrors.xml b/reference/datetime/datetimeimmutable/getlasterrors.xml new file mode 100644 index 000000000..d6af41d7f --- /dev/null +++ b/reference/datetime/datetimeimmutable/getlasterrors.xml @@ -0,0 +1,152 @@ + + + + + + DateTimeImmutable::getLastErrors + 返回警告和错误 + + + + &reftitle.description; + + public static arrayfalseDateTimeImmutable::getLastErrors + + + + 返回在解析日期/时间字符串时发现的警告和错误数组。 + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + 返回包含警告和错误信息的数组；如果既没有警告也没有错误，则返回 &false;。 + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 8.2.0 + + 在 PHP 8.2.0 之前，当没有警告或错误时，该函数不会返回 &false;。 + 相反，它将始终返回文档中描述的数组结构。 + + + + + + + + + + &reftitle.examples; + + <function>DateTimeImmutable::getLastErrors</function> 示例 + +getMessage(); +} +?> +]]> + + &example.outputs; + + 1 + [warnings] => Array + ( + [6] => Double timezone specification + ) + + [error_count] => 1 + [errors] => Array + ( + [0] => The timezone could not be found in the database + ) +) +Failed to parse time string (asdfasdf) at position 0 (a): The timezone could not be found in the database +]]> + + + 示例输出中的索引 6 和 0 指的是错误发生在字符串中的字符位置。 + + + + 检测溢出日期 + + + + &example.outputs; + + 1 + [warnings] => Array + ( + [10] => The parsed date was invalid + ) + + [error_count] => 0 + [errors] => Array + ( + ) +) +]]> + + + + + + + diff --git a/reference/datetime/datetimeimmutable/modify.xml b/reference/datetime/datetimeimmutable/modify.xml new file mode 100644 index 000000000..1d2ab4206 --- /dev/null +++ b/reference/datetime/datetimeimmutable/modify.xml @@ -0,0 +1,151 @@ + + + + + + DateTimeImmutable::modify + 创建一个具有修改后时间戳的新对象 + + + + &reftitle.description; + + #[\NoDiscard] + public DateTimeImmutableDateTimeImmutable::modify + stringmodifier + + + 创建一个新的 DateTimeImmutable 对象，其时间戳已修改。 + 原始对象不会被修改。 + + + + + &reftitle.parameters; + + + modifier + + &date.formats.parameter; + + + + + + + &reftitle.returnvalues; + + 成功时返回 DateTimeImmutable。 + 失败时返回 FALSE。 + + + + + &reftitle.errors; + + 如果传入无效的日期/时间字符串， + DateMalformedStringException 将被抛出。 + 在 PHP 8.3 之前，这会发出一个警告。 + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.3.0 + + DateTimeImmutable::modify 现在在传入无效字符串时抛出 + DateMalformedStringException。 + 之前，它返回 false，并发出警告。 + + + + + + + + &reftitle.examples; + + <function>DateTimeImmutable::modify</function> 示例 + &style.oop; + +modify('+1 day'); +echo $newDate->format('Y-m-d'); +]]> + + &example.outputs; + + + + + + 添加或减去月份时请注意 + +modify('+1 month'); +echo $newDate1->format('Y-m-d') . "\n"; + +$newDate2 = $newDate1->modify('+1 month'); +echo $newDate2->format('Y-m-d') . "\n"; +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + DateTimeImmutable::add + DateTimeImmutable::sub + DateTimeImmutable::setDate + DateTimeImmutable::setISODate + DateTimeImmutable::setTime + DateTimeImmutable::setTimestamp + + + + + diff --git a/reference/datetime/datetimeimmutable/set-state.xml b/reference/datetime/datetimeimmutable/set-state.xml new file mode 100644 index 000000000..a7d679679 --- /dev/null +++ b/reference/datetime/datetimeimmutable/set-state.xml @@ -0,0 +1,62 @@ + + + + + + DateTimeImmutable::__set_state + __set_state 处理程序 + + + + &reftitle.description; + + public static DateTimeImmutableDateTimeImmutable::__set_state + arrayarray + + + __set_state() 处理程序。 + + + + + &reftitle.parameters; + + + array + + + 初始化数组。 + + + + + + + + &reftitle.returnvalues; + + 返回一个 DateTimeImmutable 对象的新实例。 + + + + + diff --git a/reference/datetime/datetimeimmutable/setdate.xml b/reference/datetime/datetimeimmutable/setdate.xml new file mode 100644 index 000000000..2e47e57a6 --- /dev/null +++ b/reference/datetime/datetimeimmutable/setdate.xml @@ -0,0 +1,138 @@ + + + + + + DateTimeImmutable::setDate + 设置日期 + + + + &reftitle.description; + + #[\NoDiscard] + public DateTimeImmutableDateTimeImmutable::setDate + intyear + intmonth + intday + + + 返回一个新的 DateTimeImmutable 对象，其当前日期设置为给定的日期。 + + + + + &reftitle.parameters; + + &date.datetime.description.modified; + + year + + + 日期的年份。 + + + + + month + + + 日期的月份。 + + + + + day + + + 日期的日。 + + + + + + + + &reftitle.returnvalues; + + &date.datetimeimmutable.return.modifiedobject; + + + + + &reftitle.examples; + + <function>DateTimeImmutable::setDate</function> example + &style.oop; + +setDate(2001, 2, 3); +echo $newDate->format('Y-m-d'); +]]> + + &example.outputs; + + + + + + 超出范围的值会添加到其父级值 + +setDate(2001, 2, 28); +echo $newDate->format('Y-m-d') . "\n"; + +$newDate = $date->setDate(2001, 2, 29); +echo $newDate->format('Y-m-d') . "\n"; + +$newDate = $date->setDate(2001, 14, 3); +echo $newDate->format('Y-m-d') . "\n"; +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + DateTimeImmutable::setISODate + DateTimeImmutable::setTime + + + + + diff --git a/reference/datetime/datetimeimmutable/setisodate.xml b/reference/datetime/datetimeimmutable/setisodate.xml new file mode 100644 index 000000000..e38a4f1ea --- /dev/null +++ b/reference/datetime/datetimeimmutable/setisodate.xml @@ -0,0 +1,183 @@ + + + + + + DateTimeImmutable::setISODate + 设置 ISO 日期 + + + + &reftitle.description; + + #[\NoDiscard] + public DateTimeImmutableDateTimeImmutable::setISODate + intyear + intweek + intdayOfWeek1 + + + 返回一个新的 DateTimeImmutable 对象，其日期根据 ISO 8601 标准设置——使用周和日期偏移，而不是具体日期。 + + + + + &reftitle.parameters; + + + year + + + 日期的年份。 + + + + + week + + + 日期的周数。 + + + + + dayOfWeek + + + 与周首日之间的偏移量。 + + + + + + + + &reftitle.returnvalues; + + &date.datetimeimmutable.return.modifiedobject; + + + + + &reftitle.examples; + + <function>DateTimeImmutable::setISODate</function> 示例 + &style.oop; + +setISODate(2008, 2); +echo $newDate->format('Y-m-d') . "\n"; + +$newDate = $date->setISODate(2008, 2, 7); +echo $newDate->format('Y-m-d') . "\n"; +]]> + + &example.outputs; + + + + &style.procedural; + + + + &example.outputs; + + + + + + 超出范围的值会添加到其父级值 + +setISODate(2008, 2, 7); +echo $newDate->format('Y-m-d') . "\n"; + +$newDate = $date->setISODate(2008, 2, 8); +echo $newDate->format('Y-m-d') . "\n"; + +$newDate = $date->setISODate(2008, 53, 7); +echo $newDate->format('Y-m-d') . "\n"; +]]> + + &example.outputs; + + + + + + 查找某周所在的月份 + +setISODate(2008, 14); +echo $newDate->format('n'); +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + DateTimeImmutable::setDate + DateTimeImmutable::setTime + + + + + diff --git a/reference/datetime/datetimeimmutable/settime.xml b/reference/datetime/datetimeimmutable/settime.xml new file mode 100644 index 000000000..a40c72268 --- /dev/null +++ b/reference/datetime/datetimeimmutable/settime.xml @@ -0,0 +1,182 @@ + + + + + + DateTimeImmutable::setTime + 设置时间 + + + + &reftitle.description; + + #[\NoDiscard] + public DateTimeImmutableDateTimeImmutable::setTime + inthour + intminute + intsecond0 + intmicrosecond0 + + + 返回一个新的 DateTimeImmutable 对象，其时间设置为给定时间。 + + + + + &reftitle.parameters; + + + hour + + + 时间的小时。 + + + + + minute + + + 时间的分钟。 + + + + + second + + + 时间的秒。 + + + + + microsecond + + + 时间的微秒。 + + + + + + + + &reftitle.returnvalues; + + &date.datetimeimmutable.return.modifiedobject; + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.1.0 + 在双重小时（回退 DST 过渡）期间的行为已更改。之前 PHP 会选择第二次出现的时间点（DST 过渡之后），而不是第一次出现的时间点（DST 过渡之前）。 + + + 7.1.0 + 已添加 microsecond 参数。 + + + + + + + + &reftitle.examples; + + <function>DateTimeImmutable::setTime</function> 示例 + &style.oop; + +setTime(14, 55); +echo $newDate->format('Y-m-d H:i:s') . "\n"; + +$newDate = $date->setTime(14, 55, 24); +echo $newDate->format('Y-m-d H:i:s') . "\n"; +?> +]]> + + &example.outputs.similar; + + + + + + 超出范围的值会添加到其父级值 + +setTime(14, 55, 24); +echo $newDate->format('Y-m-d H:i:s') . "\n"; + +$newDate = $date->setTime(14, 55, 65); +echo $newDate->format('Y-m-d H:i:s') . "\n"; + +$newDate = $date->setTime(14, 65, 24); +echo $newDate->format('Y-m-d H:i:s') . "\n"; + +$newDate = $date->setTime(25, 55, 24); +echo $newDate->format('Y-m-d H:i:s') . "\n"; +?> +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + DateTimeImmutable::setDate + DateTimeImmutable::setISODate + + + + + + diff --git a/reference/datetime/datetimeimmutable/settimestamp.xml b/reference/datetime/datetimeimmutable/settimestamp.xml new file mode 100644 index 000000000..294a471c3 --- /dev/null +++ b/reference/datetime/datetimeimmutable/settimestamp.xml @@ -0,0 +1,99 @@ + + + + + + DateTimeImmutable::setTimestamp + 根据 Unix 时间戳设置日期和时间 + + + + &reftitle.description; + + #[\NoDiscard] + public DateTimeImmutableDateTimeImmutable::setTimestamp + inttimestamp + + + 返回一个新的 DateTimeImmutable 对象，该对象由旧对象构造， + 且其日期和时间根据 Unix 时间戳设置。 + + + + + &reftitle.parameters; + + + timestamp + + + 表示日期的 Unix 时间戳。 + 如果使用 @ 格式与 + DateTimeImmutable::modify，则可以设置超出 &integer; 范围的时间戳。 + + + + + + + + &reftitle.returnvalues; + + &date.datetimeimmutable.return.modifiedobject; + + + + + &reftitle.examples; + + <function>DateTimeImmutable::setTimestamp</function> 示例 + &style.oop; + +format('U = Y-m-d H:i:s') . "\n"; + +$newDate = $date->setTimestamp(1171502725); +echo $newDate->format('U = Y-m-d H:i:s') . "\n"; +]]> + + &example.outputs.similar; + + + + + + + + &reftitle.seealso; + + DateTimeImmutable::getTimestamp + + + + + + diff --git a/reference/datetime/datetimeimmutable/settimezone.xml b/reference/datetime/datetimeimmutable/settimezone.xml new file mode 100644 index 000000000..0c3da01cb --- /dev/null +++ b/reference/datetime/datetimeimmutable/settimezone.xml @@ -0,0 +1,99 @@ + + + + + + DateTimeImmutable::setTimezone + 设置时区 + + + + &reftitle.description; + + #[\NoDiscard] + public DateTimeImmutableDateTimeImmutable::setTimezone + DateTimeZonetimezone + + + 返回一个设置了新时区的 DateTimeImmutable 对象。 + + + + + &reftitle.parameters; + + + timezone + + + 表示所需时区的 DateTimeZone 对象。 + + + + + + + + &reftitle.returnvalues; + + 返回一个新的、已修改的 DateTimeImmutable 对象，以便方法链调用。调用此方法时， + 基础的时间点不会改变。 + + + + + &reftitle.examples; + + <function>DateTimeImmutable::setTimeZone</function> 示例 + &style.oop; + +format('Y-m-d H:i:sP') . "\n"; + +$newDate = $date->setTimezone(new DateTimeZone('Pacific/Chatham')); +echo $newDate->format('Y-m-d H:i:sP') . "\n"; +?> +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + DateTimeImmutable::getTimezone + DateTimeZone::__construct + + + + + + diff --git a/reference/datetime/datetimeimmutable/sub.xml b/reference/datetime/datetimeimmutable/sub.xml new file mode 100644 index 000000000..d372de237 --- /dev/null +++ b/reference/datetime/datetimeimmutable/sub.xml @@ -0,0 +1,181 @@ + + + + + + DateTimeImmutable::sub + + 减去一定数量的天、月、年、小时、分钟和秒 + + + + + &reftitle.description; + + #[\NoDiscard] + public DateTimeImmutableDateTimeImmutable::sub + DateIntervalinterval + + + 返回一个新的 DateTimeImmutable 对象， + 从指定的 DateTimeImmutable 对象中减去给定的 + DateInterval 对象。 + + + + + &reftitle.parameters; + + + + interval + + + + 一个 DateInterval 对象 + + + + + + + + &reftitle.returnvalues; + + &date.datetimeimmutable.return.modifiedobject; + + + + + &reftitle.errors; + + 如果尝试执行不受支持的操作，例如使用表示相对时间规范（如 next weekday）的 + DateInterval 对象，将抛出 + DateInvalidOperationException。 + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.3.0 + + 在尝试执行不受支持的操作时， + 现在会抛出 DateInvalidOperationException， + 而不是发出警告。 + + + + + + + + + &reftitle.examples; + + <function>DateTimeImmutable::sub</function> 示例 + &style.oop; + +sub(new DateInterval('P10D')); +echo $newDate->format('Y-m-d') . "\n"; +?> +]]> + + &example.outputs; + + + + + + 更多 <function>DateTimeImmutable::sub</function> 示例 + +sub(new DateInterval('PT10H30S')); +echo $newDate->format('Y-m-d H:i:s') . "\n"; + +$date = new DateTimeImmutable('2000-01-20'); +$newDate = $date->sub(new DateInterval('P7Y5M4DT4H3M2S')); +echo $newDate->format('Y-m-d H:i:s') . "\n"; +?> +]]> + + &example.outputs; + + + + + + 减去月份时请注意 + +sub($interval); +echo $newDate1->format('Y-m-d') . "\n"; + +$newDate2 = $newDate1->sub($interval); +echo $newDate2->format('Y-m-d') . "\n"; +?> +]]> + + &example.outputs; + + + + + + + + &reftitle.seealso; + + DateTimeImmutable::add + DateTimeImmutable::diff + DateTimeImmutable::modify + + + + + diff --git a/reference/datetime/datetimeinterface/serialize.xml b/reference/datetime/datetimeinterface/serialize.xml new file mode 100644 index 000000000..62f3c5a98 --- /dev/null +++ b/reference/datetime/datetimeinterface/serialize.xml @@ -0,0 +1,89 @@ + + + + + + DateTime::__serialize + DateTimeImmutable::__serialize + DateTimeInterface::__serialize + 序列化 DateTime + + + + &reftitle.description; + + public arrayDateTime::__serialize + + + + public arrayDateTimeImmutable::__serialize + + + + public arrayDateTimeInterface::__serialize + + + + __serialize() 处理程序。 + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + DateTime 对象的序列化表示。 + + + + + &reftitle.examples; + + <function>DateTime::serialize</function> example + + + + &example.outputs; + + + + + + + + &reftitle.seealso; + + DateTime::__unserialize + + + + diff --git a/reference/datetime/datetimeinterface/unserialize.xml b/reference/datetime/datetimeinterface/unserialize.xml new file mode 100644 index 000000000..cc06b3878 --- /dev/null +++ b/reference/datetime/datetimeinterface/unserialize.xml @@ -0,0 +1,105 @@ + + + + + + DateTime::__unserialize + DateTimeImmutable::__unserialize + DateTimeInterface::__unserialize + 反序列化 DateTime + + + + &reftitle.description; + + public voidDateTime::__unserialize + arraydata + + + public voidDateTimeImmutable::__unserialize + arraydata + + + public voidDateTimeInterface::__unserialize + arraydata + + + __unserialize() 处理程序。 + + + + + &reftitle.parameters; + + + data + + + 序列化后的 DateTime 数据。 + + + + + + + + &reftitle.returnvalues; + + DateTime 对象。 + + + + + &reftitle.examples; + + <function>DateTime::unserialize</function> example + + + + &example.outputs; + + + string(26) "2025-03-27 00:00:00.000000" + ["timezone_type"]=> + int(3) + ["timezone"]=> + string(3) "UTC" +} +]]> + + + + + + &reftitle.seealso; + + DateTime::__serialize + + + + diff --git a/reference/datetime/datetimeinterface/wakeup.xml b/reference/datetime/datetimeinterface/wakeup.xml new file mode 100644 index 000000000..3f76ed249 --- /dev/null +++ b/reference/datetime/datetimeinterface/wakeup.xml @@ -0,0 +1,70 @@ + + + + + + DateTime::__wakeup + DateTimeImmutable::__wakeup + DateTimeInterface::__wakeup + __wakeup 处理程序 + + + + &warn.deprecated.function-8-5-0; + + + + &reftitle.description; + + #[\Deprecated] + public voidDateTime::__wakeup + + + + #[\Deprecated] + public voidDateTimeImmutable::__wakeup + + + + #[\Deprecated] + public voidDateTimeInterface::__wakeup + + + + __wakeup() 处理程序。 + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Initializes a DateTime object. + + + + + diff --git a/reference/datetime/datetimezone/gettransitions.xml b/reference/datetime/datetimezone/gettransitions.xml new file mode 100644 index 000000000..239bd568a --- /dev/null +++ b/reference/datetime/datetimezone/gettransitions.xml @@ -0,0 +1,250 @@ + + + + + + DateTimeZone::getTransitions + timezone_transitions_get + 返回指定时区的所有转换信息 + + + &reftitle.description; + &style.oop; + + public arrayfalseDateTimeZone::getTransitions + inttimestampBeginPHP_INT_MIN + inttimestampEnd2147483647 + + &style.procedural; + + arrayfalsetimezone_transitions_get + DateTimeZoneobject + inttimestampBeginPHP_INT_MIN + inttimestampEnd2147483647 + + + + + &reftitle.parameters; + + + &date.datetimezone.description; + + timestampBegin + + + 起始时间戳。 + + + + + timestampEnd + + + 结束时间戳。 + + + + + + + + + &reftitle.returnvalues; + + 返回一个数值索引数组，包含转换数组；失败时返回 &false;。 + 包装类型 1（UTC 偏移量）和类型 2（缩写）的 DateTimeZone 对象不包含任何转换，调用该方法时将返回 &false;。 + + + 如果提供了 timestampBegin，则返回数组中的第一个条目将包含发生在 + timestampBegin 时刻的转换元素。 + + + + 转换数组结构 + + + + 键 + 类型 + 说明 + + + + + ts + int + Unix 时间戳 + + + time + string + DateTimeInterface::ISO8601_EXPANDED（PHP 8.2 及以后）或 DateTimeInterface::ISO8601（PHP 8.1 及以前）的时间字符串 + + + offset + int + UTC 偏移量，单位为秒 + + + isdst + bool + 是否处于夏令时 + + + abbr + string + 时区缩写 + + + +
+ + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.1.0 + + The default value of timestampEnd has been changed to 2147483647. Previously, + it was PHP_INT_MAX. + + + + + + + + + &reftitle.examples; + + + A <function>timezone_transitions_get</function> example + +getTransitions(); +print_r(array_slice($transitions, 0, 3)); +?> +]]> + + &example.outputs.similar; + + Array + ( + [ts] => -2147483648 + [time] => 1901-12-13T20:45:52+00:00 + [offset] => -75 + [isdst] => + [abbr] => LMT + ) + + [1] => Array + ( + [ts] => 442304971 + [time] => 1847-12-01T00:01:15+00:00 + [offset] => 0 + [isdst] => + [abbr] => GMT + ) + + [2] => Array + ( + [ts] => -1691964000 + [time] => 1916-05-21T02:00:00+00:00 + [offset] => 3600 + [isdst] => 1 + [abbr] => BST + ) + +) +]]> + + + + + A <function>timezone_transitions_get</function> example with + <parameter>timestampBegin</parameter> set + +getTransitions(time()); +print_r(array_slice($transitions, 0, 3)); +?> +]]> + + &example.outputs.similar; + + Array + ( + [ts] => 1759058251 + [time] => 2025-09-28T11:17:31+00:00 + [offset] => 3600 + [isdst] => 1 + [abbr] => BST + ) + + [1] => Array + ( + [ts] => 1761440400 + [time] => 2025-10-26T01:00:00+00:00 + [offset] => 0 + [isdst] => + [abbr] => GMT + ) + + [2] => Array + ( + [ts] => 1774746000 + [time] => 2026-03-29T01:00:00+00:00 + [offset] => 3600 + [isdst] => 1 + [abbr] => BST + ) + +) +]]> + + + + + + + diff --git a/reference/datetime/formats.xml b/reference/datetime/formats.xml new file mode 100644 index 000000000..ae6141666 --- /dev/null +++ b/reference/datetime/formats.xml @@ -0,0 +1,1146 @@ + + + + + 支持的日期和时间格式 + + + 本节以 BNF 类似的格式描述了所有不同的格式，这些格式被 + DateTimeImmutable、DateTime、 + date_create_immutable、 + date_create、date_parse 和 + strtotime 解析器理解。格式按节分组。在大多数情况下，不同节的格式可以通过空格、逗号或点分隔，在同一个日期/时间字符串中使用。对于每个支持的格式，给出一个或多个示例，以及格式的描述。格式中单引号内的字符不区分大小写（'t' 可以是 t 或 T），双引号内的字符区分大小写（"T" 只能是 T）。 + + + 要格式化 DateTimeImmutable 和 + DateTime 对象，请参考 + DateTimeInterface::format 方法的文档。 + + + + 应该考虑一套通用规则。 + + + + + 解析器允许每个单位（年、月、日、小时、分钟、秒）使用完整的值范围。对于年份，就是 4 位数字，对于月份是 0-12，日是 0-31，小时是 0-24，分钟是 0-59。 + + + + + 秒允许 60，因为有时日期字符串会出现闰秒。但 PHP 实现 Unix 时间，其中 "60" 不是有效的秒数，因此会溢出。 + + + + + strtotime 如果任何数字超出范围，则返回 &false;，而 DateTimeImmutable::__construct 会抛出异常。 + + + + + 如果字符串包含日期，所有时间元素都会重置为 0。 + + + + + 如果给定字符串中存在时间的任何部分，所有较低有效性的时间元素都会重置为 0。 + + + + + 解析器是愚蠢的，不会进行任何检查以使其更快（并且更通用）。 + + + + + 除了单个时间元素的规则外，解析器还理解更具体的复合格式，例如解析 Unix 时间戳（@1690388256）和 ISO 周日期（2008-W28-3）。 + + + + + 如果提供了无效日期，还有一个额外的检查： + + + + + &example.outputs; + + + string(27) "The parsed date was invalid" +} +]]> + + + + + + + 已经可以处理边缘情况，但必须使用 DateTimeImmutable::createFromFormat 并提供正确的格式。 + + + + + &example.outputs; + + + string(26) "2015-10-04 17:24:43.000000" + ["timezone_type"]=> + int(3) + ["timezone"]=> + string(13) "Europe/London" +} +]]> + + + + + + + + + 时间格式 + + + 本页以 BNF 类似的语法描述了不同的日期/时间格式，这些格式被 DateTimeImmutable、DateTime、date_create、date_create_immutable 和 strtotime 解析器理解。 + + + 要格式化 DateTimeImmutable 和 + DateTime 对象，请参考 + DateTimeInterface::format 方法的文档。 + + + + 使用的符号 + + + + 描述 + 格式 + 示例 + + + + + frac + . [0-9]+ + ".21342", ".85" + + + hh + "0"?[1-9] | "1"[0-2] + "04", "7", "12" + + + HH + [01][0-9] | "2"[0-4] + "04", "07", "19" + + + meridian + [AaPp] .? [Mm] .? [\0\t ] + "A.m.", "pM", "am." + + + MM + [0-5][0-9] + "00", "12", "59" + + + II + [0-5][0-9] + "00", "12", "59" + + + space + [ \t] + + + + tz + "("? [A-Za-z]{1,6} ")"? | [A-Z][a-z]+([_/][A-Z][a-z]+)+ + "CEST", "Europe/Amsterdam", "America/Indiana/Knox" + + + tzcorrection + "GMT"? [+-] hh ":"? MM? + "+0400", "GMT-07:00", "-07:00" + + + +
+ + + 12 小时制 + + + + 描述 + 格式 + 示例 + + + + + 仅小时，带上午/下午标记 + hh space? meridian + "4 am", "5PM" + + + 小时和分钟，带上午/下午标记 + hh [.:] MM space? meridian + "4:08 am", "7:19P.M." + + + 小时、分钟和秒，带上午/下午标记 + hh [.:] MM [.:] II space? meridian + "4:08:37 am", "7:19:19P.M." + + + MS SQL（带上午/下午标记的小时、分钟、秒和小数） + hh ":" MM ":" II [.:] [0-9]+ meridian + "4:08:39:12313am" + + + +
+ + + 24 小时制 + + + + 描述 + 格式 + 示例 + + + + + 小时和分钟 + 't'? HH [.:] MM + "04:08", "19.19", "T23:43" + + + 小时和分钟，无冒号 + 't'? HH MM + "0408", "t1919", "T2343" + + + 小时、分钟和秒 + 't'? HH [.:] MM [.:] II + "04.08.37", "t19:19:19" + + + 小时、分钟和秒，无冒号 + 't'? HH MM II + "040837", "T191919" + + + 小时、分钟、秒和时区 + 't'? HH [.:] MM [.:] II space? ( tzcorrection | tz ) + "040837CEST", "T191919-0700" + + + 小时、分钟、秒和小数 + 't'? HH [.:] MM [.:] II frac + "04.08.37.81412", "19:19:19.532453" + + + 时区信息 + tz | tzcorrection + "CEST", "Europe/Amsterdam", "+0430", "GMT-06:00" + + + +
+ + + + + + 日期格式 + + + 本页以 BNF 类似的语法描述了不同的日期格式，这些格式被 DateTimeImmutable、DateTime、date_create、date_create_immutable 和 strtotime 解析器理解。 + + + 要格式化 DateTimeImmutable 和 + DateTime 对象，请参考 + DateTimeInterface::format 方法的文档。 + + + + 使用的符号 + + + + 描述 + 格式 + 示例 + + + + + daysuf + "st" | "nd" | "rd" | "th" + + + + dd + ([0-2]?[0-9] | "3"[01]) daysuf? + "7th", "22nd", "31" + + + DD + "0" [0-9] | [1-2][0-9] | "3" [01] + "07", "31" + + + m + 'january' | 'february' | 'march' | 'april' | 'may' | 'june' | + 'july' | 'august' | 'september' | 'october' | 'november' | 'december' | + 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | + 'sept' | 'oct' | 'nov' | 'dec' | "I" | "II" | "III" | "IV" | "V" | "VI" + | "VII" | "VIII" | "IX" | "X" | "XI" | "XII" + + + + M + 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | + 'sep' | 'sept' | 'oct' | 'nov' | 'dec' + + + + mm + "0"? [0-9] | "1"[0-2] + "0", "04", "7", "12" + + + MM + "0" [0-9] | "1"[0-2] + "00", "04", "07", "12" + + + y + [0-9]{1,4} + "00", "78", "08", "8", "2008" + + + yy + [0-9]{2} + "00", "08", "78" + + + YY + [0-9]{4} + "2000", "2008", "1978" + + + YYY + [0-9]{5,19} + "81412", "20192" + + + +
+ + + 本地化表示法 + + + + 描述 + 格式 + 示例 + + + + + 美式 月/日 + mm "/" dd + "5/12", "10/27" + + + 美式 月/日/年 + mm "/" dd "/" y + "12/22/78", "1/17/2006", "1/17/6" + + + 四位年份 斜杠分隔 年/月/日 + YY "/" mm "/" dd + "2008/6/30", "1978/12/22" + + + 四位年份与月份（GNU 规范） + YY "-" mm + "2008-6", "2008-06", "1978-12" + + + 短横线分隔 年-月-日 + y "-" mm "-" dd + "2008-6-30", "78-12-22", "8-6-21" + + + 日、月、四位年份（点/制表符/短横线分隔） + dd [.\t-] mm [.-] YY + "30-6-2008", "22.12.1978" + + + 日、月、两位年份（点/制表符分隔） + dd [.\t] mm "." yy + "30.6.08", "22\t12.78" + + + 日期、文字月份与年份 + dd ([ \t.-])* m ([ \t.-])* y + "30-June 2008", "22DEC78", "14 III 1879" + + + 文字月份+四位年份（日期默认补 1 日） + m ([ \t.-])* YY + "June 2008", "DEC1978", "March 1879" + + + 四位年份+文字月份（日期默认补 1 日） + YY ([ \t.-])* m + "2008 June", "1978-XII", "1879.MArCH" + + + 文字月份、日期与年份 + m ([ .\t-])* dd [,.stndrh\t ]+ y + "July 1st, 2008", "April 17, 1790", "May.9,78" + + + 文字月份与日期 + m ([ .\t-])* dd [,.stndrh\t ]* + "July 1st,", "Apr 17", "May.9" + + + 日期与文字月份 + dd ([ .\t-])* m + "1 July", "17 Apr", "9.May" + + + 月份缩写、日期与年份 + M "-" DD "-" y + "May-09-78", "Apr-17-1790" + + + 年份、月份缩写与日期 + y "-" M "-" DD + "78-Dec-22", "1814-MAY-17" + + + 年份（仅四位年份） + YY + "1978", "2008" + + + 扩展年份（带正负号，5-19 位数字） + [+-] YYY + "-81120", "+20192" + + + 文字月份（仅月份文本） + m + "March", "jun", "DEC" + + + +
+ + + ISO 8601 格式规范 + + + + 描述 + 格式 + 示例 + + + + + 八位数字年月日 + YY MM DD + "15810726", "19780417", "18140517" + + + 斜杠分隔四位数字年月日 + YY "/" MM "/" DD + "2008/06/30", "1978/12/22" + + + 短横线分隔两位数字年月日 + yy "-" MM "-" DD + "08-06-30", "78-12-22" + + + 可带正负号的四位数字年月日 + [+-]? YY "-" MM "-" DD + "-0002-07-26", "+1978-04-17", "1814-05-17" + + + 必须带正负号的五位及以上数字年月日 + [+-] YYY "-" MM "-" DD + "-81120-02-26", "+20192-04-17" + + + +
+ + + + 对于 y 和 yy + 格式，使用这两个符号解析小于 100 的年份时会采用特殊处理规则。 + 如果年份处于 0（含）至 69（含）的范围，会自动加上 2000； + 如果年份处于 70（含）至 99（含）的范围，则自动加上 1900。 + 这意味着字符串 "00-01-01" 会被解析为 "2000-01-01"。 + + + + + + “日、月、两位年份（点号或制表符分隔）”格式 + （dd [.\t] mm "." + yy）仅适用于年份值为 61（含） + 至 99（含）的场景；超出该年份范围时，时间格式 + "HH [.:] MM + [.:] SS" 会优先匹配。 + + + + + + “年份（仅年份）”格式仅在已成功解析到时间字符串时才能稳定生效。 + 否则，若四位年份与 HH MM 格式匹配， + 这部分内容会被识别为时间元素而非年份。 + + + 如需稳定地仅解析年份，请使用 + DateTimeImmutable::createFromFormat 并搭配 + Y 格式符。 + + + + + + dd 和 DD 格式支持日期的上下溢出。 + 日期 0 表示上个月的最后一天，而超出当月天数的日期会顺延到下个月。 + 这使得 "2008-08-00" 等价于 "2008-07-31"， + "2008-06-31" 等价于 "2008-07-01"（六月只有 30 天）。 + + + 请注意，如上方正则表达式所示，日期范围被限制为 0-31。 + 因此，例如 "2008-06-32" 就不是一个合法的日期字符串。 + + + mm 和 MM 格式同样支持值为 0 的下溢。 + 月份值为 0 表示上一年的十二月。 + 例如 "2008-00-22" 等价于 "2007-12-22"。 + + + 如果结合以上两种情况，日期和月份同时下溢，会发生如下转换： + "2008-00-00" 首先会被转换为 "2007-12-00"， + 然后进一步转换为 "2007-11-30"。 + 字符串 "0000-00-00" 也会发生同样的转换，最终变为 "-0001-11-30" + （这是 ISO 8601 历法中的 -1 年，对应于推衍格里高利历的公元前 2 年）。 + + + + + + + + 复合格式 + + + 本页以 BNF 类似的语法描述了不同的复合日期/时间格式，这些格式被 DateTimeImmutable、DateTime、date_create、date_create_immutable 和 strtotime 解析器理解。 + + + 要格式化 DateTimeImmutable 和 + DateTime 对象，请参考 + DateTimeInterface::format 方法的文档。 + + + + 使用的符号 + + + + 说明 + 格式 + 示例 + + + + + DD + "0" [0-9] | [1-2][0-9] | "3" [01] + "02", "12", "31" + + + doy + "00"[1-9] | "0"[1-9][0-9] | [1-2][0-9][0-9] | "3"[0-5][0-9] | "36"[0-6] + "001", "012", "180", "350", "366" + + + frac + . [0-9]+ + ".21342", ".85" + + + hh + "0"?[1-9] | "1"[0-2] + "04", "7", "12" + + + HH + [01][0-9] | "2"[0-4] + "04", "07", "19" + + + meridian + [AaPp] .? [Mm] .? [\0\t ] + "A.m.", "pM", "am." + + + ii + [0-5]?[0-9] + "04", "8", "59" + + + II + [0-5][0-9] + "04", "08", "59" + + + M + 'jan' | 'feb' | 'mar' | 'apr' | 'may' | 'jun' | 'jul' | 'aug' | 'sep' | 'sept' | 'oct' | 'nov' | 'dec' + + + + MM + [0-1][0-9] + "00", "12" + + + space + [ \t] + + + + ss + ([0-5]?[0-9])|60 + "04", "8", "59", "60" (leap second) + + + SS + [0-5][0-9] + "04", "08", "59" + + + W + "0"[1-9] | [1-4][0-9] | "5"[0-3] + "05", "17", "53" + + + tzcorrection + "GMT"? [+-] hh ":"? II? + "+0400", "GMT-07:00", "-07:00" + + + YY + [0-9]{4} + "2000", "2008", "1978" + + + +
+ + + 标准格式 + + + + 说明 + 示例 + + + + + ATOM + "2022-06-02T16:58:35+00:00" + + + COOKIE + "Thursday, 02-Jun-2022 16:58:35 UTC" + + + ISO8601 + "2022-06-02T16:58:35+0000" + + + RFC 822 + "Thu, 02 Jun 22 16:58:35 +0000" + + + RFC 850 + "Thursday, 02-Jun-22 16:58:35 UTC" + + + RFC 1036 + "Thu, 02 Jun 22 16:58:35 +0000" + + + RFC 1123 + "Thu, 02 Jun 2022 16:58:35 +0000" + + + RFC 2822 + "Thu, 02 Jun 2022 16:58:35 +0000" + + + RFC 3339 + "2022-06-02T16:58:35+00:00" + + + RFC 3339 Extended + "2022-06-02T16:58:35.698+00:00" + + + RFC 7231 + "Thu, 02 Jun 2022 16:58:35 GMT" + + + RSS + "Thu, 02 Jun 2022 16:58:35 +0000" + + + W3C + "2022-06-02T16:58:35+00:00" + + + +
+ + + 本地化格式 + + + + 说明 + 格式 + 示例 + + + + + 通用日志格式 + dd "/" M "/" YY : HH ":" II ":" SS space tzcorrection + "10/Oct/2000:13:55:36 -0700" + + + EXIF 格式 + YY ":" MM ":" DD " " HH ":" II ":" SS + "2008:08:07 18:11:31" + + + ISO 年份与 ISO 周数 + YY "-"? "W" W + "2008W27", "2008-W28" + + + ISO 年份、ISO 周数与星期 + YY "-"? "W" W "-"? [0-7] + "2008W273", "2008-W28-3" + + + MySQL 格式 + YY "-" MM "-" DD " " HH ":" II ":" SS + "2008-08-07 18:11:31" + + + PostgreSQL：年份与年内天数 + YY "."? doy + "2008.197", "2008197" + + + SOAP 格式 + YY "-" MM "-" DD "T" HH ":" II ":" SS frac tzcorrection? + "2008-07-01T22:35:17.02", "2008-07-01T22:35:17.03+08:00" + + + Unix 时间戳 + "@" "-"? [0-9]+ + "@1215282385" + + + 含微秒的 Unix 时间戳 + "@" "-"? [0-9]+ "." [0-9]{0,6} + "@1607974647.503686" + + + XMLRPC 格式 + YY MM DD "T" hh ":" II ":" SS + "20080701T22:38:07", "20080701T9:38:07" + + + XMLRPC（紧凑格式） + YY MM DD 't' hh II SS + "20080701t223807", "20080701T093807" + + + WDDX 格式 + YY "-" mm "-" dd "T" hh ":" ii ":" ss + "2008-7-1T9:3:37" + + + +
+ + + + “ISO 年份与 ISO 周数”和“ISO 年份、ISO 周数与星期”格式中的 + “W” 区分大小写，仅可使用大写字母 “W”。 + + + SOAP、XMLRPC 及 WDDX 格式中的 “T” 区分大小写， + 仅可使用大写字母 “T”。 + + + “Unix 时间戳”格式会将时区设定为协调世界时（UTC）。 + + + + + + + + 相对格式 + + 本页面使用类 BNF 语法描述了 DateTimeImmutable、 + DateTime、date_create、 + date_create_immutable 和 + strtotime 解析器支持的各类相对日期/时间格式。 + + + 如需格式化 DateTimeImmutable 和 + DateTime 对象，请参考 + DateTimeInterface::format 方法的文档。 + + + + 使用的符号 + + + + 说明 + 格式 + + + + + dayname + 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | + 'friday' | 'saturday' | 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | + 'sat' + + + daytext + 'weekday' | 'weekdays' + + + number + [+-]?[0-9]+ + + + ordinal + 'first' | 'second' | 'third' | 'fourth' | 'fifth' | 'sixth' | + 'seventh' | 'eighth' | 'ninth' | 'tenth' | 'eleventh' | 'twelfth' | + 'next' | 'last' | 'previous' | 'this' + + + reltext + 'next' | 'last' | 'previous' | 'this' + + + space + [ \t]+ + + + unit + 'ms' | 'µs' | (( 'msec' | 'millisecond' | 'µsec' | 'microsecond' + | 'usec' | 'sec' | 'second' | 'min' | 'minute' | 'hour' | 'day' | + 'fortnight' | 'forthnight' | 'month' | 'year') 's'?) | 'weeks' | + daytext + + + +
+ + + 基于日期的表示法 + + + + 格式 + 说明 + 示例 + + + + + 'yesterday' + 昨天的午夜 + "yesterday 14:00" + + + 'midnight' + 时间设置为 00:00:00 + + + + 'today' + 时间设置为 00:00:00 + + + + 'now' + 当前时间——该关键字会被直接忽略 + + + + 'noon' + 时间设置为 12:00:00 + "yesterday noon" + + + 'tomorrow' + 明天的午夜 + + + + 'back of' hour + 指定小时的 15 分 + "back of 7pm", "back of 15" + + + 'front of' hour + 指定小时的 45 分 + "front of 5am", "front of 23" + + + 'first day of' + 设置为当前月份的第一天。该短语通常最好与后续的月份名称一起使用，因为它仅影响当前月份 + "first day of January 2008" + + + 'last day of' + 设置为当前月份的最后一天。该短语通常最好与后续的月份名称一起使用，因为它仅影响当前月份 + "last day of next month" + + + ordinal space dayname space 'of' + 计算当前月份的第 x 个星期几 + "first sat of July 2008" + + + 'last' space dayname space 'of' + 计算当前月份的最后一个星期几 + "last sat of July 2008" + + + number space? (unit | 'week') + 处理数值型的相对时间项 + "+5 weeks", "12 day", "-7 weekdays" + + + (ordinal | reltext) space unit + 处理文本型的相对时间项。last 和 previous 等价于 -1，this 无效果，next 等价于 +1。 + "fifth day", "second month", "last day", "previous year" + + + 'ago' + 对之前所有的相对时间项取反 + "2 days ago", "8 days ago 14:00", "2 months 5 days ago", "2 months ago 5 days", "2 days ago" + + + dayname + + 跳转到下一个同名日期。（参考 注释） + + "Monday" + + + reltext space 'week' + 处理特殊格式“星期几 + last/this/next week” + "Monday next week" + + + +
+ + + + 相对语句始终**在**非相对语句**之后**处理。这使得 "+1 week july 2008" 和 "july 2008 +1 week" 等价。 + + + 该规则的例外情况是："yesterday"、"midnight"、"today"、"noon" 和 "tomorrow"。注意 "tomorrow 11:00" 和 "11:00 tomorrow" 是不同的。假设今天是 "2008 年 7 月 23 日"，第一个会得到 "2008-07-24 11:00"，而第二个会得到 "2008-07-24 00:00"。原因是这五个语句会直接影响当前时间。 + + + 诸如 "first day of" 等关键字取决于相对格式字符串的使用上下文。如果与静态方法或函数一起使用，参照值是当前系统时间戳。但是，如果在 DateTime::modify 或 DateTimeImmutable::modify 中使用，参照值是调用 modify() 方法的对象。 + + + + + + 当当前星期几与日期/时间字符串中使用的星期几相同时，请注意以下说明。但是，当前星期几可能已由日期/时间字符串的非相对部分重新计算。 + + + + + "dayname" **不会**跳转到其他日期。（示例："Wed July 23rd, 2008" 表示 "2008-07-23"）。 + + + + + "number dayname" **不会**跳转到其他日期。（示例："1 wednesday july 23rd, 2008" 表示 "2008-07-23"）。 + + + + + "number week dayname" 会先加上周数，但**不会**跳转到其他日期。在这种情况下，"number week" 和 "dayname" 是两个独立的部分。（示例："+1 week wednesday july 23rd, 2008" 表示 "2008-07-30"）。 + + + + + "ordinal dayname" **会**跳转到其他日期。（示例 "first wednesday july 23rd, 2008" 表示 "2008-07-30"）。 + + + + + "number week ordinal dayname" 会先加上周数，然后**跳转**到其他日期。在这种情况下，"number week" 和 "ordinal dayname" 是两个独立的部分。（示例："+1 week first wednesday july 23rd, 2008" 表示 "2008-08-06"）。 + + + + + "ordinal dayname 'of' " **不会**跳转到其他日期。（示例："first wednesday of july 23rd, 2008" 表示 "2008-07-02"，因为带 'of' 的特定短语会将日期重置为 '1'，此处的 '23rd' 会被忽略）。 + + + + + 另请注意 "ordinal space dayname space 'of' " 和 "'last' space dayname space 'of' " 中的 "of" 有特殊作用。 + + + + + 它会将日期设置为 1。 + + + + + "ordinal dayname 'of' " **不会**跳转到其他日期。（示例："first tuesday of july 2008" 表示 "2008-07-01"）。 + + + + + "ordinal dayname " **会**跳转到其他日期。（示例："first tuesday july 2008" 表示 "2008-07-08"，另见上述列表中的第 4 点）。 + + + + + "'last' dayname 'of' " 取当前月份的最后一个指定星期几。（示例："last wed of july 2008" 表示 "2008-07-30"） + + + + + "'last' dayname" 取从当前日期开始的上一个指定星期几。（示例："last wed july 2008" 表示 "2008-06-25"；"july 2008" 首先将当前日期设置为 "2008-07-01"，然后 "last wed" 跳转到上一个星期三，即 "2008-06-25"）。 + + + + + + + 相对月份值是根据其经过的月份长度计算的。例如 "+2 month 2011-11-30" 会得到 "2012-01-30"。这是因为 11 月有 30 天，12 月有 31 天，总计 61 天。 + + + + + number 是**整数**；如果给出小数，点号（或逗号）可能会被解释为分隔符。例如，'+1.5 hours' 会被解析为 '+1 5 hours'，而不是 '+1 hour +30 minutes'。 + + + + + 更新日志 + + + + + + 版本 + 说明 + + + + + 8.4.0 + + number 现在再次接受加号后跟减号的格式，例如 +-2，以及其他多符号组合。 + + + + 8.2.0 + + number 不再接受加号后跟减号的格式，例如 +-2。 + + + + 7.0.8 + + 每周始终从星期一开始。此前，星期日也会被视为一周的开始。 + + + + + + + + + + + + + diff --git a/reference/datetime/functions/date-create-immutable.xml b/reference/datetime/functions/date-create-immutable.xml new file mode 100644 index 000000000..8ada991cb --- /dev/null +++ b/reference/datetime/functions/date-create-immutable.xml @@ -0,0 +1,68 @@ + + + + + + date_create_immutable + 创建一个新的 DateTimeImmutable 对象 + + + + &reftitle.description; + + DateTimeImmutablefalsedate_create_immutable + stringdatetime"now" + DateTimeZonenulltimezone&null; + + + 这是 DateTimeImmutable::__construct 的过程式版本。 + + + 与 DateTimeImmutable 构造函数不同，当传入的 + datetime 字符串无效时，它会返回 &false;，而不是抛出异常。 + + + + + &reftitle.parameters; + + See DateTimeImmutable::__construct. + + + + + &reftitle.returnvalues; + + Returns a new DateTimeImmutable instance &return.falseforfailure; + + + + + &reftitle.seealso; + + DateTimeImmutable::createFromFormat + + + + + + diff --git a/reference/datetime/functions/date-create.xml b/reference/datetime/functions/date-create.xml new file mode 100644 index 000000000..732b45739 --- /dev/null +++ b/reference/datetime/functions/date-create.xml @@ -0,0 +1,69 @@ + + + + + + date_create + 创建一个新的 DateTime 对象 + + + + &reftitle.description; + + DateTimefalsedate_create + stringdatetime"now" + DateTimeZonenulltimezone&null; + + + 这是 DateTime::__construct 的过程式版本。 + + + 与 DateTime 构造函数不同，当传入的 + datetime 字符串无效时，它会返回 &false;，而不是抛出异常。 + + + + + &reftitle.parameters; + + See DateTimeImmutable::__construct. + + + + + &reftitle.returnvalues; + + Returns a new DateTime instance &return.falseforfailure; + + + + + &reftitle.seealso; + + DateTimeImmutable::__construct + DateTimeImmutable::createFromFormat + DateTime::__construct + + + + + diff --git a/reference/datetime/functions/date-parse-from-format.xml b/reference/datetime/functions/date-parse-from-format.xml new file mode 100644 index 000000000..38a79287e --- /dev/null +++ b/reference/datetime/functions/date-parse-from-format.xml @@ -0,0 +1,258 @@ + + + + + + + date_parse_from_format + 根据指定格式获取给定日期的信息 + + + + &reftitle.description; + + arraydate_parse_from_format + stringformat + stringdatetime + + + 返回一个关联数组，包含给定日期/时间的详细信息。 + + + + + &reftitle.parameters; + + + + format + + + 有关 format 用法的文档，请参阅 + DateTimeImmutable::createFromFormat 的说明。 + 相同规则适用。 + + + + + datetime + + + 表示日期/时间的字符串。 + + + + + + + + + &reftitle.returnvalues; + + + 返回一个关联数组，包含给定日期/时间的详细信息。 + + + 返回数组包含键 year、 + month、day、hour、 + minute、second、 + fraction 和 is_localtime。 + + + 如果存在 is_localtime，则 zone_type + 表示时区类型。对于类型 1（UTC 偏移量），将 + 添加 zone 和 is_dst 字段；对于 + 类型 2（缩写），将添加 tz_abbr + 和 is_dst 字段；对于类型 3 + （时区标识符），将添加 tz_abbr 和 tz_id。 + + + 该数组还包含 warning_count 和 + warnings 字段。前者表示警告数量。 + warnings 数组元素的键表示在给定 + datetime 中发生警告的位置，值为描述警告的字符串。 + 下面的示例展示了此类警告。 + + + 该数组还包含 error_count 和 + errors 字段。前者表示发现的错误数量。 + errors 数组元素的键表示在给定 + datetime 中发生错误的位置，值为描述该错误的字符串。 + 下面的示例展示了此类错误。 + + + + 如果警告和错误发生在相同位置，warnings 和 + errors 数组中元素的数量可能少于 + warning_count 或 error_count。 + + + + + + &reftitle.errors; + + 当 datetime 包含 NULL 字节时，此函数会抛出 + ValueError。 + + + + + &reftitle.changelog; + + + + + &Version; + &Description; + + + + + 8.0.21, 8.1.8, 8.2.0 + + Now throws ValueError when NULL-bytes + are passed into datetime, which previously was silently + ignored. + + + + 7.2.0 + + The zone element of the returned array represents + seconds instead of minutes now, and its sign is inverted. For instance + -120 is now 7200. + + + + + + + + + &reftitle.examples; + + + <function>date_parse_from_format</function> example + + + + &example.outputs; + + 2009 + [month] => 1 + [day] => 6 + [hour] => 13 + [minute] => 0 + [second] => 0 + [fraction] => 0 + [warning_count] => 0 + [warnings] => Array + ( + ) + + [error_count] => 0 + [errors] => Array + ( + ) + + [is_localtime] => 1 + [zone_type] => 1 + [zone] => 3600 + [is_dst] => +) +]]> + + + + + + + <function>date_parse_from_format</function> with warnings example + + $message) { + echo "\tOn position {$position}: {$message}\n"; +} +]]> + + &example.outputs; + + + + + + + + + <function>date_parse_from_format</function> with errors example + + $message) { + echo "\tOn position {$position}: {$message}\n"; +} +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + DateTimeImmutable::createFromFormat + checkdate + + + + + + diff --git a/reference/datetime/functions/date-sun-info.xml b/reference/datetime/functions/date-sun-info.xml new file mode 100644 index 000000000..870f1764c --- /dev/null +++ b/reference/datetime/functions/date-sun-info.xml @@ -0,0 +1,304 @@ + + + + + + date_sun_info + 返回包含日出/日落及黎明/黄昏开始和结束信息的数组 + + + &reftitle.description; + + arraydate_sun_info + inttimestamp + floatlatitude + floatlongitude + + + + + &reftitle.parameters; + + + + timestamp + + + Unix 时间戳。 + + + + + latitude + + + 以度为单位的纬度。 + + + + + longitude + + + 以度为单位的经度。 + + + + + + + + + &reftitle.returnvalues; + + 返回一个数组，其结构在下列列表中详细说明： + + + + + sunrise + + + 日出的时间戳（天顶角 = 90°35'）。 + + + + + sunset + + + 日落的时间戳（天顶角 = 90°35'）。 + + + + + transit + + + 太阳位于天顶时的时间戳，即达到最高点时的时间戳。 + + + + + civil_twilight_begin + + + 民用黎明的开始（天顶角 = 96°）。它在 sunrise 结束。 + + + + + civil_twilight_end + + + 民用黄昏的结束（天顶角 = 96°）。它从 sunset 开始。 + + + + + nautical_twilight_begin + + + 航海黎明的开始（天顶角 = 102°）。它在 civil_twilight_begin 结束。 + + + + + nautical_twilight_end + + + 航海黄昏的结束（天顶角 = 102°）。它从 civil_twilight_end 开始。 + + + + + astronomical_twilight_begin + + + 天文黎明的开始（天顶角 = 108°）。它在 nautical_twilight_begin 结束。 + + + + + astronomical_twilight_end + + + 天文黄昏的结束（天顶角 = 108°）。它从 nautical_twilight_end 开始。 + + + + + + + 数组元素的值要么是 UNIX 时间戳，若太阳全天位于相应天顶角之下则为 &false;， + 若太阳全天位于相应天顶角之上则为 &true;。 + + + + + &reftitle.changelog; + + + + + + &Version; + &Description; + + + + + 7.2.0 + + 修正了关于本地午夜而非本地中午的计算方式，从而使结果略有变化。 + + + + + + + + + + &reftitle.examples; + + + <function>date_sun_info</function> 示例 + + $val) { + echo "$key: " . date("H:i:s", $val) . "\n"; +} +]]> + + &example.outputs; + + + + + + + + + 极夜示例，带一些处理 + + $value) { + echo + match ($value) { + true => 'always', + false => 'never', + default => date_create("@{$value}")->setTimeZone($tz)->format( 'H:i:s T' ), + }, + ": {$key}", + "\n"; +} +]]> + + &example.outputs; + + + + + + + + + 午夜太阳（挪威特罗姆瑟） + + + + &example.outputs; + + 1 + [sunset] => 1 + [transit] => 1656240426 + [civil_twilight_begin] => 1 + [civil_twilight_end] => 1 + [nautical_twilight_begin] => 1 + [nautical_twilight_end] => 1 + [astronomical_twilight_begin] => 1 + [astronomical_twilight_end] => 1 +) +]]> + + + + + + + 计算白昼长度（基辅） + + + + &example.outputs; + + + + + + + + + diff --git a/reference/datetime/functions/timezone-name-from-abbr.xml b/reference/datetime/functions/timezone-name-from-abbr.xml new file mode 100644 index 000000000..6fa60619a --- /dev/null +++ b/reference/datetime/functions/timezone-name-from-abbr.xml @@ -0,0 +1,117 @@ + + + + + + timezone_name_from_abbr + 根据缩写和 UTC 偏移量猜测时区名称 + + + &reftitle.description; + + stringfalsetimezone_name_from_abbr + stringabbr + intutcOffset-1 + intisDST-1 + + + + + &reftitle.parameters; + + + + abbr + + + 时区缩写。 + + + + + utcOffset + + + 与 GMT 的偏移量，单位为秒。默认为 -1，表示返回第一个与 + abbr 相符的时区。否则会先尝试精确偏移量匹配， + 如果未找到则返回第一个匹配任意偏移量的时区。 + + + + + isDST + + + 夏令时指示器。默认为 -1，表示搜索时不考虑该时区是否使用夏令时。 + 如果设置为 1，则认为 utcOffset 为夏令时偏移； + 如果设置为 0，则认为 utcOffset 为非夏令时偏移。 + 如果 abbr 不存在，则仅根据 + utcOffset 和 isDST 搜索时区。 + + + + + + + + + &reftitle.returnvalues; + + 成功时返回时区名称，失败时返回 &false;。 + + + + + &reftitle.examples; + + + A <function>timezone_name_from_abbr</function> example + + + + &example.outputs.similar; + + + + + + + + + &reftitle.seealso; + + + timezone_abbreviations_list + + + + + + +