Update calendar and hash

php · Dec 11, 2023 · b7dc63a · b7dc63a
1 parent 2a93dad
commit b7dc63a
Show file tree

Hide file tree

Showing 2 changed files with 72 additions and 26 deletions.
diff --git a/reference/calendar/functions/easter-date.xml b/reference/calendar/functions/easter-date.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 789af834328bf5d492ed174a4fedb226ccaf4b27 Maintainer: mowangjuanzi Status: ready -->
+<!-- EN-Revision: a0fcdcb58023bd4cb017fdba511df29b9f7a25f5 Maintainer: mowangjuanzi Status: ready -->
 <refentry xml:id="function.easter-date" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>easter_date</refname>
@@ -17,11 +17,6 @@
   <para>
    返回指定年份的复活节午夜时的 Unix 时间戳。
   </para>
-  <warning>
-   <para>
-    如果指定的年份超出 Unix 时间戳（即通常在 32 位系统上指定 1970 年以前或 2037 年以后）的范围，该函数将生成一个警告。
-   </para>
-  </warning>
   <para>
    复活节的日期是由尼西亚议会在公元 325 年确定的为每年春分月圆后的第一个星期日。春分一般是在 3 月 21 
    日，这就简化为只要计算满月的日期和紧挨的星期日的日期。这里所用的算法是在 532 年由 Dionysius Exiguus
@@ -39,8 +34,8 @@
      <term><parameter>year</parameter></term>
      <listitem>
       <para>
-       1970 年至 2037 年之间的数字类型的年份。如果省略或者为 
-       &null;，则根据本地时间默认为当前年份。
+       对于 32 位系统，年份必须是 1970 至 2037 之间的数字，对于 64 位系统，年份必须是 1970 到 2,000,000,000
+       之间的数字。如果省略或者为 &null;，则根据本地时间默认为当前年份。
       </para>
      </listitem>
     </varlistentry>  
@@ -64,6 +59,14 @@
   </para>
  </refsect1>
 
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   如果年份早于 1970，或者晚于 32 位系统的 2037 以及 64 位系统上的 2,000,000,000
+   时会抛出 <classname>ValueError</classname>。
+  </para>
+ </refsect1>
+
  <refsect1 role="changelog">
   &reftitle.changelog;
   <informaltable>
@@ -75,12 +78,25 @@
      </row>
     </thead>
     <tbody>
+     <row>
+      <entry>8.3.0</entry>
+      <entry>
+       在 64 位系统上，<parameter>year</parameter> 参数现在接受范围在 1970 到 2,000,000,000 的值。
+      </entry>
+     </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
        <parameter>year</parameter> 现在可为空（nullable）。
       </entry>
      </row>
+     <row>
+      <entry>8.0.0</entry>
+      <entry>
+       当 <parameter>year</parameter> 超出允许的范围现在抛出 <classname>ValueError</classname>。之前函数会返回
+       &false; 会触发 <constant>E_WARNING</constant>。
+      </entry>
+     </row>
     </tbody>
    </tgroup>
   </informaltable>
@@ -99,6 +115,24 @@ echo date("M-d-Y", easter_date(1999));        // Apr-04-1999
 echo date("M-d-Y", easter_date(2000));        // Apr-23-2000
 echo date("M-d-Y", easter_date(2001));        // Apr-15-2001
 
+?>
+]]>
+    </programlisting>
+   </example>
+
+   <example>
+    <title>使用带 <classname>DateTime</classname> 的 <function>easter_date</function></title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+$timestamp = easter_date(2023);
+
+$datetime = new \DateTime();
+$datetime->setTimestamp($timestamp);
+
+echo $datetime->format('M-d-Y'); // Apr-09-2023
+
 ?>
 ]]>
     </programlisting>

diff --git a/reference/hash/functions/hash-equals.xml b/reference/hash/functions/hash-equals.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 91e303f2d27cbca485137230fa7d2e50e75f19a6 Maintainer: yuanyuqiang Status: ready -->
+<!-- EN-Revision: 472a8ae5cc4e91fcf8365760ba07787f61087aae Maintainer: yuanyuqiang Status: ready -->
 <!-- CREDITS: Luffy, mowangjuanzi -->
 <refentry xml:id="function.hash-equals" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -16,12 +16,17 @@
    <methodparam><type>string</type><parameter>user_string</parameter></methodparam>
   </methodsynopsis>
   <para>
-   比较两个字符串，无论它们是否相等，本函数的时间消耗是恒定的。
+   检查两个字符串是否相等，而不会通过执行时泄露有关 <parameter>known_string</parameter> 内容的任何信息。
   </para>
   <para>
-   本函数可以用在需要防止时序攻击的字符串比较场景中，
-   例如，可以用在比较 <function>crypt</function> 密码散列值的场景。
+   此函数可用于缓解计时攻击。使用 <code>===</code> 进行常规比较所需的时间的长短取决于两个值是否不同以及可以找到第一个不同的位置，从而泄露有关
+   <parameter>known_string</parameter> 内容的秘密信息。
   </para>
+  <caution>
+   <para>
+    非常重要的一点是，用户提供的字符串必须是第二个参数。
+   </para>
+  </caution>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -31,15 +36,15 @@
     <term><parameter>known_string</parameter></term>
     <listitem>
      <para>
-       已知长度的、要参与比较的 <type>string</type> 
+       必须保密的已知 &string;。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>user_string</parameter></term>
     <listitem>
      <para>
-      用户提供的字符串
+      与已知字符串进行比较的用户提供的 &string;。
      </para>
     </listitem>
    </varlistentry>
@@ -61,20 +66,24 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-$expected  = crypt('12345', '$2a$07$usesomesillystringforsalt$');
-$correct   = crypt('12345', '$2a$07$usesomesillystringforsalt$');
-$incorrect = crypt('apple', '$2a$07$usesomesillystringforsalt$');
+$secretKey = '8uRhAeH89naXfFXKGOEj';
 
-var_dump(hash_equals($expected, $correct));
-var_dump(hash_equals($expected, $incorrect));
+// 值和签名是由用户提供的，例如在 URL 中，使用 $_GET 检索。
+$value = 'username=rasmuslerdorf';
+$signature = '8c35009d3b50caf7f5d2c1e031842e6b7823a1bb781d33c5237cd27b57b5f327';
+
+if (hash_equals(hash_hmac('sha256', $value, $secretKey), $signature)) {
+    echo "The value is correctly signed.", PHP_EOL;
+} else {
+    echo "The value was tampered with.", PHP_EOL;
+}
 ?>
 ]]>
     </programlisting>
     &example.outputs;
     <screen>
 <![CDATA[
-bool(true)
-bool(false)
+The value is correctly signed.
 ]]>
     </screen>
    </example>
@@ -90,13 +99,16 @@ bool(false)
     在时序攻击的场景下，已知字符串的长度可能会被泄露。
    </para>
   </note>
-  <note>
-   <para>
-    非常重要的一点是，用户提供的字符串必须是第二个参数。
-   </para>
-  </note>
  </refsect1>
 
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>hash_hmac</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file