<?xml version="1.0" encoding="utf-8"?>

<!-- EN-Revision: 21ce7d7f4f9f6f241f3e09e7f0a5be5c504d90d2 Maintainer: sammywg Status: ready -->

<!-- Reviewed: yes -->

<!-- Rev-Revision: c44475e1fafcbee203ed4935a6d5d7a01379fcdc Reviewer: samesch -->

<refentry xml:id="function.set-error-handler" xmlns="http://docbook.org/ns/docbook">

<refnamediv>

<refname>set_error_handler</refname>

<refpurpose>Bestimmt eine benutzerdefinierte Funktion zur Fehlerbehandlung</refpurpose>

</refnamediv>

<refsect1 role="description">

&reftitle.description;

<methodsynopsis>

<type class="union"><type>callable</type><type>null</type></type><methodname>set_error_handler</methodname>

<methodparam><type class="union"><type>callable</type><type>null</type></type><parameter>callback</parameter></methodparam>

<methodparam choice="opt"><type>int</type><parameter>error_levels</parameter><initializer><constant>E_ALL</constant></initializer></methodparam>

</methodsynopsis>

<para>

Setzt eine benutzerdefinierte Funktion (<parameter>callback</parameter>),

um Fehler in einem Skript zu behandeln.

</para>

<para>

Mit dieser Funktion können während der Laufzeit benutzerdefinierte

Fehlerbehandlungen erstellt werden, beispielsweise in Anwendungen, die bei

einem kritischen Fehler die Löschung von Daten bzw. Dateien erfordert, oder

wenn es nötig ist, unter bestimmten Bedingungen (mit der Funktion

<function>trigger_error</function>) eine Fehlermeldung zu generieren.

</para>

<para>

Es ist unbedingt zu beachten, dass auf diese Weise die standardmäßige

PHP-Fehlerbehandlung für die durch <parameter>error_levels</parameter>

angegebenen Fehlertypen vollkommen umgangen wird, außer wenn die

Callback-Funktion &false; zurückgibt. Die Einstellungen der Funktion

<function>error_reporting</function> haben keine

Auswirkung und die Fehlerbehandlungsroutine wird ohne Rücksicht darauf

aufgerufen, es ist jedoch immer noch möglich, den aktuellen Wert von

<link linkend="ini.error-reporting">error_reporting</link> zu lesen und

entsprechend zu handeln.

</para>

<para>

Es ist auch zu beachten, dass die Fehlerbehandlung dafür zuständig ist, bei

Bedarf <function>exit</function> aufzurufen, um die Ausführung des Skripts

zu beenden. Nach der Funktion für die Fehlerbehandlung wird die Ausführung

des Skripts bei der Anweisung fortgesetzt, die auf die Fehler verursachende

Anweisung folgt.

</para>

<para>

Die folgenden Fehlertypen können nicht von einer benutzerdefinierten

Funktion behandelt werden: <constant>E_ERROR</constant>,

<constant>E_PARSE</constant>, <constant>E_CORE_ERROR</constant>,

<constant>E_CORE_WARNING</constant>, <constant>E_COMPILE_ERROR</constant>

und <constant>E_COMPILE_WARNING</constant> unabhängig davon, wo sie

ausgelöst wurden, und die meisten <constant>E_STRICT</constant>, die in der

Datei ausgelöst werden, in der <function>set_error_handler</function>

aufgerufen wird.

</para>

<para>

Falls Fehler auftreten, bevor das Skript ausgeführt wird (&zb; beim

Hochladen von Dateien), kann eine benutzerdefinierte Fehlerbehandlung nicht

aufgerufen werden, weil sie zu diesem Zeitpunkt noch nicht registriert ist.

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>callback</parameter></term>

<listitem>

<para>

Falls &null; übergeben wird, wird der Handler auf seinen Standardwert

zurückgesetzt. Andernfalls ist der Handler ein Callback mit der

folgenden Signatur:

</para>

<para>

<methodsynopsis>

<type>bool</type><methodname><replaceable>handler</replaceable></methodname>

<methodparam><type>int</type><parameter>errno</parameter></methodparam>

<methodparam><type>string</type><parameter>errstr</parameter></methodparam>

<methodparam choice="opt"><type>string</type><parameter>errfile</parameter></methodparam>

<methodparam choice="opt"><type>int</type><parameter>errline</parameter></methodparam>

<methodparam choice="opt"><type>array</type><parameter>errcontext</parameter></methodparam>

</methodsynopsis>

<variablelist>

<varlistentry>

<term><parameter>errno</parameter></term>

<listitem>

<simpara>

Dem erstem Parameter, <parameter>errno</parameter>, wird der

Schweregrad des ausgelösten Fehlers als Integer übergeben.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>errstr</parameter></term>

<listitem>

<simpara>

Dem zweiten Parameter, <parameter>errstr</parameter>, wird die

Fehlermeldung als String übergeben.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>errfile</parameter></term>

<listitem>

<simpara>

Wenn der Callback einen dritten Parameter akzeptiert, nämlich

<parameter>errfile</parameter>, wird der Dateiname, in dem der

Fehler aufgetreten ist, als String übergeben.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>errline</parameter></term>

<listitem>

<simpara>

Wenn der Callback einen vierten Parameter akzeptiert, nämlich

<parameter>errline</parameter>, wird die Zeilennummer, in der der

Fehler aufgetreten ist, als Integer übergeben.

</simpara>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>errcontext</parameter></term>

<listitem>

<simpara>

Wenn der Callback einen fünften Parameter akzeptiert, nämlich

<parameter>errcontext</parameter>, wird ihm ein Array übergeben,

das auf die aktive Symboltabelle zu dem Punkt zeigt, an dem der

Fehler auftrat. Mit anderen Worten:

<parameter>errcontext</parameter> enthält ein Array mit allen

Variablen, die im fehlerauslösenden Bereich existierten.

Benutzerdefinierte Fehlerbehandlungen dürfen den Fehlerkontext

nicht verändern.

</simpara>

<warning xmlns="http://docbook.org/ns/docbook">

<simpara>

Dieser Parameter ist von PHP 7.2.0 an

<emphasis>MISSBILLIGT</emphasis> und wurde in PHP 8.0.0

<emphasis>ENTFERNT</emphasis>. Wenn die Funktion diesen Parameter

ohne Vorgabe definiert, wird beim Aufruf der Funktion der Fehler

"too few arguments" (zu wenig Parameter) ausgelöst.

</simpara>

</warning>

</listitem>

</varlistentry>

</variablelist>

</para>

<para>

Falls diese Funktion &false; zurückgibt, wird mit der normalen

Fehlerbehandlung fortgesetzt.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>error_levels</parameter></term>

<listitem>

<para>

Kann wie die php.ini-Konfigurationseinstellung

<link linkend="ini.error-reporting">error_reporting</link>, die

bestimmt, welche Fehler angezeigt werden, zum Maskieren des Aufrufs der

<parameter>callback</parameter>-Funktion verwendet werden. Wird diese

Maske nicht gesetzt, wird der <parameter>callback</parameter>

unabhängig von der Einstellung

<link linkend="ini.error-reporting">error_reporting</link> bei jedem

Fehler aufgerufen.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Gibt die zuvor definierte Fehlerbehandlungsroutine (falls eine definiert

wurde) als <type>callable</type> zurück.

Wenn der eingebaute Errorhandler verwendet wurde, wird &null; zurückgegeben.

</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.0.0</entry>

<entry>

Der Parameter <parameter>errcontext</parameter> wurde entfernt und

wird nicht mehr an Benutzer-Callbacks übergeben.

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

<parameter>errcontext</parameter> wurde missbilligt. Die Verwendung

dieses Parameters erzeugt nun einen

<constant>E_DEPRECATED</constant>-Hinweis.

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Fehlerbehandlung mit <function>set_error_handler</function> und

<function>trigger_error</function></title>

<para>

Das untenstehende Beispiel zeigt die Behandlung von internen Ausnahmen,

indem Fehler ausgelöst und durch eine benutzerdefinierte Funktion

behandelt werden:

</para>

<programlisting role="php">

<![CDATA[

<?php

// Fehlerbehandlungsfunktion

function myErrorHandler($fehlercode, $fehlertext, $fehlerdatei, $fehlerzeile)

{

if (!(error_reporting() & $fehlercode)) {

// Dieser Fehlercode ist nicht in error_reporting enthalten

return false;

}

// $fehlertext muss möglicherweise maskiert werden:

$fehlertext = htmlspecialchars($fehlertext);

switch ($fehlercode) {

case E_USER_ERROR:

echo "<b>Mein FEHLER</b> [$fehlercode] $fehlertext<br />\n";

echo " Fataler Fehler in Zeile $fehlerzeile in der Datei $fehlerdatei";

echo ", PHP " . PHP_VERSION . " (" . PHP_OS . ")<br />\n";

echo "Abbruch...<br />\n";

break;

case E_USER_WARNING:

echo "<b>Meine WARNUNG</b> [$fehlercode] $fehlertext<br />\n";

break;

case E_USER_NOTICE:

echo "<b>Mein HINWEIS</b> [$fehlercode] $fehlertext<br />\n";

break;

default:

echo "Unbekannter Fehlertyp: [$fehlercode] $fehlertext<br />\n";

break;

}

/* Damit die PHP-interne Fehlerbehandlung nicht ausgeführt wird */

return true;

}

// Funktion zum Test der Fehlerbehandlung

function logarithmisch_skalieren($vektor, $skalierung)

{

if (!is_numeric($skalierung) || $skalierung <= 0) {

trigger_error("log(x) ist für x <= 0 nicht definiert, Sie verwendeten: skalierung = $skalierung", E_USER_ERROR);

}

if (!is_array($vektor)) {

trigger_error("Fehlerhafter Eingabevektor, es wird ein Wertearray erwartet", E_USER_WARNING);

return null;

}

$temp = array();

foreach($vektor as $pos => $wert) {

if (!is_numeric($wert)) {

trigger_error("Der Wert an Position $pos ist keine Zahl, verwende 0 (Null)", E_USER_NOTICE);

$wert = 0;

}

$temp[$pos] = log($skalierung) * $wert;

}

return $temp;

}

// auf die benutzerdefinierte Fehlerbehandlung umstellen

$alter_error_handler = set_error_handler("myErrorHandler");

// ein paar Fehler auslösen, zuerst wird ein gemischtes Array mit einem

// nichtnumerischen Eintrag definiert

echo "Vektor a\n";

$a = array(2, 3, "foo", 5.5, 43.3, 21.11);

print_r($a);

// ein zweites Array erzeugen

echo "----\nVektor b - ein Hinweis (b = log(PI) * a)\n";

/* Der Wert an Position $pos ist keine Zahl, verwende 0 (Null) */

$b = logarithmisch_skalieren($a, M_PI);

print_r($b);

// das gibt Ärger: statt eines Arrays wird eine Zeichenkette übergeben

echo "----\nVektor c - eine Warnung\n";

/* Fehlerhafter Eingabevektor, es wird ein Wertearray erwartet */

$c = logarithmisch_skalieren("kein Array", 2.3);

var_dump($c); // NULL

// dies ist ein kritischer Fehler: log ist für Null oder negative Werte

// nicht definiert

echo "----\nVektor d - fataler Fehler\n";

/* log(x) ist für x <= 0 nicht definiert, Sie verwendeten: skalierung = $skalierung */

$d = logarithmisch_skalieren($a, -2.5);

var_dump($d); // wird nie erreicht

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

Vektor a

Array

(

[0] => 2

[1] => 3

[2] => foo

[3] => 5.5

[4] => 43.3

[5] => 21.11

)

----

Vektor b - ein Hinweis (b = log(PI) * a)

<b>Mein HINWEIS</b> [1024] Der Wert an Position 2 ist keine Zahl, verwende 0 (Null)<br />

Array

(

[0] => 2.2894597716988

[1] => 3.4341896575482

[2] => 0

[3] => 6.2960143721717

[4] => 49.566804057279

[5] => 24.165247890281

)

----

Vektor c - eine Warnung

<b>Meine WARNUNG</b> [512] Fehlerhafter Eingabevektor, es wird ein Wertearray erwartet<br />

NULL

----

Vektor d - fataler Fehler

<b>Mein FEHLER</b> [256] log(x) ist für x <= 0 nicht definiert, Sie verwendeten: skalierung = -2.5<br />

Fataler Fehler in Zeile 35 in der Datei trigger_error.php, PHP 5.2.1 (FreeBSD)<br />

Abbruch...<br />

]]>

</screen>

</example>

</para>

</refsect1>

<refsect1 role="seealso">

&reftitle.seealso;

<para>

<simplelist>

<member><classname>ErrorException</classname></member>

<member><function>error_reporting</function></member>

<member><function>restore_error_handler</function></member>

<member><function>get_error_handler</function></member>

<member><function>trigger_error</function></member>

<member><link linkend="errorfunc.constants">Errorlevel-Konstanten</link></member>

</simplelist>

</para>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file

Local variables:

mode: sgml

sgml-omittag:t

sgml-shorttag:t

sgml-minimize-attributes:nil

sgml-always-quote-attributes:t

sgml-indent-step:1

sgml-indent-data:t

indent-tabs-mode:nil

sgml-parent-document:nil

sgml-default-dtd-file:"~/.phpdoc/manual.ced"

sgml-exposed-tags:nil

sgml-local-catalogs:nil

sgml-local-ecat-files:nil

End:

vim600: syn=xml fen fdm=syntax fdl=2 si

vim: et tw=78 syn=sgml

vi: ts=1 sw=1

-->