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

<!-- $Revision$ -->

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

<!-- CREDITS: hirokawa,mumumu -->

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

<refnamediv>

<refname>set_error_handler</refname>

<refpurpose>ユーザー定義のエラーハンドラ関数を設定する</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>

スクリプトのエラー処理を行うユーザー関数

(<parameter>callback</parameter>)を設定します。

</para>

<para>

この関数は、実行時にカスタムのエラーハンドラを定義するために使います。

例えば、致命的なエラーの際にデータやファイルを消去する必要があるような

アプリケーションや、ある条件のもとに

(<function>trigger_error</function>を使用して)エラーを発生する必要がある

アプリケーションがこの場合にあたります。

</para>

<para>

コールバック関数が &false; を返さない限り、<parameter>error_levels</parameter>

で指定した型のエラーでは PHP 標準のエラーハンドラが完全にバイパスされることに注意してください。

<function>error_reporting</function> の設定にかかわらず、どのような場合でも

ユーザーが設定したエラーハンドラがコールされます。ただし、この場合でも

ハンドラで <function>error_reporting</function> の現在の値を読み込み、

それにあわせて適切に動作させることは可能です。

</para>

<para>

ユーザーハンドラ関数は、必要に応じて <function>exit</function> を

コールすることで、スクリプトを停止させる責任があることにも注意しましょう。

エラーハンドラ関数がリターンした場合、エラーが発生した次の行から実行が継続されます。

</para>

<para>

以下のエラータイプは、ユーザー定義の関数では扱えません。

<constant>E_ERROR</constant>, <constant>E_PARSE</constant>,

<constant>E_CORE_ERROR</constant>, <constant>E_CORE_WARNING</constant>,

<constant>E_COMPILE_ERROR</constant>,

<constant>E_COMPILE_WARNING</constant>。これらは発生した場所に関係なく使えません。

また、<function>set_error_handler</function> がコールされたファイルで発生した

大半の <constant>E_STRICT</constant> も、ユーザー定義の関数では扱えません。

</para>

<para>

(ファイルアップロードのように)スクリプトが実行される前にエラーが

発生した場合、カスタムエラーハンドラはコールされません。

これは、その時点では登録されていないためです。

</para>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

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

<listitem>

<para>

&null; を渡すと、ハンドラをデフォルトの状態に戻せます。

それ以外の場合、次のシグネチャに従うコールバックを渡します:

</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>

最初のパラメータ <parameter>errno</parameter> は、発生させる

エラーのレベルが整数で渡されます。

</simpara>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<simpara>

2 番目のパラメータ <parameter>errstr</parameter> は、

エラーメッセージが文字列で渡されます。

</simpara>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<simpara>

コールバックが第3引数 <parameter>errfile</parameter> を受け入れる場合、

エラーが発生したファイルの名前が文字列で渡されます。

</simpara>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<simpara>

コールバックが第4引数 <parameter>errline</parameter> を受け入れる場合、

エラーが発生した行番号が整数で渡されます。

</simpara>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<simpara>

コールバックが第5引数 <parameter>errcontext</parameter> を受け入れる場合、

エラーが発生した場所のアクティブシンボルテーブルが配列で渡されます。

つまり、エラーが発生したスコープ内でのすべての変数の内容を格納した

配列が <parameter>errcontext</parameter> だということです。

ユーザーエラーハンドラは、決してエラーコンテキストを書き換えては

いけません。

</simpara>

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

<simpara>

このパラメータは PHP 7.2.0 以降では <emphasis>推奨されなくなり</emphasis>、

PHP 8.0.0 で <emphasis>削除されました</emphasis>。

この引数をデフォルト値以外に設定すると、

ハンドラが呼び出された時に "too few arguments" エラーが発生します。

</simpara>

</warning>

</listitem>

</varlistentry>

</variablelist>

</para>

<para>

この関数が &false; を返した場合は、通常のエラーハンドラが処理を引き継ぎます。

</para>

</listitem>

</varlistentry>

<varlistentry>

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

<listitem>

<para>

設定パラメータ

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

で表示するエラーを制御するのと全く同様に、

<parameter>callback</parameter> の起動を制御する際に

使用可能です。

このマスクを指定しない場合、

<parameter>callback</parameter> は

<link

linkend="ini.error-reporting">error_reporting</link> の設定によらず

全てのエラーに関してコールされます。

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

前に定義されたエラーハンドラ(ある場合)を <type>callable</type>

として返します。

組み込みのエラーハンドラを使用している場合は &null; を返します。

</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>

<parameter>errcontext</parameter> 引数は削除されました。

よって、ユーザー定義のコールバックに渡されることはありません。

</entry>

</row>

<row>

<entry>7.2.0</entry>

<entry>

<parameter>errcontext</parameter> が非推奨になりました。

このパラメーターを使うと、

<constant>E_DEPRECATED</constant> レベルの警告が発生するようになりました。

</entry>

</row>

</tbody>

</tgroup>

</informaltable>

</para>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>

<function>set_error_handler</function> および

<function>trigger_error</function> によるエラー処理

</title>

<para>

以下の例では、エラーを発生させることによる内部例外の処理や

それらをユーザー定義関数で処理する方法を説明します。

</para>

<programlisting role="php">

<![CDATA[

<?php

// エラーハンドラ関数

function myErrorHandler($errno, $errstr, $errfile, $errline)

{

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

// error_reporting 設定に含まれていないエラーコードのため、

// 標準の PHP エラーハンドラに渡されます。

return false;

}

// $errstr はエスケープする必要があるかもしれません。

$errstr = htmlspecialchars($errstr);

switch ($errno) {

case E_USER_ERROR:

echo "<b>My ERROR</b> [$errno] $errstr<br />\n";

echo " Fatal error on line $errline in file $errfile";

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

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

exit(1);

case E_USER_WARNING:

echo "<b>My WARNING</b> [$errno] $errstr<br />\n";

break;

case E_USER_NOTICE:

echo "<b>My NOTICE</b> [$errno] $errstr<br />\n";

break;

default:

echo "Unknown error type: [$errno] $errstr<br />\n";

break;

}

/* PHP の内部エラーハンドラを実行しません */

return true;

}

// エラー処理のテスト用関数

function scale_by_log($vect, $scale)

{

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

trigger_error("log(x) for x <= 0 is undefined, you used: scale = $scale", E_USER_ERROR);

}

if (!is_array($vect)) {

trigger_error("Incorrect input vector, array of values expected", E_USER_WARNING);

return null;

}

$temp = array();

foreach($vect as $pos => $value) {

if (!is_numeric($value)) {

trigger_error("Value at position $pos is not a number, using 0 (zero)", E_USER_NOTICE);

$value = 0;

}

$temp[$pos] = log($scale) * $value;

}

return $temp;

}

// 定義したエラーハンドラを設定する

$old_error_handler = set_error_handler("myErrorHandler");

// エラーを発生します。まず、数値でない項目が混ざった配列を定義します。

echo "vector a\n";

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

print_r($a);

// 二番目の配列を生成します。

echo "----\nvector b - a notice (b = log(PI) * a)\n";

/* Value at position $pos is not a number, using 0 (zero) */

$b = scale_by_log($a, M_PI);

print_r($b);

// 配列の代わりに文字列を渡しており、問題を発生します。

echo "----\nvector c - a warning\n";

/* Incorrect input vector, array of values expected */

$c = scale_by_log("not array", 2.3);

var_dump($c); // NULL

// ゼロまたは負数の対数が定義されないという致命的なエラーを発生します。

echo "----\nvector d - fatal error\n";

/* log(x) for x <= 0 is undefined, you used: scale = $scale" */

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

var_dump($d); // ここには到達しません

?>

]]>

</programlisting>

&example.outputs.similar;

<screen>

<![CDATA[

vector a

Array

(

[0] => 2

[1] => 3

[2] => foo

[3] => 5.5

[4] => 43.3

[5] => 21.11

)

----

vector b - a notice (b = log(PI) * a)

<b>My NOTICE</b> [1024] Value at position 2 is not a number, using 0 (zero)<br />

Array

(

[0] => 2.2894597716988

[1] => 3.4341896575482

[2] => 0

[3] => 6.2960143721717

[4] => 49.566804057279

[5] => 24.165247890281

)

----

vector c - a warning

<b>My WARNING</b> [512] Incorrect input vector, array of values expected<br />

NULL

----

vector d - fatal error

<b>My ERROR</b> [256] log(x) for x <= 0 is undefined, you used: scale = -2.5<br />

Fatal error on line 35 in file trigger_error.php, PHP 5.2.1 (FreeBSD)<br />

Aborting...<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">エラーレベル定数</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

-->