(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)
trigger_error — 產生使用者層級的錯誤/警告/通知訊息
用於觸發使用者錯誤狀況，它可以與內建的錯誤處理器一起使用，或者與已設定為新錯誤處理器的使用者自訂函式 (set_error_handler()) 一起使用。
當您需要在執行期間針對例外產生特定回應時，此函式非常有用。
message此錯誤的指定錯誤訊息。其長度限制為 1024 個位元組。超過 1024 個位元組的任何額外字元將會被截斷。
error_level此錯誤的指定錯誤類型。它僅適用於 E_USER_* 系列常數，預設值為 E_USER_NOTICE。
傳遞 E_USER_ERROR 作為 error_level 現已棄用。請改為拋出 Exception 或呼叫 exit()。
永遠返回 true。
如果 error_level 不是 E_USER_ERROR、E_USER_WARNING、E_USER_NOTICE 或 E_USER_DEPRECATED 其中之一，則此函式會拋出 ValueError。
| 版本 | 說明 |
|---|---|
| 8.4.0 | 傳遞 E_USER_ERROR 作為 error_level 現已棄用。請改為拋出 Exception 或呼叫 exit()。 |
| 8.4.0 | 此函式的返回類型現在是 true，而不是 bool。 |
| 8.0.0 | 如果指定了無效的 error_level，此函式現在會拋出 ValueError。以前，它會返回 false。 |
範例 #1 trigger_error() 範例
更廣泛的範例，請參見 set_error_handler()。
<?php
$password = $_POST['password'] ?? '';
if ($password === '') {
trigger_error("使用空密碼並不安全", E_USER_WARNING);
}
$hash = password_hash($password, PASSWORD_DEFAULT);
?>message 中的 HTML 實體不會被跳脫。如果錯誤要顯示在瀏覽器中，請對訊息使用 htmlentities()。
重點是永遠不要向使用者顯示檔案名稱、行號和難以理解的程式碼。在使用 set_error_handler() 註冊您自己的回呼函式（用於記錄或透過電子郵件將錯誤程式碼發送給您）之後，使用 trigger_error()，並向使用者顯示簡潔易懂的訊息。
並在需要除錯指令碼時開啟更詳細的錯誤處理函式。在我的 init.php 指令碼中，我總是這樣做：
if (_DEBUG_) {
set_error_handler ('debug_error_handler');
}
} else {
set_error_handler ('nice_error_handler');
}注意，trigger_error() 對於在 $php_errormsg 中傳輸您自訂函式的錯誤訊息完全無用。
ini_set('track_errors', TRUE);
function x() { trigger_error('MY ERROR'); }
@x();
echo "錯誤 1: \\"$php_errormsg\\"\\n";
@file_get_contents('/nonexisting');
echo "錯誤 2: \\"$php_errormsg\\"\\n";
這會輸出
錯誤 1: ""
錯誤 2: "failed to open stream: No such file or directory"
此行為與 $php_errormsg 的描述一致，該描述說明該變數僅在發生錯誤的範圍內可用。可以使用如下所示的自訂錯誤處理程式來解決此問題。然而，我不確定以這種方式更改語言是否合適。
function errHandler($errno, $errstr, $errfile, $errline) {
global $php_errormsg; $php_errormsg = $errstr;
}
}
trigger_error 總是回報呼叫 trigger_error 的行和檔案。這並不是很有用。
例如：
main.php
<?php
include('functions.php');
$x = 'test';
doFunction($x);
?>
functions.php
<?php
function doFunction($var) {
if(is_numeric($var)) {
/* 做一些事情*/
} else {
trigger_error('var 必須是數字');
}
}
?>
將會輸出「注意：functions.php 中第 6 行的 var 必須是數字」
而「注意：main.php 中第 4 行的 var 必須是數字」會更有用
這裡有一個可以做到這一點的函式
<?php
函式 error($message, $level=E_USER_NOTICE) {
$caller = next(debug_backtrace());
trigger_error($message.' 位於 <strong>'.$caller['function'].'</strong>，從 <strong>'.$caller['file'].'</strong> 的第 <strong>'.$caller['line'].'</strong> 行呼叫'."\n<br />錯誤處理器", $level);
}
?>
現在在我們的範例中
main.php
<?php
include('functions.php');
$x = 'test';
doFunction($x);
?>
functions.php
<?php
函式 doFunction($var) {
if(is_numeric($var)) {
/* 做一些事情*/
} else {
error('變數必須是數字');
}
}
函式 error($message, $level=E_USER_NOTICE) {
$caller = next(debug_backtrace());
trigger_error($message.' 位於 <strong>'.$caller['function'].'</strong>，從 <strong>'.$caller['file'].'</strong> 的第 <strong>'.$caller['line'].'</strong> 行呼叫'."\n<br />錯誤處理器", $level);
}
?>
現在輸出
"注意：變數必須是數字，位於 doFunction，從 main.php 的第 4 行呼叫"對於那些希望在錯誤訊息中使用自己的檔案或行號（可能使用 debug_backtrace()）而不是 trigger_error() 建立的檔案或行號的人，這裡提供一個解決方案
建立一個自訂函式來處理 E_USER_ERROR，它只輸出錯誤類型和訊息，但不包含 trigger_error() 回報的行號和檔案。如有必要，您也可以設定它來處理使用者警告和注意事項（我在下面的範例中這樣做了）。
<?php
函式 error_handler($level, $message, $file, $line, $context) {
//自行處理使用者錯誤、警告和注意事項
if($level === E_USER_ERROR || $level === E_USER_WARNING || $level === E_USER_NOTICE) {
echo '<strong>錯誤：</strong> '.$message;
return(true); //並阻止 PHP 錯誤處理器繼續執行
}
return(false); //否則，使用 PHP 的錯誤處理器
}
函式 trigger_my_error($message, $level) {
//取得呼叫函式的呼叫者及其詳細資訊
$callee = next(debug_backtrace());
//觸發相應的錯誤
trigger_error($message.' 位於 <strong>'.$callee['file'].'</strong> 的第 <strong>'.$callee['line'].'</strong> 行', $level);
}
//使用我們的自訂處理器
set_error_handler('error_handler');
//-------------------------------
//示範用法：
//-------------------------------
函式 abc($str) {
if(!is_string($str)) {
trigger_my_error('abc() 預期參數 1 為字串', E_USER_ERROR);
}
}
abc('Hello world!'); //正常運作
abc(18); //錯誤：abc() 預期參數 1 為字串，位於 [FILE].php 的第 31 行
?>
這是一個相當簡單的概念，我相信你們大多數人都知道，但對於那些不知道的人來說，這是一個很好的例子！如果 error_type 是 E_USER_ERROR，那麼 trigger_error 會拋出致命錯誤，腳本將在此行之後停止。
<?php
$msg = '這是 echo 的測試訊息';
trigger_error('錯誤訊息', E_USER_ERROR); // 腳本在此行之後停止...
echo $msg; // 此行不會出現...
?>如果 $error_level 大於或等於 E_USER_ERROR，函式 trigger_error 將會終止腳本。
如果您編寫自己的錯誤處理器，您將必須自行處理這些問題。
範例中，我們假設全域 LOG 常數指向一個 PSR-2 紀錄介面。
<?php
set_error_handler( function ($errno, $errstr, $errfile, $errline) {
// 使用 @ 運算子抑制錯誤
if ( 0 === error_reporting() ) {
return false;
}
switch ($errno) {
default:
LOG->error( "未知的錯誤類型： [$errno] $errstr", [ 'file' => $errfile, '@' => $errline ] );
exit(1);
case E_USER_ERROR: // fall through
case E_WARNING: // 將 PHP 警告視為錯誤
LOG->error( $errstr, [ 'file' => $errfile, '@' => $errline ] );
exit(1);
case E_USER_DEPRECATED:
case E_DEPRECATED:
LOG->error( "已棄用 $errstr", [ 'file' => $errfile, '@' => $errline ] );
break;
case E_USER_WARNING: // fall through
case E_NOTICE: // 將 PHP 通知視為警告
LOG->warning( $errstr, [ 'file' => $errfile, '@' => $errline ] );
break;
case E_USER_NOTICE:
LOG->notice( $errstr, [ 'file' => $errfile, '@' => $errline ] );
break;
case E_ERROR: // fall through
case E_RECOVERABLE_ERROR:
LOG->critical( $errstr, [ 'file' => $errfile, '@' => $errline ] );
exit(1);
}
/* 不要執行 PHP 內部錯誤處理器 */
return true;
} );
?>