Obtain status information for a mailbox.
| public status ( mixed $mailbox, integer $flags = Horde_Imap_Client::STATUS_ALL, array $opts = [] ) : array | ||
| $mailbox | mixed | The mailbox(es) to query. Either a Horde_Imap_Client_Mailbox object, a string (UTF-8), or an array of objects/strings (since 2.10.0). |
| $flags | integer | A bitmask of information requested from the
server. Allowed flags:
- Horde_Imap_Client::STATUS_MESSAGES
Return key: messages
Return format: (integer) The number of messages in the mailbox.
- Horde_Imap_Client::STATUS_RECENT
Return key: recent
Return format: (integer) The number of messages with the \Recent
flag set as currently reported in the mailbox
- Horde_Imap_Client::STATUS_RECENT_TOTAL
Return key: recent_total
Return format: (integer) The number of messages with the \Recent
flag set. This returns the total number of messages
that have been marked as recent in this mailbox
since the PHP process began. (since 2.12.0)
- Horde_Imap_Client::STATUS_UIDNEXT
Return key: uidnext
Return format: (integer) The next UID to be assigned in the
mailbox. Only returned if the server automatically
provides the data.
- Horde_Imap_Client::STATUS_UIDNEXT_FORCE
Return key: uidnext
Return format: (integer) The next UID to be assigned in the
mailbox. This option will always determine this
value, even if the server does not automatically
provide this data.
- Horde_Imap_Client::STATUS_UIDVALIDITY
Return key: uidvalidity
Return format: (integer) The unique identifier validity of the
mailbox.
- Horde_Imap_Client::STATUS_UNSEEN
Return key: unseen
Return format: (integer) The number of messages which do not have
the \Seen flag set.
- Horde_Imap_Client::STATUS_FIRSTUNSEEN
Return key: firstunseen
Return format: (integer) The sequence number of the first unseen
message in the mailbox.
- Horde_Imap_Client::STATUS_FLAGS
Return key: flags
Return format: (array) The list of defined flags in the mailbox
(all flags are in lowercase).
- Horde_Imap_Client::STATUS_PERMFLAGS
Return key: permflags
Return format: (array) The list of flags that a client can change
permanently (all flags are in lowercase).
- Horde_Imap_Client::STATUS_HIGHESTMODSEQ
Return key: highestmodseq
Return format: (integer) If the server supports the CONDSTORE
IMAP extension, this will be the highest
mod-sequence value of all messages in the mailbox.
Else 0 if CONDSTORE not available or the mailbox
does not support mod-sequences.
- Horde_Imap_Client::STATUS_SYNCMODSEQ
Return key: syncmodseq
Return format: (integer) If caching, and the server supports the
CONDSTORE IMAP extension, this is the cached
mod-sequence value of the mailbox when it was opened
for the first time in this access. Will be null if
not caching, CONDSTORE not available, or the mailbox
does not support mod-sequences.
- Horde_Imap_Client::STATUS_SYNCFLAGUIDS
Return key: syncflaguids
Return format: (Horde_Imap_Client_Ids) If caching, the server
supports the CONDSTORE IMAP extension, and the
mailbox contained cached data when opened for the
first time in this access, this is the list of UIDs
in which flags have changed since STATUS_SYNCMODSEQ.
- Horde_Imap_Client::STATUS_SYNCVANISHED
Return key: syncvanished
Return format: (Horde_Imap_Client_Ids) If caching, the server
supports the CONDSTORE IMAP extension, and the
mailbox contained cached data when opened for the
first time in this access, this is the list of UIDs
which have been deleted since STATUS_SYNCMODSEQ.
- Horde_Imap_Client::STATUS_UIDNOTSTICKY
Return key: uidnotsticky
Return format: (boolean) If the server supports the UIDPLUS IMAP
extension, and the queried mailbox does not support
persistent UIDs, this value will be true. In all
other cases, this value will be false.
- Horde_Imap_Client::STATUS_FORCE_REFRESH
Normally, the status information will be cached for a given
mailbox. Since most PHP requests are generally less than a second,
this is fine. However, if your script is long running, the status
information may not be up-to-date. Specifying this flag will ensure
that the server is always polled for the current mailbox status
before results are returned. (since 2.14.0)
- Horde_Imap_Client::STATUS_ALL (DEFAULT)
Shortcut to return 'messages', 'recent', 'uidnext', 'uidvalidity',
and 'unseen' values.
|
| $opts | array | Additional options:
- sort: (boolean) If true, sort the list of mailboxes? (since 2.10.0)
DEFAULT: Do not sort the list.
- sort_delimiter: (string) If 'sort' is true, this is the delimiter
used to sort the mailboxes. (since 2.10.0)
DEFAULT: '.'
|
| return | array | If $mailbox contains multiple mailboxes, an array with keys being the UTF-8 mailbox name and values as arrays containing the requested keys (see above). Otherwise, an array with keys as the requested keys (see above) and values as the key data. |
/**
* Returns a unique identifier for the current mailbox status.
*
* @param Horde_Imap_Client_Base $base_ob The base driver object.
* @param mixed $mailbox A mailbox. Either a
* Horde_Imap_Client_Mailbox
* object or a string (UTF-8).
* @param boolean $condstore Is CONDSTORE enabled?
* @param array $addl Additional cache info to add to
* the cache ID string.
*
* @return string The cache ID string, which will change when the
* composition of the mailbox changes. The uidvalidity
* will always be the first element, and will be delimited
* by the '|' character.
*
* @throws Horde_Imap_Client_Exception
*/
public static function getCacheId($base_ob, $mailbox, $condstore, array $addl = array())
{
$query = Horde_Imap_Client::STATUS_UIDVALIDITY | Horde_Imap_Client::STATUS_MESSAGES | Horde_Imap_Client::STATUS_UIDNEXT;
/* Use MODSEQ as cache ID if CONDSTORE extension is available. */
if ($condstore) {
$query |= Horde_Imap_Client::STATUS_HIGHESTMODSEQ;
} else {
$query |= Horde_Imap_Client::STATUS_UIDNEXT_FORCE;
}
$status = $base_ob->status($mailbox, $query);
if (empty($status['highestmodseq'])) {
$parts = array('V' . $status['uidvalidity'], 'U' . $status['uidnext'], 'M' . $status['messages']);
} else {
$parts = array('V' . $status['uidvalidity'], 'H' . $status['highestmodseq']);
}
return implode('|', array_merge($parts, $addl));
}
/**
* Constructor.
*
* @param Horde_Imap_Client_Base $base_ob Base driver object.
* @param mixed $mailbox Mailbox to sync.
* @param array $sync Token sync data.
* @param array $curr Current sync data.
* @param integer $criteria Mask of criteria to return.
* @param Horde_Imap_Client_Ids $ids List of known UIDs.
*
* @throws Horde_Imap_Client_Exception
* @throws Horde_Imap_Client_Exception_Sync
*/
public function __construct(Horde_Imap_Client_Base $base_ob, $mailbox, $sync, $curr, $criteria, $ids)
{
foreach (self::$map as $key => $val) {
if (isset($sync[$key])) {
$this->{$val} = $sync[$key];
}
}
/* Check uidvalidity. */
if (!$this->uidvalidity || $curr['V'] != $this->uidvalidity) {
throw new Horde_Imap_Client_Exception_Sync('UIDs in cached mailbox have changed.', Horde_Imap_Client_Exception_Sync::UIDVALIDITY_CHANGED);
}
$this->mailbox = $mailbox;
/* This was a UIDVALIDITY check only. */
if (!$criteria) {
return;
}
$sync_all = $criteria & Horde_Imap_Client::SYNC_ALL;
/* New messages. */
if ($sync_all || $criteria & Horde_Imap_Client::SYNC_NEWMSGS || $criteria & Horde_Imap_Client::SYNC_NEWMSGSUIDS) {
$this->newmsgs = empty($this->uidnext) ? !empty($curr['U']) : !empty($curr['U']) && $curr['U'] > $this->uidnext;
if ($this->newmsgs && ($sync_all || $criteria & Horde_Imap_Client::SYNC_NEWMSGSUIDS)) {
$new_ids = empty($this->uidnext) ? Horde_Imap_Client_Ids::ALL : $this->uidnext . ':' . $curr['U'];
$squery = new Horde_Imap_Client_Search_Query();
$squery->ids(new Horde_Imap_Client_Ids($new_ids));
$sres = $base_ob->search($mailbox, $squery);
$this->_newmsgsuids = $sres['match'];
}
}
/* Do single status call to get all necessary data. */
if ($this->highestmodseq && ($sync_all || $criteria & Horde_Imap_Client::SYNC_FLAGS || $criteria & Horde_Imap_Client::SYNC_FLAGSUIDS || $criteria & Horde_Imap_Client::SYNC_VANISHED || $criteria & Horde_Imap_Client::SYNC_VANISHEDUIDS)) {
$status_sync = $base_ob->status($mailbox, Horde_Imap_Client::STATUS_SYNCMODSEQ | Horde_Imap_Client::STATUS_SYNCFLAGUIDS | Horde_Imap_Client::STATUS_SYNCVANISHED);
if (!is_null($ids)) {
$ids = $base_ob->resolveIds($mailbox, $ids);
}
}
/* Flag changes. */
if ($sync_all || $criteria & Horde_Imap_Client::SYNC_FLAGS) {
$this->flags = $this->highestmodseq ? $this->highestmodseq != $curr['H'] : true;
}
if ($sync_all || $criteria & Horde_Imap_Client::SYNC_FLAGSUIDS) {
if ($this->highestmodseq) {
if ($this->highestmodseq == $status_sync['syncmodseq']) {
$this->_flagsuids = is_null($ids) ? $status_sync['syncflaguids'] : $base_ob->getIdsOb(array_intersect($ids->ids, $status_sync['syncflaguids']->ids));
} else {
$squery = new Horde_Imap_Client_Search_Query();
$squery->modseq($this->highestmodseq + 1);
$sres = $base_ob->search($mailbox, $squery, array('ids' => $ids));
$this->_flagsuids = $sres['match'];
}
} else {
/* Without MODSEQ, need to mark all FLAGS as changed. */
$this->_flagsuids = $base_ob->resolveIds($mailbox, is_null($ids) ? $base_ob->getIdsOb(Horde_Imap_Client_Ids::ALL) : $ids);
}
}
/* Vanished messages. */
if ($sync_all || $criteria & Horde_Imap_Client::SYNC_VANISHED || $criteria & Horde_Imap_Client::SYNC_VANISHEDUIDS) {
if ($this->highestmodseq && $this->highestmodseq == $status_sync['syncmodseq']) {
$vanished = is_null($ids) ? $status_sync['syncvanished'] : $base_ob->getIdsOb(array_intersect($ids->ids, $status_sync['syncvanished']->ids));
} else {
$vanished = $base_ob->vanished($mailbox, $this->highestmodseq ? $this->highestmodseq : 1, array('ids' => $ids));
}
$this->vanished = (bool) count($vanished);
$this->_vanisheduids = $vanished;
}
}
