(PHP 4, PHP 5, PHP 7, PHP 8)
imap_search — 此函式會傳回符合指定搜尋條件的郵件陣列
此函式會在指定 IMAP 資料流中目前開啟的信箱上執行搜尋。
例如，要匹配所有媽媽寄來的未回覆郵件，您可以使用：「UNANSWERED FROM mom」。搜尋似乎不區分大小寫。此條件清單是根據 UW c-client 原始碼整理而得，可能不完整或不準確（另請參閱 » RFC1176，「tag SEARCH search_criteria」章節）。
imap一個 IMAP\Connection 實例。
criteria一個以空格分隔的字串，允許使用以下關鍵字。任何多字參數（例如 FROM "joey smith"）都必須用引號括起來。結果將匹配所有 criteria 項目。
flagsflags 的有效值為 SE_UID，它會使返回的陣列包含 UID 而不是郵件序號。
charset搜尋字串時使用的 MIME 字元集。
| 版本 | 說明 |
|---|---|
| 8.1.0 | imap 參數現在需要一個 IMAP\Connection 實例；先前需要一個有效的 imap 資源。 |
範例 #1 imap_search() 範例
<?php
$imap = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'foo@example.com', 'pass123', OP_READONLY);
$some = imap_search($imap, 'SUBJECT "HOWTO be Awesome" SINCE "8 August 2008"', SE_UID);
$msgnos = imap_search($imap, 'ALL');
$uids = imap_search($imap, 'ALL', SE_UID);
print_r($some);
print_r($msgnos);
print_r($uids);
?>以上範例將輸出類似以下的內容：
Array
(
[0] => 4
[1] => 6
[2] => 11
)
Array
(
[0] => 1
[1] => 2
[2] => 3
[3] => 4
[4] => 5
[5] => 6
)
Array
(
[0] => 1
[1] => 4
[2] => 6
[3] => 8
[4] => 11
[5] => 12
)
根據 rfc3501，例如 SINCE 的日期格式為：
date = date-text / DQUOTE date-text DQUOTE
date-day = 1*2DIGIT
; 月份中的日期
date-day-fixed = (SP DIGIT) / 2DIGIT
; 固定格式版本的 date-day
date-month = "Jan" / "Feb" / "Mar" / "Apr" / "May" / "Jun" /
"Jul" / "Aug" / "Sep" / "Oct" / "Nov" / "Dec"
date-text = date-day "-" date-month "-" date-year
因此，有效的日期例如 "22-Jul-2012"，可以加上或不加上雙引號。據指出，imap_search 會在使用 imap4 語法時中斷。要執行 imap 4 搜尋，請使用 curl 並發送自訂指令，然後擷取結果。最好執行 UID 搜尋以取得稍後要使用的唯一 ID。以下是一個包含有效 curl 函式的範例。
<?php
$host = 'your-server.tld';
$user = 'username';
$pass = 'password';
$folder = 'INBOX';
function send_imap_command($server, $user, $pass, $command, $folder="INBOX")
{ //Send an imap command directly to the imap server
$result=["response"=>"", "error"=>""];
$url = "imaps://$server/". rawurlencode($folder);
$options=[CURLOPT_URL=>$url, CURLOPT_PORT=> 993, CURLOPT_USERNAME=> $user,
CURLOPT_PASSWORD=> $pass, CURLOPT_RETURNTRANSFER=> true, CURLOPT_HEADER=> true,
CURLOPT_CUSTOMREQUEST=> $command];
$ch = curl_init();
curl_setopt_array($ch, $options);
$result["response"] = curl_exec($ch);
if(curl_errno($ch)) $response["error"]="Error (". curl_errno($ch) ."): ". curl_error($ch);
return $result;
}
//Pull out all the emails returned as undeliverable by the remote mail server in the inbox using curl
$response=send_imap_command($host, $user, $pass,
'UID SEARCH SINCE "01-Jan-2022" (OR FROM "mailer-daemon" FROM "postmaster") (OR SUBJECT "fail" (OR SUBJECT "undeliver" SUBJECT "returned"))',
$folder);
if($response["error"]!="")
{
echo $response["error"]."\n";
} elseif (strlen($response["response"])>5){
//Server returns a string in the form * SEARCH uid1 uid2 uid3 ... Clean up and create array of UIDs.
$response["response"]=str_replace("* SEARCH ","",$response["response"]);
$messages=explode(" ",$response["response"]);
}
print_r($messages);
?>您好，
請注意，如果找不到任何項目，imap_search() 並不會（如您所預期）傳回空陣列！
如手冊所述，它會傳回 FALSE。
不要像我一樣用 "count($array)" 這種方式測試結果。
即使結果為空，這樣做也會回傳 1。 我花了一個小時才找到原因 :-( 請閱讀該死的說明文件 (RTFM)imap_search 函式與 IMAP4 並不完全相容。 目前使用的 c-client 只支援 IMAP2，有些搜尋條件例如 "OR" 無法使用。
所以像這樣的 PHP 程式碼：
$inbox = imap_open('{imap.example.com:993/imap/ssl}INBOX', 'foo@example.com', 'pass123', OP_READONLY);
$search_string = 'SUBJECT "FedEx" OR SUBJECT "USPS"';
$emails = imap_search($inbox, $search_string);
會拋出 "Unknown search criterion（未知的搜尋條件）" 錯誤。
觀察與參考
PHP 原始碼追蹤：（參考：https://github.com/php/php-src/blob/master/ext/imap/php_imap.c）
/ext/imap/php_imap.c -> 行號：4126
imap_search => 行號：4148
c-client 函式庫原始碼追蹤
src/c-client/mail.c -> 行號：3973
internal.txt -> 行號：1919 => mail_criteria()
criteria IMAP2 格式的搜尋條件字串
警告：此函式不接受 IMAP4 搜尋條件。
IMAP2 RFC1064 => [參考：https://tools.ietf.org/html/rfc1064] [頁數：13]
IMAP4 RFC2060 => [參考：http://www.faqs.org/rfcs/rfc2060.html] [章節：6.4.4]
備註
PHP 中的核心模組 (IMAP) 仍然不提供核心搜尋功能。希望這能引起開發者社群的關注……設定您自己的字元集，這在處理中文、日文和韓文查詢時很有用。
<?php imap_search($inbox,'BODY "'.$keyword.'"', SE_FREE, "UTF-8"); ?>請注意訊息的 UID。
它並非永不變更的 ID！
如果您將訊息移至 IMAP 帳戶中的另一個資料夾，則此 UID 將會變更。
因此，如果您的訊息在「收件匣」資料夾中的 UID 為 100，而您將其移至某個子資料夾，然後再移回「收件匣」，則它在「收件匣」中的新 UID 將會是 101。這是使用帶有 ON "date" 的 imap_search 的正確方法
$date = date("j F Y");
$emails = imap_search($inbox,'ON "'.$date.'"' );當連線參數中設定了 op_silent 旗標時，imap_search() 永遠會回傳 false。