reference/errorfunc/functions/set-error-handler.xml
23906aa9f613d0f67538e4292b220cebf624d5f2
...
...
@@ -9,38 +9,35 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>mixed</type><methodname>set_error_handler</methodname>
13
-
<methodparam><type>callable</type><parameter>error_handler</parameter></methodparam>
14
-
<methodparam choice="opt"><type>int</type><parameter>error_types</parameter><initializer>E_ALL | E_STRICT</initializer></methodparam>
12
+
<type class="union"><type>callable</type><type>null</type></type><methodname>set_error_handler</methodname>
13
+
<methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam>
14
+
<methodparam choice="opt"><type>int</type><parameter>error_levels</parameter><initializer><constant>E_ALL</constant></initializer></methodparam>
15
15
</methodsynopsis>
16
16
<para>
17
-
Sets a user function (<parameter>error_handler</parameter>) to handle
17
+
Sets a user function (<parameter>callback</parameter>) to handle
18
18
errors in a script.
19
19
</para>
20
20
<para>
21
-
This function can be used for defining your own way of handling errors
22
-
during runtime, for example in applications in which you need to do
23
-
cleanup of data/files when a critical error happens, or when you need
24
-
to trigger an error under certain conditions (using
25
-
<function>trigger_error</function>).
21
+
This function can be used to define custom error handlers during runtime,
22
+
for example in applications which need to do file/data cleanup when a critical
23
+
error happens, or when triggering an error in response to certain conditions
24
+
(using <function>trigger_error</function>).
26
25
</para>
27
26
<para>
28
27
It is important to remember that the standard PHP error handler is completely
29
-
bypassed for the error types specified by <parameter>error_types</parameter>
28
+
bypassed for the error types specified by <parameter>error_levels</parameter>
30
29
unless the callback function returns &false;.
31
-
<function>error_reporting</function> settings will have no effect and your
32
-
error handler will be called regardless - however you are still able to read
33
-
the current value of
30
+
<function>error_reporting</function> settings will have no effect and the
31
+
error handler will be called regardless - however, it's still possible to
32
+
read the current value of
34
33
<link linkend="ini.error-reporting">error_reporting</link> and act
35
-
appropriately. Of particular note is that this value will be 0 if the
36
-
statement that caused the error was prepended by the
37
-
<link linkend="language.operators.errorcontrol">@ error-control
38
-
operator</link>.
34
+
appropriately.
39
35
</para>
40
36
<para>
41
-
Also note that it is your responsibility to <function>die</function> if
42
-
necessary. If the error-handler function returns, script execution
43
-
will continue with the next statement after the one that caused an error.
37
+
Also note that it is the handler's responsibility to stop the
38
+
script's execution if necessary by calling <function>exit</function>. If the error-handler
39
+
function returns, script execution will continue with the next statement
40
+
after the one that caused an error.
44
41
</para>
45
42
<para>
46
43
The following error types cannot be handled with a user defined
...
...
@@ -63,13 +60,11 @@
63
60
<para>
64
61
<variablelist>
65
62
<varlistentry>
66
-
<term><parameter>error_handler</parameter></term>
63
+
<term><parameter>callback</parameter></term>
67
64
<listitem>
68
65
<para>
69
-
A callback with the following signature.
70
-
&null; may be passed instead, to reset this handler to its default state.
71
-
Instead of a function name, an array containing an object reference
72
-
and a method name can also be supplied.
66
+
If &null; is passed, the handler is reset to its default state.
67
+
Otherwise, the handler is a callback with the following signature:
73
68
</para>
74
69
<para>
75
70
<methodsynopsis>
...
...
@@ -85,7 +80,7 @@
85
80
<term><parameter>errno</parameter></term>
86
81
<listitem>
87
82
<simpara>
88
-
The first parameter, <parameter>errno</parameter>, contains the
83
+
The first parameter, <parameter>errno</parameter>, will be passed the
89
84
level of the error raised, as an integer.
90
85
</simpara>
91
86
</listitem>
...
...
@@ -94,7 +89,7 @@
94
89
<term><parameter>errstr</parameter></term>
95
90
<listitem>
96
91
<simpara>
97
-
The second parameter, <parameter>errstr</parameter>, contains the
92
+
The second parameter, <parameter>errstr</parameter>, will be passed the
98
93
error message, as a string.
99
94
</simpara>
100
95
</listitem>
...
...
@@ -103,8 +98,8 @@
103
98
<term><parameter>errfile</parameter></term>
104
99
<listitem>
105
100
<simpara>
106
-
The third parameter is optional, <parameter>errfile</parameter>,
107
-
which contains the filename that the error was raised in, as a string.
101
+
If the callback accepts a third parameter, <parameter>errfile</parameter>,
102
+
it will be passed the filename that the error was raised in, as a string.
108
103
</simpara>
109
104
</listitem>
110
105
</varlistentry>
...
...
@@ -112,8 +107,8 @@
112
107
<term><parameter>errline</parameter></term>
113
108
<listitem>
114
109
<simpara>
115
-
The fourth parameter is optional, <parameter>errline</parameter>,
116
-
which contains the line number the error was raised at, as an integer.
110
+
If the callback accepts a fourth parameter, <parameter>errline</parameter>,
111
+
it will be passed the line number where the error was raised, as an integer.
117
112
</simpara>
118
113
</listitem>
119
114
</varlistentry>
...
...
@@ -121,17 +116,19 @@
121
116
<term><parameter>errcontext</parameter></term>
122
117
<listitem>
123
118
<simpara>
124
-
The fifth parameter is optional, <parameter>errcontext</parameter>,
125
-
which is an array that points to the active symbol table at the point
126
-
the error occurred. In other words, <parameter>errcontext</parameter>
119
+
If the callback accepts a fifth parameter, <parameter>errcontext</parameter>,
120
+
it will be passed an array that points to the active symbol table at the
121
+
point the error occurred. In other words, <parameter>errcontext</parameter>
127
122
will contain an array of every variable that existed in the scope the
128
123
error was triggered in.
129
-
User error handler must not modify error context.
124
+
User error handlers must not modify the error context.
130
125
</simpara>
131
126
<warning xmlns="http://docbook.org/ns/docbook">
132
127
<simpara>
133
-
This parameter has been <emphasis>DEPRECATED</emphasis> as of PHP 7.2.0.
134
-
Relying on it is highly discouraged.
128
+
This parameter has been <emphasis>DEPRECATED</emphasis> as of PHP 7.2.0,
129
+
and <emphasis>REMOVED</emphasis> as of PHP 8.0.0. If the function defines
130
+
this parameter without a default, an error of "too few arguments" will be
131
+
raised when it is called.
135
132
</simpara>
136
133
</warning>
137
134
</listitem>
...
...
@@ -144,16 +141,14 @@
144
141
</listitem>
145
142
</varlistentry>
146
143
<varlistentry>
147
-
<term><parameter>error_types</parameter></term>
144
+
<term><parameter>error_levels</parameter></term>
148
145
<listitem>
149
146
<para>
150
147
Can be used to mask the triggering of the
151
-
<parameter>error_handler</parameter> function just like the <link
152
-
linkend="ini.error-reporting">error_reporting</link> ini setting
148
+
<parameter>callback</parameter> function just like the <link linkend="ini.error-reporting">error_reporting</link> ini setting
153
149
controls which errors are shown. Without this mask set the
154
-
<parameter>error_handler</parameter> will be called for every error
155
-
regardless to the setting of the <link
156
-
linkend="ini.error-reporting">error_reporting</link> setting.
150
+
<parameter>callback</parameter> will be called for every error
151
+
regardless to the setting of the <link linkend="ini.error-reporting">error_reporting</link> setting.
157
152
</para>
158
153
</listitem>
159
154
</varlistentry>
...
...
@@ -164,9 +159,9 @@
164
159
<refsect1 role="returnvalues">
165
160
&reftitle.returnvalues;
166
161
<para>
167
-
Returns a string containing the previously defined error handler (if any). If
168
-
the built-in error handler is used &null; is returned. &null; is also returned
169
-
in case of an error such as an invalid callback. If the previous error handler
162
+
Returns the previously defined error handler (if any). If
163
+
the built-in error handler is used &null; is returned.
164
+
If the previous error handler
170
165
was a class method, this function will return an indexed array with the class
171
166
and the method name.
172
167
</para>
...
...
@@ -185,6 +180,12 @@
185
180
</thead>
186
181
<tbody>
187
182
<row>
183
+
<entry>8.0.0</entry>
184
+
<entry>
185
+
<parameter>errcontext</parameter> was removed, and will no longer be passed to user callbacks.
186
+
</entry>
187
+
</row>
188
+
<row>
188
189
<entry>7.2.0</entry>
189
190
<entry>
190
191
<parameter>errcontext</parameter> became deprecated. Usage of this parameter now emits an <constant>E_DEPRECATED</constant> notice.
...
...
@@ -350,7 +351,6 @@ Aborting...<br />
350
351
</para>
351
352
</refsect1>
352
353
</refentry>
353
-

354
354
<!-- Keep this comment at the end of the file
355
355
Local variables:
356
356
mode: sgml
357
357