reference/errorfunc/functions/trigger-error.xml
72b70d7c3c3b2b87423641906da2db407c32c3c3
72b70d7c3c3b2b87423641906da2db407c32c3c3
...
...
@@ -9,9 +9,9 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>bool</type><methodname>trigger_error</methodname>
13
-
<methodparam><type>string</type><parameter>error_msg</parameter></methodparam>
14
-
<methodparam choice="opt"><type>int</type><parameter>error_type</parameter><initializer>E_USER_NOTICE</initializer></methodparam>
12
+
<type>true</type><methodname>trigger_error</methodname>
13
+
<methodparam><type>string</type><parameter>message</parameter></methodparam>
14
+
<methodparam choice="opt"><type>int</type><parameter>error_level</parameter><initializer><constant>E_USER_NOTICE</constant></initializer></methodparam>
15
15
</methodsynopsis>
16
16
<para>
17
17
Used to trigger a user error condition, it can be used in conjunction
...
...
@@ -30,7 +30,7 @@
30
30
<para>
31
31
<variablelist>
32
32
<varlistentry>
33
-
<term><parameter>error_msg</parameter></term>
33
+
<term><parameter>message</parameter></term>
34
34
<listitem>
35
35
<para>
36
36
The designated error message for this error. It's limited to 1024
...
...
@@ -40,12 +40,20 @@
40
40
</listitem>
41
41
</varlistentry>
42
42
<varlistentry>
43
-
<term><parameter>error_type</parameter></term>
43
+
<term><parameter>error_level</parameter></term>
44
44
<listitem>
45
45
<para>
46
-
The designated error type for this error. It only works with the E_USER
46
+
The designated error type for this error. It only works with the <constant>E_USER_<replaceable>*</replaceable></constant>
47
47
family of constants, and will default to <constant>E_USER_NOTICE</constant>.
48
48
</para>
49
+
<warning>
50
+
<simpara>
51
+
Passing <constant>E_USER_ERROR</constant> as the
52
+
<parameter>error_level</parameter> is now deprecated.
53
+
Throw an <exceptionname>Exception</exceptionname> or
54
+
call <function>exit</function> instead.
55
+
</simpara>
56
+
</warning>
49
57
</listitem>
50
58
</varlistentry>
51
59
</variablelist>
...
...
@@ -55,11 +63,59 @@
55
63
<refsect1 role="returnvalues">
56
64
&reftitle.returnvalues;
57
65
<para>
58
-
This function returns &false; if wrong <parameter>error_type</parameter> is
59
-
specified, &true; otherwise.
66
+
&return.true.always;
60
67
</para>
61
68
</refsect1>
62
69
70
+
<refsect1 role="errors">
71
+
&reftitle.errors;
72
+
<para>
73
+
This function throws a <classname>ValueError</classname> if
74
+
<parameter>error_level</parameter> is not one of
75
+
<constant>E_USER_ERROR</constant>, <constant>E_USER_WARNING</constant>,
76
+
<constant>E_USER_NOTICE</constant>, <constant>E_USER_DEPRECATED</constant>.
77
+
</para>
78
+
</refsect1>
79
+
80
+
<refsect1 role="changelog">
81
+
&reftitle.changelog;
82
+
<informaltable>
83
+
<tgroup cols="2">
84
+
<thead>
85
+
<row>
86
+
<entry>&Version;</entry>
87
+
<entry>&Description;</entry>
88
+
</row>
89
+
</thead>
90
+
<tbody>
91
+
<row>
92
+
<entry>8.4.0</entry>
93
+
<entry>
94
+
Passing <constant>E_USER_ERROR</constant> as the
95
+
<parameter>error_level</parameter> is now deprecated.
96
+
Throw an <exceptionname>Exception</exceptionname> or
97
+
call <function>exit</function> instead.
98
+
</entry>
99
+
</row>
100
+
<row>
101
+
<entry>8.4.0</entry>
102
+
<entry>
103
+
The function now has a return type of <type>true</type>
104
+
instead of <type>bool</type>.
105
+
</entry>
106
+
</row>
107
+
<row>
108
+
<entry>8.0.0</entry>
109
+
<entry>
110
+
The function now throws a <classname>ValueError</classname> if an invalid
111
+
<parameter>error_level</parameter> is specified. Previously, it returned &false;.
112
+
</entry>
113
+
</row>
114
+
</tbody>
115
+
</tgroup>
116
+
</informaltable>
117
+
</refsect1>
118
+
63
119
<refsect1 role="examples">
64
120
&reftitle.examples;
65
121
<para>
...
...
@@ -71,9 +127,11 @@
71
127
<programlisting role="php">
72
128
<![CDATA[
73
129
<?php
74
-
if ($divisor == 0) {
75
-
trigger_error("Cannot divide by zero", E_USER_ERROR);
130
+
$password = $_POST['password'] ?? '';
131
+
if ($password === '') {
132
+
trigger_error("Using an empty password is unsafe", E_USER_WARNING);
76
133
}
134
+
$hash = password_hash($password, PASSWORD_DEFAULT);
77
135
?>
78
136
]]>
79
137
</programlisting>
...
...
@@ -85,7 +143,7 @@ if ($divisor == 0) {
85
143
&reftitle.notes;
86
144
<warning>
87
145
<para>
88
-
HTML entities in <parameter>error_msg</parameter> are not
146
+
HTML entities in <parameter>message</parameter> are not
89
147
escaped. Use <function>htmlentities</function> on the message if
90
148
the error is to be displayed in a browser.
91
149
</para>
...
...
@@ -100,11 +158,11 @@ if ($divisor == 0) {
100
158
<member><function>set_error_handler</function></member>
101
159
<member><function>restore_error_handler</function></member>
102
160
<member>The <link linkend="errorfunc.constants">error level constants</link></member>
161
+
<member>The <classname>Deprecated</classname> attribute</member>
103
162
</simplelist>
104
163
</para>
105
164
</refsect1>
106
165
</refentry>
107
-
108
166
<!-- Keep this comment at the end of the file
109
167
Local variables:
110
168
mode: sgml
111
169