<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>This function returns an array of messages matching the given search criteria</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.imap-scanmailbox.html">imap_scanmailbox</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.imap-set-quota.html">imap_set_quota</a></div>
<div class="up"><a href="ref.imap.html">IMAP Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="function.imap-search" class="refentry">
<div class="refnamediv">
<h1 class="refname">imap_search</h1>
<p class="verinfo">(PHP 4, PHP 5)</p><p class="refpurpose"><span class="refname">imap_search</span> — <span class="dc-title">This function returns an array of messages matching the given search criteria</span></p>
</div>
<div class="refsect1 description" id="refsect1-function.imap-search-description">
<h3 class="title">Description</h3>
<div class="methodsynopsis dc-description">
<span class="type">array</span> <span class="methodname"><strong>imap_search</strong></span>
( <span class="methodparam"><span class="type">resource</span> <code class="parameter">$imap_stream</code></span>
, <span class="methodparam"><span class="type">string</span> <code class="parameter">$criteria</code></span>
[, <span class="methodparam"><span class="type">int</span> <code class="parameter">$options</code><span class="initializer"> = SE_FREE</span></span>
[, <span class="methodparam"><span class="type">string</span> <code class="parameter">$charset</code><span class="initializer"> = NIL</span></span>
]] )</div>
<p class="para rdfs-comment">
This function performs a search on the mailbox currently opened
in the given <acronym title="Internet Message Access Protocol">IMAP</acronym> stream.
</p>
<p class="para">
For example, to match all unanswered messages sent by Mom, you'd
use: "UNANSWERED FROM mom". Searches appear to be case
insensitive. This list of criteria is from a reading of the UW
c-client source code and may be incomplete or
inaccurate (see also <a href="http://www.faqs.org/rfcs/rfc2060" class="link external">» RFC2060</a>,
section 6.4.4).
</p>
</div>
<div class="refsect1 parameters" id="refsect1-function.imap-search-parameters">
<h3 class="title">Parameters</h3>
<p class="para">
<dl>
<dt>
<span class="term"><em><code class="parameter">
imap_stream</code></em></span><dd>
<p class="para">An IMAP stream returned by
<span class="function"><a href="function.imap-open.html" class="function">imap_open()</a></span>.</p></dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">criteria</code></em></span>
<dd>
<p class="para">
A string, delimited by spaces, in which the following keywords are
allowed. Any multi-word arguments (e.g.
<em>FROM "joey smith"</em>) must be quoted. Results will match
all <em><code class="parameter">criteria</code></em> entries.
<ul class="itemizedlist">
<li class="listitem">
<span class="simpara">
ALL - return all messages matching the rest of the criteria
</span>
</li>
<li class="listitem">
<span class="simpara">
ANSWERED - match messages with the \\ANSWERED flag set
</span>
</li>
<li class="listitem">
<span class="simpara">
BCC "string" - match messages with "string" in the Bcc: field
</span>
</li>
<li class="listitem">
<span class="simpara">
BEFORE "date" - match messages with Date: before "date"
</span>
</li>
<li class="listitem">
<span class="simpara">
BODY "string" - match messages with "string" in the body of the message
</span>
</li>
<li class="listitem">
<span class="simpara">
CC "string" - match messages with "string" in the Cc: field
</span>
</li>
<li class="listitem">
<span class="simpara">
DELETED - match deleted messages
</span>
</li>
<li class="listitem">
<span class="simpara">
FLAGGED - match messages with the \\FLAGGED (sometimes
referred to as Important or Urgent) flag set
</span>
</li>
<li class="listitem">
<span class="simpara">
FROM "string" - match messages with "string" in the From: field
</span>
</li>
<li class="listitem">
<span class="simpara">
KEYWORD "string" - match messages with "string" as a keyword
</span>
</li>
<li class="listitem">
<span class="simpara">
NEW - match new messages
</span>
</li>
<li class="listitem">
<span class="simpara">
OLD - match old messages
</span>
</li>
<li class="listitem">
<span class="simpara">
ON "date" - match messages with Date: matching "date"
</span>
</li>
<li class="listitem">
<span class="simpara">
RECENT - match messages with the \\RECENT flag set
</span>
</li>
<li class="listitem">
<span class="simpara">
SEEN - match messages that have been read (the \\SEEN flag is set)
</span>
</li>
<li class="listitem">
<span class="simpara">
SINCE "date" - match messages with Date: after "date"
</span>
</li>
<li class="listitem">
<span class="simpara">
SUBJECT "string" - match messages with "string" in the Subject:
</span>
</li>
<li class="listitem">
<span class="simpara">
TEXT "string" - match messages with text "string"
</span>
</li>
<li class="listitem">
<span class="simpara">
TO "string" - match messages with "string" in the To:
</span>
</li>
<li class="listitem">
<span class="simpara">
UNANSWERED - match messages that have not been answered
</span>
</li>
<li class="listitem">
<span class="simpara">
UNDELETED - match messages that are not deleted
</span>
</li>
<li class="listitem">
<span class="simpara">
UNFLAGGED - match messages that are not flagged
</span>
</li>
<li class="listitem">
<span class="simpara">
UNKEYWORD "string" - match messages that do not have the
keyword "string"
</span>
</li>
<li class="listitem">
<span class="simpara">
UNSEEN - match messages which have not been read yet
</span>
</li>
</ul>
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">options</code></em></span>
<dd>
<p class="para">
Valid values for <em><code class="parameter">options</code></em> are
<strong><code>SE_UID</code></strong>, which causes the returned array to
contain UIDs instead of messages sequence numbers.
</p>
</dd>
</dt>
<dt>
<span class="term"><em><code class="parameter">charset</code></em></span>
<dd>
<p class="para">
</p>
</dd>
</dt>
</dl>
</p>
</div>
<div class="refsect1 returnvalues" id="refsect1-function.imap-search-returnvalues">
<h3 class="title">Return Values</h3>
<p class="para">
Returns an array of message numbers or UIDs.
</p>
<p class="para">
Return <strong><code>FALSE</code></strong> if it does not understand the search
<em><code class="parameter">criteria</code></em> or no messages have been found.
</p>
</div>
<div class="refsect1 changelog" id="refsect1-function.imap-search-changelog">
<h3 class="title">Changelog</h3>
<p class="para">
<table class="doctable informaltable">
<thead>
<tr>
<th>Version</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td>4.3.3</td>
<td>
The <em><code class="parameter">charset</code></em> parameter was added
</td>
</tr>
</tbody>
</table>
</p>
</div>
<div class="refsect1 examples" id="refsect1-function.imap-search-examples">
<h3 class="title">Examples</h3>
<div class="example" id="imap-search.examples">
<p><strong>Example #1 <span class="function"><strong>imap_search()</strong></span> example</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$conn </span><span style="color: #007700">= </span><span style="color: #0000BB">imap_open</span><span style="color: #007700">(</span><span style="color: #DD0000">'{imap.example.com:993/imap/ssl}INBOX'</span><span style="color: #007700">, </span><span style="color: #DD0000">'foo@example.com'</span><span style="color: #007700">, </span><span style="color: #DD0000">'pass123'</span><span style="color: #007700">, </span><span style="color: #0000BB">OP_READONLY</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">$some </span><span style="color: #007700">= </span><span style="color: #0000BB">imap_search</span><span style="color: #007700">(</span><span style="color: #0000BB">$conn</span><span style="color: #007700">, </span><span style="color: #DD0000">'SUBJECT "HOWTO be Awesome" SINCE "8 August 2008"'</span><span style="color: #007700">, </span><span style="color: #0000BB">SE_UID</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$msgnos </span><span style="color: #007700">= </span><span style="color: #0000BB">imap_search</span><span style="color: #007700">(</span><span style="color: #0000BB">$conn</span><span style="color: #007700">, </span><span style="color: #DD0000">'ALL'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$uids </span><span style="color: #007700">= </span><span style="color: #0000BB">imap_search</span><span style="color: #007700">(</span><span style="color: #0000BB">$conn</span><span style="color: #007700">, </span><span style="color: #DD0000">'ALL'</span><span style="color: #007700">, </span><span style="color: #0000BB">SE_UID</span><span style="color: #007700">);<br /><br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$some</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$msgnos</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$uids</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output
something similar to:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
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
)
</pre></div>
</div>
</div>
</div>
<div class="refsect1 seealso" id="refsect1-function.imap-search-seealso">
<h3 class="title">See Also</h3>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="function"><a href="function.imap-listscan.html" class="function" rel="rdfs-seeAlso">imap_listscan()</a> - Returns the list of mailboxes that matches the given text</span></li>
</ul>
</p>
</div>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="function.imap-scanmailbox.html">imap_scanmailbox</a></div>
<div class="next" style="text-align: right; float: right;"><a href="function.imap-set-quota.html">imap_set_quota</a></div>
<div class="up"><a href="ref.imap.html">IMAP Functions</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
