PHP 8.4: trigger_error() updates (#4063)

Author: Girgias

reference/errorfunc/functions/trigger-error.xml

@@ -46,6 +46,14 @@
        The designated error type for this error. It only works with the <constant>E_USER_<replaceable>*</replaceable></constant>
        family of constants, and will default to <constant>E_USER_NOTICE</constant>.
       </para>
+      <warning>
+       <simpara>
+        Passing <constant>E_USER_ERROR</constant> as the
+        <parameter>error_level</parameter> is now deprecated.
+        Throw an <exceptionname>Exception</exceptionname> or
+        call <function>exit</function> instead.
+       </simpara>
+      </warning>
      </listitem>
     </varlistentry>
    </variablelist>
@@ -80,6 +88,22 @@
      </row>
     </thead>
     <tbody>
+     <row>
+      <entry>8.4.0</entry>
+      <entry>
+       Passing <constant>E_USER_ERROR</constant> as the
+       <parameter>error_level</parameter> is now deprecated.
+       Throw an <exceptionname>Exception</exceptionname> or
+       call <function>exit</function> instead.
+      </entry>
+     </row>
+     <row>
+      <entry>8.4.0</entry>
+      <entry>
+       The function now has a return type of <type>true</type>
+       instead of <type>bool</type>.
+      </entry>
+     </row>
      <row>
       <entry>8.0.0</entry>
       <entry>
@@ -103,9 +127,11 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-if ($divisor == 0) {
-    trigger_error("Cannot divide by zero", E_USER_ERROR);
+$password = $_POST['password'] ?? '';
+if ($password === '') {
+  trigger_error("Using an empty password is unsafe", E_USER_WARNING);
 }
+$hash = password_hash($password, PASSWORD_DEFAULT);
 ?>
 ]]>
     </programlisting>
@@ -132,6 +158,7 @@ if ($divisor == 0) {
     <member><function>set_error_handler</function></member>
     <member><function>restore_error_handler</function></member>
     <member>The <link linkend="errorfunc.constants">error level constants</link></member>
+    <member>The <classname>Deprecated</classname> attribute</member>
    </simplelist>
   </para>
  </refsect1>