Skip to content

[Sync-EN] Document the exception handler stack behavior of PHP 8.3.0 and 8.3.5 #1791

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lacatoire wants to merge 1 commit into
base: master
Choose a base branch
from
+138 −20
Open

[Sync-EN] Document the exception handler stack behavior of PHP 8.3.0 and 8.3.5 #1791

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 66 additions & 10 deletions reference/errorfunc/functions/restore-exception-handler.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 4a6671fe697ead5b27603b56face01a2c4e7ebe5 Maintainer: tmn Status: ready -->
<!-- EN-Revision: 1cc803aaa07ac94ce8e3bfdf56f4b9ddd23326d3 Maintainer: tmn Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.restore-exception-handler" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
Expand All @@ -21,6 +21,29 @@
которым станет или пользовательская функция обработки исключений, если такую определили,
или встроенный обработчик.
</para>
<note>
<simpara>
Пока обработчик исключений выполняется, ни один обработчик исключений
не активен: начиная с PHP 8.3.0 движок снимает обработчик перед вызовом,
чтобы исключение, которое выбросил сам обработчик, не передавалось ему же.
</simpara>
<simpara>
Начиная с PHP 8.3.5 движок вдобавок помещает обработчик, который собирается
вызвать, в стек обработчиков. Поэтому вызов функции
<function>restore_exception_handler</function> изнутри обработчика исключений
снимает со стека эту запись и переустанавливает обработчик, который сейчас
выполняется; чтобы установить обработчик, который действовал до него,
требуется второй вызов.
</simpara>
<simpara>
Выполняющийся обработчик переустанавливается автоматически, когда он
возвращает управление, но только если в этот момент ни один обработчик
исключений не активен: обработчик, который вызвал функцию
<function>set_exception_handler</function> или
<function>restore_exception_handler</function>, дальше сам отвечает
за стек обработчиков.
</simpara>
</note>
</refsect1>

<refsect1 role="parameters">
Expand All @@ -35,6 +58,41 @@
</para>
</refsect1>

<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>8.3.5</entry>
<entry>
Обработчик исключений, который вызывают, теперь помещается в стек
обработчиков, поэтому вызов функции
<function>restore_exception_handler</function> изнутри обработчика
исключений переустанавливает обработчик, который сейчас выполняется;
чтобы восстановить обработчик, который действовал до него, теперь
требуется два вызова.
</entry>
</row>
<row>
<entry>8.3.0</entry>
<entry>
Активный обработчик исключений теперь снимается на время его работы.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
Expand Down Expand Up @@ -78,15 +136,13 @@ throw new Exception('Эта инструкция запустит первый

<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>set_exception_handler</function></member>
<member><function>get_exception_handler</function></member>
<member><function>set_error_handler</function></member>
<member><function>restore_error_handler</function></member>
<member><function>error_reporting</function></member>
</simplelist>
</para>
<simplelist>
<member><function>set_exception_handler</function></member>
<member><function>get_exception_handler</function></member>
<member><function>set_error_handler</function></member>
<member><function>restore_error_handler</function></member>
<member><function>error_reporting</function></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Expand Down
82 changes: 72 additions & 10 deletions reference/errorfunc/functions/set-exception-handler.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 4a6671fe697ead5b27603b56face01a2c4e7ebe5 Maintainer: rjhdby Status: ready -->
<!-- EN-Revision: 1cc803aaa07ac94ce8e3bfdf56f4b9ddd23326d3 Maintainer: rjhdby Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.set-exception-handler" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
Expand All @@ -20,6 +20,35 @@
для перехвата исключений, которые не отловили в блоке try-catch. Выполнение скрипта остановится
после вызова <parameter>callback</parameter>-функции.
</para>

<note>
<simpara>
Пока обработчик исключений выполняется, ни один обработчик исключений
не активен: начиная с PHP 8.3.0 движок снимает обработчик перед вызовом,
чтобы исключение, которое выбросил сам обработчик, не передавалось ему же.
Поэтому вызванная изнутри обработчика функция
<function>set_exception_handler</function> сообщает, что ранее определённого
обработчика нет.
</simpara>
<simpara>
Начиная с PHP 8.3.5 движок вдобавок помещает обработчик, который собирается
вызвать, в стек обработчиков, поэтому вызванная изнутри обработчика функция
<function>restore_exception_handler</function> переустанавливает обработчик,
который сейчас выполняется, а не тот, который действовал до него.
</simpara>
<simpara>
Выполняющийся обработчик переустанавливается автоматически, когда он
возвращает управление, но только если в этот момент ни один обработчик
исключений не активен. Как только обработчик вызвал функцию
<function>set_exception_handler</function> или
<function>restore_exception_handler</function>, автоматическое
восстановление пропускается, и активным остаётся тот обработчик,
который оставил сам обработчик.
</simpara>
<simpara>
Поэтому менять обработчик исключений изнутри него самого не рекомендуют.
</simpara>
</note>
</refsect1>

<refsect1 role="parameters">
Expand Down Expand Up @@ -62,6 +91,41 @@
</para>
</refsect1>

<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>8.3.5</entry>
<entry>
Обработчик исключений, который вызывают, теперь помещается в стек
обработчиков и переустанавливается, когда он возвращает управление,
если только обработчик сам не изменил стек.
</entry>
</row>
<row>
<entry>8.3.0</entry>
<entry>
Активный обработчик исключений теперь снимается на время его работы,
поэтому вызванная изнутри обработчика функция
<function>set_exception_handler</function> сообщает, что ранее
определённого обработчика нет.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
Expand Down Expand Up @@ -92,15 +156,13 @@ echo "Не выполняется\n";

<refsect1 role="seealso"><!-- {{{ -->
&reftitle.seealso;
<para>
<simplelist>
<member><function>get_exception_handler</function></member>
<member><function>restore_exception_handler</function></member>
<member><function>restore_error_handler</function></member>
<member><function>error_reporting</function></member>
<member><link linkend="language.exceptions">Исключения</link></member>
</simplelist>
</para>
<simplelist>
<member><function>get_exception_handler</function></member>
<member><function>restore_exception_handler</function></member>
<member><function>restore_error_handler</function></member>
<member><function>error_reporting</function></member>
<member><link linkend="language.exceptions">Исключения</link></member>
</simplelist>
</refsect1><!-- }}} -->

</refentry>
Expand Down
Loading