Documentation

IMP_Mailbox
in package

This object is a clearinghouse for actions related to an IMP mailbox.

Tags
author

Michael Slusarz slusarz@horde.org

category

Horde

copyright

2011-2017 Horde LLC

license

http://www.horde.org/licenses/gpl GPL

Table of Contents

Constants

MBOX_DRAFTS  = 'drafts_folder'
MBOX_SENT  = 'sent_mail_folder'
MBOX_SPAM  = 'spam_folder'
MBOX_TEMPLATES  = 'composetemplates_mbox'
MBOX_TRASH  = 'trash_folder'
MBOX_USERSPECIAL  = 'user_special'
SPECIAL_COMPOSETEMPLATES  = 'composetemplates'
SPECIAL_DRAFTS  = 'drafts'
SPECIAL_SENT  = 'sent'
SPECIAL_SPAM  = 'spam'
SPECIAL_TRASH  = 'trash'
SPECIAL_USER  = 'userspecial'

Properties

$abbrev_label  : string
$access_creatembox  : bool
$access_deletembox  : bool
$access_deletembox_acl  : bool
$access_deletemsgs  : bool
$access_empty  : bool
$access_expunge  : bool
$access_filters  : bool
$access_flags  : bool
$access_search  : bool
$access_sort  : bool
$access_sortthread  : bool
$acl  : mixed
$basename  : string
$cacheid  : string
$cacheid_date  : string
$children  : bool
$container  : bool
$display  : string
$display_html  : string
$drafts  : bool
$editquery  : bool
$editvfolder  : bool
$exists  : bool
$form_to  : string
$icon  : object
$imap_mbox  : string
$imap_mbox_ob  : Horde_Imap_Client_Mailbox
$imp_imap  : IMP_Imap
$inbox  : bool
$innocent_show  : bool
$is_imap  : bool
$is_open  : bool
$label  : string
$level  : int
$list_ob  : IMP_Mailbox_List
$namespace  : string
$namespace_append  : IMP_Mailbox
$namespace_delimiter  : string
$namespace_info  : Horde_Imap_Client_Data_Namespace
$nonimap  : bool
$parent  : IMP_Mailbox
$parent_imap  : string
$permflags  : IMP_Imap_PermanentFlags
$poll_info  : object
$polled  : bool
$pref_from  : string
$pref_to  : string
$query  : bool
$readonly  : bool
$remote  : bool
$remote_account  : IMP_Remote_Account
$remote_container  : bool
$remote_mbox  : bool
$search  : bool
$size  : string
$sortob  : IMP_Prefs_Sort
$spam  : bool
$spam_show  : bool
$special  : bool
$special_outgoing  : bool
$specialvfolder  : bool
$sub  : bool
$subfolders  : array<string|int, mixed>
$subfolders_only  : array<string|int, mixed>
$systemquery  : bool
$templates  : bool
$trash  : bool
$tree_elt  : IMP_Ftree_Element
$uidvalid  : string
$value  : string
$vfolder  : bool
$vfolder_container  : bool
$vinbox  : bool
$vtrash  : bool
$_mbox  : string
The IMAP mailbox name (UTF-8).

Methods

__construct()  : mixed
Constructor.
__get()  : mixed
__set()  : mixed
__toString()  : mixed
create()  : bool
Create this mailbox on the server.
createMailboxName()  : IMP_Mailbox
Return the mailbox name to create given a submailbox name.
delete()  : bool
Deletes mailbox.
emptyMailbox()  : mixed
Empties the entire mailbox.
equals()  : bool
Determines if this mailbox is equal to the given mailbox.
expunge()  : IMP_Indices
Expunges all deleted messages.
filter()  : mixed
Runs filters on this mailbox.
filterOnDisplay()  : bool
Filters this mailbox if it is the INBOX and the filter on display pref is active.
flagAll()  : bool
Adds or removes flag(s) for all messages in the mailbox.
formFrom()  : mixed
Converts a mailbox string from a form representation.
formTo()  : mixed
Converts a mailbox string to a form representation.
fromBuids()  : IMP_Indices
Create an indices object from a list of browser-UIDs.
get()  : mixed
Shortcut to obtaining mailbox object(s).
getImapMboxOb()  : mixed
Shortcut to obtaining Horde_Imap_Client_Mailbox object(s).
getIndicesOb()  : IMP_Indices
Return an indices object for this mailbox.
getPref()  : IMP_Mailbox
Shortcut to obtaining a mailbox object from a preference name.
getSearchOb()  : IMP_Search_Query
Return the search query object for this mailbox.
getSort()  : IMP_Prefs_Sort_Sortpref
Return the sorting preference for this mailbox.
getSpecialMailboxes()  : array<string|int, mixed>
Return the list of special mailboxes.
getSpecialMailboxesSort()  : array<string|int, mixed>
Return the list of sorted special mailboxes.
hideDeletedMsgs()  : bool
Are deleted messages hidden in this mailbox?
prefFrom()  : string
Converts a mailbox name from a value stored in the preferences.
prefTo()  : string
Converts a mailbox name to a value to be stored in a preference.
rename()  : bool
Rename this mailbox on the server. The subscription status remains the same. All subfolders will also be renamed.
runSearchQuery()  : IMP_Indices
Run a search query on this mailbox that is not stored in the current session. Allows custom queries with custom sorts to be used without affecting cached mailboxes.
setHideDeletedMsgs()  : mixed
Sets the 'delhide' preference and clears necessary cached data.
setSort()  : mixed
Set the sorting preference for this mailbox.
subscribe()  : bool
Subscribe/unsubscribe to an IMAP mailbox.
toBuids()  : IMP_Indices
Create a BUID indices object from a list of UIDs.
url()  : Horde_Url
Generate a URL using the current mailbox.
urlParams()  : array<string|int, mixed>
Returns list of URL parameters necessary to indicate current mailbox status.
_getCacheID()  : string
Returns a unique identifier for this mailbox's status.
_getDisplay()  : string
If there is information available to tell us about a prefix in front of mailbox names that shouldn't be displayed to the user, then use it to strip that prefix out. Additionally, translate prefix text if this is a special mailbox.
_getIcon()  : object
Return icon information.
_onDelete()  : mixed
Do the necessary cleanup/cache updates when deleting mailboxes.

Constants

MBOX_DRAFTS

public mixed MBOX_DRAFTS = 'drafts_folder'

MBOX_SENT

public mixed MBOX_SENT = 'sent_mail_folder'

MBOX_SPAM

public mixed MBOX_SPAM = 'spam_folder'

MBOX_TEMPLATES

public mixed MBOX_TEMPLATES = 'composetemplates_mbox'

MBOX_TRASH

public mixed MBOX_TRASH = 'trash_folder'

MBOX_USERSPECIAL

public mixed MBOX_USERSPECIAL = 'user_special'

SPECIAL_COMPOSETEMPLATES

public mixed SPECIAL_COMPOSETEMPLATES = 'composetemplates'

SPECIAL_DRAFTS

public mixed SPECIAL_DRAFTS = 'drafts'

SPECIAL_SENT

public mixed SPECIAL_SENT = 'sent'

SPECIAL_SPAM

public mixed SPECIAL_SPAM = 'spam'

SPECIAL_TRASH

public mixed SPECIAL_TRASH = 'trash'

SPECIAL_USER

public mixed SPECIAL_USER = 'userspecial'

Properties

$abbrev_label read-only

public string $abbrev_label

Abbreviated version of $label - displays only the bare mailbox name (no parents).

$access_creatembox read-only

public bool $access_creatembox

Can sub mailboxes be created?

$access_deletembox read-only

public bool $access_deletembox

Can this mailbox be deleted?

$access_deletembox_acl read-only

public bool $access_deletembox_acl

Can this mailbox be deleted according to ACL rules?

$access_deletemsgs read-only

public bool $access_deletemsgs

Can messages be deleted in this mailbox?

$access_empty read-only

public bool $access_empty

Can this mailbox be emptied?

$access_expunge read-only

public bool $access_expunge

Can messages be expunged in this mailbox?

$access_filters read-only

public bool $access_filters

Is filtering available?

$access_flags read-only

public bool $access_flags

Are flags available?

public bool $access_search

Is searching available?

$access_sort read-only

public bool $access_sort

Is sorting available?

$access_sortthread read-only

public bool $access_sortthread

Is thread sort available?

$acl read-only

public mixed $acl

Either an ACL object for the mailbox, or null if no ACL found for the mailbox.

$basename read-only

public string $basename

The basename of the mailbox (UTF-8).

$cacheid read-only

public string $cacheid

Cache ID for the mailbox.

$cacheid_date read-only

public string $cacheid_date

Cache ID for the mailbox, with added data information.

$children read-only

public bool $children

Does the element have children?

$container read-only

public bool $container

Is this a container element?

$display

public string $display

Display version of mailbox. Special mailboxes are replaced with localized strings and namespace information is removed.

$display_html read-only

public string $display_html

$display that has been HTML encoded.

$drafts read-only

public bool $drafts

Is this a Drafts mailbox?

$editquery read-only

public bool $editquery

Can this search query be edited?

$editvfolder read-only

public bool $editvfolder

Can this virtual folder be edited?

$exists read-only

public bool $exists

Does this mailbox exist on the IMAP server?

$form_to read-only

public string $form_to

Converts this mailbox to a form representation.

$icon read-only

public object $icon

Icon information for the mailbox. Properties:

  • alt: (string) The alt text for the icon.
  • class: (string) The CSS class name.
  • icon: (Horde_Themes_Image) The icon graphic to use.
  • iconopen: (Horde_Themes_Image) The openicon to use.
  • user_icon: (boolean) Use a user defined icon?

$imap_mbox read-only

public string $imap_mbox

The actual name of the underlying IMAP mailbox.

$imap_mbox_ob read-only

public Horde_Imap_Client_Mailbox $imap_mbox_ob

Convert this object tp an Imap_Client mailbox object.

$imp_imap read-only

public IMP_Imap $imp_imap

The IMP_Imap object for this mailbox.

$inbox read-only

public bool $inbox

Is this the INBOX?

$innocent_show read-only

public bool $innocent_show

Show the innocent action in this mailbox?

$is_imap read-only

public bool $is_imap

Is this an IMAP mailbox?

$is_open read-only

public bool $is_open

Is this level expanded?

$label read-only

public string $label

The mailbox label. Essentially is $display that can be modified by user hook.

$level read-only

public int $level

The child level of this element.

$namespace read-only

public string $namespace

Is this a namespace element?

$namespace_append read-only

public IMP_Mailbox $namespace_append

The mailbox with necessary namespace information appended.

$namespace_delimiter read-only

public string $namespace_delimiter

The delimiter for this namespace.

$namespace_info read-only

public Horde_Imap_Client_Data_Namespace $namespace_info

Namespace info.

$nonimap read-only

public bool $nonimap

Is this a non-IMAP element?

$parent read-only

public IMP_Mailbox $parent

The parent element. Returns null if no parent. (Base of tree is returned as a special element).

$parent_imap read-only

public string $parent_imap

The IMAP parent name.

$poll_info read-only

public object $poll_info

Poll information for the mailbox. Properties:

  • msgs: (integer) The number of total messages in the element, if polled.
  • recent: (integer) The number of new messages in the element, if polled.
  • unseen: (integer) The number of unseen messages in the element, if polled.

$polled read-only

public bool $polled

Show polled information?

$pref_from read-only

public string $pref_from

Convert mailbox name from preference storage.

$pref_to read-only

public string $pref_to

Convert mailbox name to preference storage.

$query read-only

public bool $query

Is this a search query?

$readonly read-only

public bool $readonly

Is this mailbox read-only?

$remote read-only

public bool $remote

Is this a remote element?

$remote_account read-only

public IMP_Remote_Account $remote_account

Return the account object for this element (null if not a remote element).

$remote_container read-only

public bool $remote_container

Is this mailbox a remote special element?

$remote_mbox read-only

public bool $remote_mbox

Is this mailbox on a remote server?

public bool $search

Is this a search mailbox?

$size read-only

public string $size

Human readable size of the mailbox.

$spam read-only

public bool $spam

Is this a Spam mailbox?

$spam_show read-only

public bool $spam_show

Show the spam action in this mailbox?

$special read-only

public bool $special

Is this is a "special" element?

$special_outgoing read-only

public bool $special_outgoing

Is this a "special" element dealing with outgoing messages?

$specialvfolder read-only

public bool $specialvfolder

Is this a "special" virtual folder?

$sub read-only

public bool $sub

Is this mailbox subscribed to?

$subfolders read-only

public array<string|int, mixed> $subfolders

Returns the list of subfolders as mailbox objects (including the current mailbox).

$subfolders_only read-only

public array<string|int, mixed> $subfolders_only

Returns the list of subfolders as mailbox objects (NOT including the current mailbox).

$systemquery read-only

public bool $systemquery

Is this a system (built-in) search query?

$templates read-only

public bool $templates

Is this a Templates mailbox?

$trash read-only

public bool $trash

Is this a Trash mailbox?

$uidvalid read-only

public string $uidvalid

Returns the UIDVALIDITY string. Throws an IMP_Exception on error.

$value read-only

public string $value

The value of this element (IMAP mailbox name; UTF-8).

$vfolder read-only

public bool $vfolder

Is this a virtual folder?

$vfolder_container read-only

public bool $vfolder_container

Is this the virtual folder container?

$vinbox read-only

public bool $vinbox

Is this the virtual inbox?

$vtrash read-only

public bool $vtrash

Is this the virtual trash?

$_mbox

The IMAP mailbox name (UTF-8).

protected string $_mbox

Methods

__construct()

Constructor.

public __construct(mixed $mbox) : mixed
Parameters
$mbox : mixed
Tags
throws
IMP_Exception

__get()

public __get(mixed $key) : mixed
Parameters
$key : mixed

__set()

public __set(mixed $key, mixed $value) : mixed
Parameters
$key : mixed
$value : mixed

__toString()

public __toString() : mixed

create()

Create this mailbox on the server.

public create([array<string|int, mixed> $opts = array() ]) : bool
Parameters
$opts : array<string|int, mixed> = array()

Additional options:

  • special_use: (array) An array of special-use attributes to attempt to add to the mailbox. DEFAULT: NONE
  • subscribe: (boolean) Override preference value of subscribe.
Tags
throws
Horde_Exception
Return values
bool

True on success.

createMailboxName()

Return the mailbox name to create given a submailbox name.

public createMailboxName(string $new) : IMP_Mailbox
Parameters
$new : string

The submailbox name (UTF-8).

Return values
IMP_Mailbox

The mailbox to create.

delete()

Deletes mailbox.

public delete([array<string|int, mixed> $opts = array() ]) : bool
Parameters
$opts : array<string|int, mixed> = array()

Addtional options:

  • subfolders: (boolean) Delete all subfolders? DEFAULT: false
  • subfolders_only: (boolean) If deleting subfolders, delete only subfolders (not current mailbox)? DEFAULT: false
Return values
bool

True on success.

emptyMailbox()

Empties the entire mailbox.

public emptyMailbox() : mixed

equals()

Determines if this mailbox is equal to the given mailbox.

public equals(mixed $mbox) : bool

Needed because directly comparing two mailbox objects may fail (the member variables may be different).

Parameters
$mbox : mixed

The mailbox to compare to.

Return values
bool

True if the mailboxes are the same.

expunge()

Expunges all deleted messages.

public expunge([array<string|int, mixed> $to_expunge = array() ][, array<string|int, mixed> $opts = array() ]) : IMP_Indices
Parameters
$to_expunge : array<string|int, mixed> = array()

An optional array of indices to delete. If empty, all messages flagged as deleted in the mailbox will be deleted.

$opts : array<string|int, mixed> = array()

Additional options:

  - list: (boolean) Return a list of messages expunged.
          DEFAULT: false
Return values
IMP_Indices

If 'list' option is true, an indices object containing the messages that have been expunged.

filter()

Runs filters on this mailbox.

public filter() : mixed

filterOnDisplay()

Filters this mailbox if it is the INBOX and the filter on display pref is active.

public filterOnDisplay() : bool
Return values
bool

True if filter() was called.

flagAll()

Adds or removes flag(s) for all messages in the mailbox.

public flagAll(array<string|int, mixed> $flags[, bool $action = true ]) : bool

This function works with IMAP only, not POP3.

Parameters
$flags : array<string|int, mixed>

The IMAP flag(s) to add or remove.

$action : bool = true

If true, add the flag(s); otherwise, remove the flag(s).

Return values
bool

True if successful, false if not.

formFrom()

Converts a mailbox string from a form representation.

public static formFrom(mixed $mbox) : mixed

Needed because null characters (used for various internal non-IMAP mailbox representations) will not work in form elements.

Parameters
$mbox : mixed

The mailbox name(s).

Return values
mixed

The mailbox object(s).

formTo()

Converts a mailbox string to a form representation.

public static formTo(mixed $mbox) : mixed

Needed because null characters (used for various internal non-IMAP mailbox representations) will not work in form elements.

Parameters
$mbox : mixed

The mailbox name(s).

Return values
mixed

The converted mailbox string(s).

fromBuids()

Create an indices object from a list of browser-UIDs.

public fromBuids(IMP_Indices|array<string|int, mixed> $buids) : IMP_Indices
Parameters
$buids : IMP_Indices|array<string|int, mixed>

Browser-UIDs.

Return values
IMP_Indices

An indices object.

get()

Shortcut to obtaining mailbox object(s).

public static get(mixed $mbox) : mixed
Parameters
$mbox : mixed

The full IMAP mailbox name(s).

Return values
mixed

The IMP_Mailbox object(s).

getImapMboxOb()

Shortcut to obtaining Horde_Imap_Client_Mailbox object(s).

public static getImapMboxOb(mixed $mbox) : mixed
Parameters
$mbox : mixed

The full IMAP mailbox name(s).

Return values
mixed

The Horde_Imap_Client_Mailbox object(s).

getIndicesOb()

Return an indices object for this mailbox.

public getIndicesOb(mixed $in) : IMP_Indices
Parameters
$in : mixed

Either a single UID, array of UIDs, or a Horde_Imap_Client_Ids object.

Return values
IMP_Indices

An indices object.

getPref()

Shortcut to obtaining a mailbox object from a preference name.

public static getPref(mixed $pref) : IMP_Mailbox
Parameters
$pref : mixed
Return values
IMP_Mailbox

The IMP_Mailbox object.

getSort()

Return the sorting preference for this mailbox.

public getSort([bool $convert = false ]) : IMP_Prefs_Sort_Sortpref
Parameters
$convert : bool = false

Convert 'by' to a Horde_Imap_Client constant?

Return values
IMP_Prefs_Sort_Sortpref

Sortpref object.

getSpecialMailboxes()

Return the list of special mailboxes.

public static getSpecialMailboxes() : array<string|int, mixed>
Return values
array<string|int, mixed>

A list of mailboxes, with the self::SPECIAL_* constants as keys and values containing the IMP_Mailbox objects or null if the mailbox doesn't exist (self::SPECIAL_SENT contains an array of objects).

getSpecialMailboxesSort()

Return the list of sorted special mailboxes.

public static getSpecialMailboxesSort() : array<string|int, mixed>
Return values
array<string|int, mixed>

The list of sorted special mailboxes (IMP_Mailbox objects).

hideDeletedMsgs()

Are deleted messages hidden in this mailbox?

public hideDeletedMsgs([bool $deleted = false ]) : bool
Parameters
$deleted : bool = false

Return value is what should be done with deleted messages in general, as opposed to any deleted message in the mailbox.

Return values
bool

True if deleted messages should be hidden.

prefFrom()

Converts a mailbox name from a value stored in the preferences.

public static prefFrom(string $mbox) : string
Parameters
$mbox : string

The mailbox name as stored in a preference.

Return values
string

The full IMAP mailbox name (UTF-8).

prefTo()

Converts a mailbox name to a value to be stored in a preference.

public static prefTo(string $mbox) : string
Parameters
$mbox : string

The full IMAP mailbox name (UTF-8).

Return values
string

The value to store in a preference.

rename()

Rename this mailbox on the server. The subscription status remains the same. All subfolders will also be renamed.

public rename(string $new_name) : bool
Parameters
$new_name : string

The new mailbox name (UTF-8).

Return values
bool

True on success

runSearchQuery()

Run a search query on this mailbox that is not stored in the current session. Allows custom queries with custom sorts to be used without affecting cached mailboxes.

public runSearchQuery(Horde_Imap_Client_Search_Query $query[, int $sortby = null ][, int $sortdir = null ]) : IMP_Indices
Parameters
$query : Horde_Imap_Client_Search_Query

The search query object.

$sortby : int = null

The sort criteria.

$sortdir : int = null

The sort directory.

Return values
IMP_Indices

An indices object.

setHideDeletedMsgs()

Sets the 'delhide' preference and clears necessary cached data.

public setHideDeletedMsgs(bool $value) : mixed
Parameters
$value : bool

The value to set 'delhide' to.

setSort()

Set the sorting preference for this mailbox.

public setSort([int $by = null ][, int $dir = null ][, bool $delete = false ]) : mixed
Parameters
$by : int = null

The sort type.

$dir : int = null

The sort direction.

$delete : bool = false

Delete the entry?

subscribe()

Subscribe/unsubscribe to an IMAP mailbox.

public subscribe(bool $sub[, array<string|int, mixed> $opts = array() ]) : bool
Parameters
$sub : bool

True to subscribe, false to unsubscribe.

$opts : array<string|int, mixed> = array()

Additional options:

  • subfolders: (boolean) If true, applies actions to all subfolders.
Return values
bool

True on success.

url()

Generate a URL using the current mailbox.

public url(string|Horde_Url $page[, string $buid = null ][, bool $encode = true ]) : Horde_Url
Parameters
$page : string|Horde_Url

Page name to link to.

$buid : string = null

The BUID to use on the linked page.

$encode : bool = true

Encode the argument separator?

Return values
Horde_Url

URL to $page with any necessary mailbox information added to the parameter list of the URL.

urlParams()

Returns list of URL parameters necessary to indicate current mailbox status.

public urlParams([string $buid = null ]) : array<string|int, mixed>
Parameters
$buid : string = null

The BUID to use on the linked page.

Return values
array<string|int, mixed>

The list of parameters needed to indicate the current mailbox status.

_getCacheID()

Returns a unique identifier for this mailbox's status.

protected _getCacheID([bool $date = false ]) : string

This cache ID is guaranteed to change if messages are added/deleted from the mailbox. Additionally, if CONDSTORE is available on the remote IMAP server, this ID will change if flag information changes.

For search mailboxes, this value never changes (search mailboxes must be forcibly refreshed).

Parameters
$date : bool = false

If true, adds date information to ID.

Return values
string

The cache ID string, which will change when the composition of this mailbox changes.

_getDisplay()

If there is information available to tell us about a prefix in front of mailbox names that shouldn't be displayed to the user, then use it to strip that prefix out. Additionally, translate prefix text if this is a special mailbox.

protected _getDisplay([bool $notranslate = false ]) : string
Parameters
$notranslate : bool = false

Don't translate the mailbox prefix?

Return values
string

The mailbox, with any prefix gone/translated.

_getIcon()

Return icon information.

protected _getIcon() : object
Return values
object

Object with the following properties:

  • alt
  • class
  • icon
  • iconopen
  • user_icon

_onDelete()

Do the necessary cleanup/cache updates when deleting mailboxes.

protected _onDelete(array<string|int, mixed> $deleted) : mixed
Parameters
$deleted : array<string|int, mixed>

The list of deleted mailboxes.


        
On this page

Search results