Update deprecated.xml (#516)

Co-authored-by: Sergey Panteleev <sergey@php.net>
2025-07-24 09:59:46 +00:00 · 2023-11-27 11:35:04 +03:00
parent eb55b45ba0
commit 15fbc5a3a4
3 changed files with 93 additions and 62 deletions
--- a/appendices/migration83/deprecated.xml
+++ b/appendices/migration83/deprecated.xml
@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: f037a94fd276a36a5061b0160fd3c2eafb20d980 Maintainer: sergey Status: ready -->
+<!-- EN-Revision: 9c828621cbce488cf6306b21c39e208f847eabd5 Maintainer: sergey Status: ready -->
 <!-- Reviewed: no -->
 <sect1 xml:id="migration83.deprecated">
 <title>Устаревшая функциональность</title>
@ -11,10 +11,11 @@
   <title>Операторы Increment/Decrement</title>

   <para>
-    Использование оператора <link linkend="language.operators.increment">increment</link> (<literal>++</literal>) для пустых,
-    нечисловых или не буквенно-числовых строк теперь устарело.
-    Более того, инкремент нечисловых строк, мягко говоря, устарел и вместо него следует использовать новую
-    функцию <function>str_increment</function>.
+    Передача оператору <link linkend="language.operators.increment">increment</link> (<literal>++</literal>) пустых,
+    нечисловых или не буквенно-числовых строк устарела.
+    Притом инкрементирование нечисловых строк устарело мягко.
+    Понятие «мягкое устаревание» означает, что диагностика уровня <constant>E_DEPRECATED</constant> выполняться не будет,
+    но нужно отказаться от устаревших правил в новом коде. Вместо устаревшего способа инкрементирования необходимо вызывать новую функцию <function>str_increment</function>.
   </para>

   <para>
@ -57,7 +58,8 @@
  <para>
   Константа <constant>U_MULTIPLE_DECIMAL_SEP*E*RATORS</constant> устарела,
   вместо неё рекомендуется использовать
-   константу <constant>U_MULTIPLE_DECIMAL_SEP*A*RATORS</constant>.
+   константу
+   <constant>U_MULTIPLE_DECIMAL_SEP*A*RATORS</constant>.
  </para>
  <para>
   Константа <constant>NumberFormatter::TYPE_CURRENCY</constant> устарела.
@ -78,7 +80,8 @@

  <para>
   Передача отрицательного значения в параметр <parameter>$width</parameter>
-   функции <function>mb_strimwidth</function> устарела.
+   функции
+   <function>mb_strimwidth</function> устарела.
  </para>
 </sect2>

@ -87,8 +90,9 @@

  <para>
   Вызов метода <methodname>Phar::setStub</methodname>
-   с параметром <parameter>$resource</parameter> и <parameter>$length</parameter> устарел.
-   Такие вызовы должны быть заменены на: <code>$phar->setStub(stream_get_contents($resource));</code>.
+   с типом <type>resource</type> и параметром <parameter>$length</parameter> устарел.
+   Такие вызовы должны быть заменены на:
+   <code>$phar->setStub(stream_get_contents($resource));</code>.
  </para>
 </sect2>

@ -96,7 +100,7 @@
  <title>Random</title>

  <para>
-   Вариант <constant>MT_RAND_PHP</constant> Mt19937 устарел.
+   Вариант константы <constant>MT_RAND_PHP</constant> Mt19937 устарел.
  </para>
 </sect2>

@ -104,7 +108,8 @@
  <title>Reflection</title>

  <para>
-   Вызов метода <methodname>ReflectionProperty::setValue</methodname> только с одним параметром устарел.
+   Вызов метода <methodname>ReflectionProperty::setValue</methodname>
+   только с одним параметром устарел.
   Чтобы установить статические свойства, передайте &null; в качестве первого параметра.
  </para>
 </sect2>
@ -123,7 +128,8 @@

  <para>
   INI-параметры <literal>assert.*</literal> устарели.
-   Смотрите <link linkend="migration83.other-changes.ini">изменения в работе с INI-файлами</link>
+   Смотрите
+   <link linkend="migration83.other-changes.ini">изменения в работе с INI-файлами</link>
   для более подробной информации.
  </para>
 </sect2>
@ -132,7 +138,7 @@
  <title>SQLite3</title>

  <para>
-   Использование исключений теперь предпочтительнее, предупреждения будут удалены в будущем.
+   Работа с исключениями теперь предпочтительнее, предупреждения будут удалены в будущем.
   Вызов <code>SQLite3::enableExceptions(false)</code> в этой версии
   выдаст предупреждение об устаревании.
  </para>
--- a/language-snippets.ent
+++ b/language-snippets.ent
@ -508,8 +508,7 @@ xmlns="http://docbook.org/ns/docbook"><simpara>Функция объявлена
  <term><parameter>flags</parameter></term>
  <listitem>
   <para>
-    Необязательный второй параметр <parameter>flags</parameter>
-    может использоваться для изменения поведения сортировки с использованием следующих значений:
+    Необязательный второй параметр <parameter>flags</parameter> изменяет поведение сортировки и может принимать следующие значения:
   </para>
   <para>
    Флаги типа сортировки:
@ -1807,10 +1806,9 @@ linkend="book.mysqlnd">mysqlnd</link>.'>
 <para>Если количество строк больше, чем <constant>PHP_INT_MAX</constant>, число будет возвращено как строка (&string;).</para></note>'>

 <!ENTITY mysqli.sqlinjection.warning '<warning xmlns="http://docbook.org/ns/docbook">
-<title>Предупреждение безопасности: SQL-инъекция</title><para>Если запрос содержит какие-либо входные переменные, вместо этого следует
-использовать <link linkend="mysqli.quickstart.prepared-statements">подготавливаемые запросы</link>.
-В качестве альтернативы данные должны быть правильно отформатированы
-и все строки должны быть экранированы с помощью функции <function>mysqli_real_escape_string</function>.</para></warning>'>
+<title>Предупреждение безопасности: SQL-инъекция</title><para>Вместо составления строки запроса с включением переменных значений
+необходимо <link linkend="mysqli.quickstart.prepared-statements">подготавливать запросы</link>. Либо строки запроса должны быть экранированы
+функцией <function>mysqli_real_escape_string</function> и правильно отформатированы.</para></warning>'>

 <!ENTITY mysqli.conditionalexception '<para xmlns="http://docbook.org/ns/docbook">
 Если уведомления об ошибках mysqli включены (<constant>MYSQLI_REPORT_ERROR</constant>) и запрошенная операция не удалась,
--- a/reference/calendar/functions/easter-date.xml
+++ b/reference/calendar/functions/easter-date.xml
@ -1,12 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 789af834328bf5d492ed174a4fedb226ccaf4b27 Maintainer: tmn Status: ready -->
+<!-- EN-Revision: a0fcdcb58023bd4cb017fdba511df29b9f7a25f5 Maintainer: tmn Status: ready -->
 <!-- Reviewed: no -->
 <refentry xml:id="function.easter-date" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>easter_date</refname>
-  <refpurpose>
-   Получить метку времени Unix, соответствующую полуночи на Пасху в заданном году
-  </refpurpose>
+  <refpurpose>Получить метку времени Unix, соответствующую полуночи на Пасху в заданном году</refpurpose>
 </refnamediv>

 <refsect1 role="description">
@ -17,28 +15,17 @@
   <methodparam choice="opt"><type>int</type><parameter>mode</parameter><initializer><constant>CAL_EASTER_DEFAULT</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
-   Возвращает метку времени Unix, соответствующую полуночи
-   на Пасху в заданном году.
+   Возвращает метку времени Unix, соответствующую полуночи на Пасху в заданном году.
  </para>
-  <warning>
-   <para>
-    Функция выдаст предупреждение, если заданный год будет выходить
-    за пределы диапазона меток времени Unix (меньше 1970, либо больше 2037 для 32-битных систем).
-   </para>
-  </warning>
  <para>
-   Дата Пасхального дня была введена Консулом Никеи в 325 году до н.э.
-   Это первое воскресенье, следующее за первым полнолунием после
-   весеннего равноденствия. Днём весеннего равноденствия принято считать
-   21 марта, так что расчёт дня Пасхи сводится к определению даты
-   полнолуния и следующего за ней воскресенья. Используемый здесь
-   алгоритм введён Дионисием Малым в 532 году. В юлианском летоисчислении
-   (до 1753 года) для отслеживания фаз луны использовался простой
-   19-летний цикл. В григорианском календаре (годы после 1753 -
-   разработан Христофором Клавиусом и Алоизием Лилиусом и введён
-   Папой Григорием XIII в октябре 1582 г., а в Великобритании и её
-   колониях в сентябре 1752 г.) было добавлено 2 поправочных
-   коэффициента, увеличивающих точность расчёта дат.
+   Дата Пасхи была установлена на Первом Никейском соборе в 325 году до н. э.
+   в честь воскресенья, следовавшего за полнолунием, наступившим в день или после весеннего равноденствия.
+   Считалось, что День весеннего равноденствия всегда наступает 21 марта, поэтому расчёт дня Пасхи
+   сводился к определению даты полнолуния и следующего за ней воскресенья. Используемый здесь алгоритм
+   введён Дионисием Малым около 532 года. В юлианском летоисчислении (до 1753 года) для отслеживания фаз луны
+   использовался простой 19-летний цикл. В григорианском календаре (годы после 1753 - разработан Христофором Клавиусом
+   и Алоизием Лилиусом и введён Папой Григорием XIII в октябре 1582, а в Великобритании и её колониях
+   в сентябре 1752 г.) было добавлено 2 поправочных коэффициента, увеличивающих точность расчёта дат.
  </para>
 </refsect1>

@ -50,8 +37,8 @@
     <term><parameter>year</parameter></term>
     <listitem>
      <para>
-       Год - число между 1970 и 2037. Если не указан или &null;, то
-       по умолчанию равен текущему года, согласно местному времени.
+       Год должен быть числом от 1970 до 2037 для 32-битных или 2 000 000 000 для 64-битных систем.
+       Если не указан или &null;, будет использован текущий год по местному времени.
      </para>
     </listitem>
    </varlistentry>
@ -59,10 +46,8 @@
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
-       Позволяет рассчитывать даты Пасхи на основе юлианского календаря,
-       если установлено значение
-       <constant>CAL_EASTER_ALWAYS_JULIAN</constant>. Смотрите
-       также <link
+       Позволяет рассчитывать даты Пасхи на основе Юлианского календаря,
+       если установлено значение <constant>CAL_EASTER_ALWAYS_JULIAN</constant>. Смотрите также <link
        linkend="calendar.constants">константы календаря</link>.
       </para>
     </listitem>
@ -74,7 +59,15 @@
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
-   Дата Пасхи в виде метки времени Unix.
+   Возвращает дату Пасхи в виде метки времени Unix.
+  </para>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   Будет выброшено исключение <classname>ValueError</classname>, если значение года окажется меньше 1970 или больше 2037
+   для 32-битных или 2 000 000 000 для 64-битных систем.
  </para>
 </refsect1>

@ -89,10 +82,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> теперь допускает значение null.
+       Параметр <parameter>year</parameter> теперь может иметь значение &null;.
+      </entry>
+     </row>
+     <row>
+      <entry>8.0.0</entry>
+      <entry>
+       Будет выброшено исключение <classname>ValueError</classname>,
+       если значение параметра <parameter>year</parameter> выходит за пределы допустимого диапазона.
+       Ранее вызывалась ошибка уровня <constant>E_WARNING</constant>
+       и функция возвращала &false;.
      </entry>
     </row>
    </tbody>
@ -113,6 +121,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>Пример использования <function>easter_date</function> с объектом класса <classname>DateTime</classname></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>
@ -124,18 +150,19 @@ echo date("M-d-Y", easter_date(2001));        // Apr-15-2001
  &reftitle.notes;
  <note>
   <para>
-    Функция <function>easter_date</function> зависит от вашей системной библиотеки C функций
-    работы со временем, а не от внутренних функций PHP. Как следствие,
-    функция <function>easter_date</function> использует переменную
-    окружения <literal>TZ</literal> для определения часового пояса, а не заданный
-    в PHP <link linkend="ini.date.timezone">часовой пояс по умолчанию</link>.
-    Это может привести к неожиданному поведению при использовании этой функции
-    совместно с другими функциями для работы с датами в PHP.
+    Функция <function>easter_date</function> полагается на работающие со временем
+    системные функции библиотеки языка Си, а не на работающие с датой и временем внутренние функции PHP.
+    Вследствие этого для определения часового пояса,
+    в котором она должна работать, функция <function>easter_date</function>
+    использует переменную окружения <literal>TZ</literal>, а не заданный в PHP
+    <link linkend="ini.date.timezone">часовой пояс по умолчанию</link>, что может
+    привести к неожиданному поведению в сочетании с другими функциями PHP для работы с датами.
   </para>
   <para>
-    В качестве обходного решения может быть использование функции <function>easter_days</function> с
-    объектами <classname>DateTime</classname> и <classname>DateInterval</classname> для
-    подсчёта начала Пасхи в вашем часовом поясе, как в этом примере:
+    В качестве обходного пути для расчёта начала Пасхи в текущем часовом поясе PHP
+    можно использовать функцию <function>easter_days</function> с объектами классов
+    <classname>DateTime</classname> и <classname>DateInterval</classname>
+    следующим образом:
   </para>
   <informalexample>
    <programlisting role="php">
@ -175,7 +202,7 @@ foreach (range(2012, 2015) as $year) {
   <simplelist>
    <member>
     Функция <function>easter_days</function> для расчёта дня Пасхи
-     до 1970 или после 2037
+     до 1970 или после 2037 года
    </member>
   </simplelist>
  </para>