Roundcube Framework
Back to top  

rcube_imap_generic

PHP based wrapper class to connect to an IMAP server

package

Framework
subpackage

Storage

Methods

Connects to IMAP server.

_connect(string $host) : boolean

Arguments

$host

string

Server hostname or IP

Response

boolean

True on success, False on failure

IMAP LIST/LSUB command

_listMailboxes(string $ref, string $mailbox, boolean $subscribed = false, array $return_opts = array(), array $select_opts = array()) : array|boolean

Arguments

$ref

string

Reference name

$mailbox

string

Mailbox name

$subscribed

boolean

Enables returning subscribed mailboxes only

$return_opts

array

List of RETURN options (RFC5819: LIST-STATUS, RFC5258: LIST-EXTENDED) Possible: MESSAGES, RECENT, UIDNEXT, UIDVALIDITY, UNSEEN, MYRIGHTS, SUBSCRIBED, CHILDREN

$select_opts

array

List of selection options (RFC5258: LIST-EXTENDED) Possible: SUBSCRIBED, RECURSIVEMATCH, REMOTE, SPECIAL-USE (RFC6154)

Response

array|boolean

List of mailboxes or hash of options if STATUS/MYROGHTS response is requested, False on error.

_xor

_xor( $string,  $string2)

Arguments

$string

$string2

Handler for IMAP APPEND command

append(string $mailbox, string|array &$message, array $flags = array(), string $date = null, boolean $binary = false) : string|boolean

Arguments

$mailbox

string

Mailbox name

$message

string|array

The message source string or array (of strings and file pointers)

$flags

array

Message flags

$date

string

Message internal date

$binary

boolean

Enable BINARY append (RFC3516)

Response

string|boolean

On success APPENDUID response (if available) or True, False on failure

Handler for IMAP APPEND command.

appendFromFile(string $mailbox, string $path, string $headers = null, array $flags = array(), string $date = null, boolean $binary = false) : string|boolean

Arguments

$mailbox

string

Mailbox name

$path

string

Path to the file with message body

$headers

string

Message headers

$flags

array

Message flags

$date

string

Message internal date

$binary

boolean

Enable BINARY append (RFC3516)

Response

string|boolean

On success APPENDUID response (if available) or True, False on failure

DIGEST-MD5/CRAM-MD5/PLAIN Authentication

authenticate(string $user, string $pass, string $type = 'PLAIN') : resource

Arguments

$user

string

Username

$pass

string

Password

$type

string

Authentication type (PLAIN/CRAM-MD5/DIGEST-MD5)

Response

resource

Connection resourse on success, error code on error

Clear internal cache of the current mailbox

clear_mailbox_cache()

Clear internal status cache

clear_status_cache( $mailbox)

Arguments

$mailbox

Clears detected server capabilities

clearCapability()

Removes all messages in a folder

clearFolder(string $mailbox) : boolean

Arguments

$mailbox

string

Mailbox name

Response

boolean

True on success, False on error

Executes CLOSE command

close() : boolean
since 0.5

Response

boolean

True on success, False on error

Closes connection with logout.

closeConnection()

Closes connection stream.

closeSocket()

Converts message identifiers array into sequence-set syntax

compressMessageSet(array $messages, boolean $force = false) : string
static

Arguments

$messages

array

Message identifiers

$force

boolean

Forces compression of any size

Response

string

Compressed sequence-set

Connects to IMAP server and authenticates.

connect(string $host, string $user, string $password, array $options = array()) : boolean

Arguments

$host

string

Server hostname or IP

$user

string

User name

$password

string

Password

$options

array

Connection and class options

Response

boolean

True on success, False on failure

Checks connection status

connected() : boolean

Response

boolean

True if connection is active and user is logged in, False otherwise.

Copies message(s) from one folder to another

copy(string|array $messages, string $from, string $to) : boolean

Arguments

$messages

string|array

Message UID(s)

$from

string

Mailbox name

$to

string

Destination mailbox name

Response

boolean

True on success, False on failure

Returns count of all messages in a folder

countMessages(string $mailbox) : integer

Arguments

$mailbox

string

Mailbox name

Response

integer

Number of messages, False on error

Returns count of messages with \Recent flag in a folder

countRecent(string $mailbox) : integer

Arguments

$mailbox

string

Mailbox name

Response

integer

Number of messages, False on error

Returns count of messages without \Seen flag in a specified folder

countUnseen(string $mailbox) : integer

Arguments

$mailbox

string

Mailbox name

Response

integer

Number of messages, False on error

Folder creation (CREATE)

createFolder(string $mailbox, array $types = null) : boolean

Arguments

$mailbox

string

Mailbox name

$types

array

Optional folder types (RFC 6154)

Response

boolean

True on success, False on error

Write the given debug text to the current debug output handler.

debug(string $message)
since 0.5-stable

Arguments

$message

string

Debug mesage text.

Send the DELETEACL command (RFC4314)

deleteACL(string $mailbox, string $user) : boolean
since 0.5-beta

Arguments

$mailbox

string

Mailbox name

$user

string

User name

Response

boolean

True on success, False on failure

Send the SETANNOTATION command with NIL values (draft-daboo-imap-annotatemore)

deleteAnnotation(string $mailbox, array $data) : boolean
since 0.5-beta

Arguments

$mailbox

string

Mailbox name

$data

array

Data array where each item is an array with two elements: entry name and attribute name

Response

boolean

True on success, False on failure

Executes DELETE command

deleteFolder(string $mailbox) : boolean

Arguments

$mailbox

string

Mailbox name

Response

boolean

True on success, False on error

Send the SETMETADATA command with NIL values (RFC5464)

deleteMetadata(string $mailbox, array $entries) : boolean
since 0.5-beta

Arguments

$mailbox

string

Mailbox name

$entries

array

Entry names array

Response

boolean

True on success, False on failure

Executes ENABLE command (RFC5161)

enable(mixed $extension) : array|boolean
since 0.6

Arguments

$extension

mixed

Extension name to enable (or array of names)

Response

array|boolean

List of enabled extensions, False on error

Checks connection stream state.

eof() : boolean

Response

boolean

True if connection is closed

Escapes a string when it contains special characters (RFC3501)

escape(string $string, boolean $force_quotes = false) : string
static
todo

lists

Arguments

$string

string

IMAP string

$force_quotes

boolean

Forces string quoting (for atoms)

Response

string

String atom, quoted-string or string literal

Sends IMAP command and parses result

execute(string $command, array $arguments = array(), integer $options) : mixed
since 0.5-beta

Arguments

$command

string

IMAP command

$arguments

array

Command arguments

$options

integer

Execution options

Response

mixed

Response code or list of response code and data

Executes EXPUNGE command

expunge(string $mailbox, string|array $messages = null) : boolean

Arguments

$mailbox

string

Mailbox name

$messages

string|array

Message UIDs to expunge

Response

boolean

True on success, False on error

FETCH command (RFC3501)

fetch(string $mailbox, mixed $message_set, boolean $is_uid = false, array $query_items = array(), string $mod_seq = null, boolean $vanished = false) : array
since 0.6

Arguments

$mailbox

string

Mailbox name

$message_set

mixed

Message(s) sequence identifier(s) or UID(s)

$is_uid

boolean

True if $message_set contains UIDs

$query_items

array

FETCH command data items

$mod_seq

string

Modification sequence for CHANGEDSINCE (RFC4551) query

$vanished

boolean

Enables VANISHED parameter (RFC5162) for CHANGEDSINCE query

Response

array

List of rcube_message_header elements, False on error

Returns message data (flags, headers, etc.)

fetchHeader(string $mailbox, integer $id, boolean $is_uid = false, boolean $bodystr = false, array $add_headers = array()) : boolean|\rcube_message_header

Arguments

$mailbox

string

Mailbox name

$id

integer

Message sequence identifier or UID

$is_uid

boolean

True if $id is an UID

$bodystr

boolean

Enable to add BODYSTRUCTURE data to the result

$add_headers

array

List of additional headers

Response

boolean|\rcube_message_header

Message data, False on error

Fetches specified header/data value for a set of messages.

fetchHeaderIndex(string $mailbox, string|array $message_set, string $index_field = '', boolean $skip_deleted = true, boolean $uidfetch = false, boolean $return_uid = false) : array|boolean

Arguments

$mailbox

string

Mailbox name

$message_set

string|array

Searching criteria (list of messages to return)

$index_field

string

Field to sort by (ARRIVAL, CC, DATE, FROM, SIZE, SUBJECT, TO)

$skip_deleted

boolean

Makes that DELETED messages will be skipped

$uidfetch

boolean

Enables UID FETCH usage

$return_uid

boolean

Enables returning UIDs instead of IDs

Response

array|boolean

List of header values or False on failure

Returns message(s) data (flags, headers, etc.)

fetchHeaders(string $mailbox, mixed $message_set, boolean $is_uid = false, boolean $bodystr = false, array $add_headers = array()) : boolean|array

Arguments

$mailbox

string

Mailbox name

$message_set

mixed

Message(s) sequence identifier(s) or UID(s)

$is_uid

boolean

True if $message_set contains UIDs

$bodystr

boolean

Enable to add BODYSTRUCTURE data to the result

$add_headers

array

List of additional headers

Response

boolean|array

List of rcube_message_header elements, False on error

Fetch MIME headers of specified message parts

fetchMIMEHeaders(string $mailbox, integer $uid, array $parts, boolean $mime = true) : array|boolean

Arguments

$mailbox

string

Mailbox name

$uid

integer

Message UID

$parts

array

Message part identifiers

$mime

boolean

Use MIME instad of HEADER

Response

array|boolean

Array containing headers string for each specified body False on failure.

Fetches message part header

fetchPartHeader( $mailbox,  $id,  $is_uid = false,  $part = null)

Arguments

$mailbox

$id

$is_uid

$part

Sets flag of the message(s)

flag(string $mailbox, string|array $messages, string $flag) : boolean

Arguments

$mailbox

string

Mailbox name

$messages

string|array

Message UID(s)

$flag

string

Flag name

Response

boolean

True on success, False on failure

Converts flags array into string for inclusion in IMAP command

flagsToStr(array $flags) : string

Arguments

$flags

array

Flags (see self::flags)

Response

string

Space-separated list of flags

Send the GETACL command (RFC4314)

getACL(string $mailbox) : array
since 0.5-beta

Arguments

$mailbox

string

Mailbox name

Response

array

User-rights array on success, NULL on error

Send the GETANNOTATION command (draft-daboo-imap-annotatemore)

getAnnotation(string $mailbox, array $entries, array $attribs) : array
since 0.5-beta

Arguments

$mailbox

string

Mailbox name

$entries

array

Entries names

$attribs

array

Attribs names

Response

array

Annotations result on success, NULL on error

Capabilities checker

getCapability(string $name) : mixed

Arguments

$name

string

Capability name

Response

mixed

Capability values array for key=value pairs, true/false for others

Detects hierarchy delimiter

getHierarchyDelimiter() : string

Response

string

The delimiter

Send the GETMETADATA command (RFC5464)

getMetadata(string $mailbox, array $entries, array $options = array()) : array
since 0.5-beta

Arguments

$mailbox

string

Mailbox name

$entries

array

Entries

$options

array

Command options (with MAXSIZE and DEPTH keys)

Response

array

GETMETADATA result on success, NULL on error

NAMESPACE handler (RFC 2342)

getNamespace() : array

Response

array

Namespace data hash (personal, other, shared)

Returns QUOTA information

getQuota(string $mailbox = null) : array

Arguments

$mailbox

string

Mailbox name

Response

array

Quota information

Returns BODYSTRUCTURE for the specified message.

getStructure(string $mailbox, integer $id, boolean $is_uid = false) : \array/bool
since 0.6

Arguments

$mailbox

string

Folder name

$id

integer

Message sequence number or UID

$is_uid

boolean

True if $id is an UID

Response

\array/bool

Body structure array or False on error.

getStructurePartArray

getStructurePartArray( $a,  $part)
static

Arguments

$a

$part

Returns data of a message part according to specified structure.

getStructurePartData(array $structure, string $part) : array
static

Arguments

$structure

array

Message structure (getStructure() result)

$part

string

Message part identifier

Response

array

Part data as hash array (type, encoding, charset, size)

Fetches body of the specified message part

handlePartBody( $mailbox,  $id,  $is_uid = false,  $part = '',  $encoding = null,  $print = null,  $file = null,  $formatted = false,  $max_bytes)

Arguments

$mailbox

$id

$is_uid

$part

$encoding

$print

$file

$formatted

$max_bytes

Capabilities checker

hasCapability( $name)

Arguments

$name

Executes ID command (RFC2971)

id(array $items = array()) : array
since 0.6

Arguments

$items

array

Client identification information key/value hash

Response

array

Server identification information key/value hash

Returns message unique identifier (UID)

ID2UID(string $mailbox,  $id) : integer

Arguments

$mailbox

string

Mailbox name

$id

Response

integer

Message unique identifier

Simulates SORT command by using FETCH and sorting.

index(string $mailbox, string|array $message_set, string $index_field = '', boolean $skip_deleted = true, boolean $uidfetch = false, boolean $return_uid = false) : \rcube_result_index

Arguments

$mailbox

string

Mailbox name

$message_set

string|array

Searching criteria (list of messages to return)

$index_field

string

Field to sort by (ARRIVAL, CC, DATE, FROM, SIZE, SUBJECT, TO)

$skip_deleted

boolean

Makes that DELETED messages will be skipped

$uidfetch

boolean

Enables UID FETCH usage

$return_uid

boolean

Enables returning UIDs instead of IDs

Response

\rcube_result_index

Response data

Returns list of mailboxes

listMailboxes(string $ref, string $mailbox, array $return_opts = array(), array $select_opts = array()) : array|boolean

Arguments

$ref

string

Reference name

$mailbox

string

Mailbox name

$return_opts

array

(see self::_listMailboxes)

$select_opts

array

(see self::_listMailboxes)

Response

array|boolean

List of mailboxes or hash of options if STATUS/MYROGHTS response is requested, False on error.

Send the LISTRIGHTS command (RFC4314)

listRights(string $mailbox, string $user) : array
since 0.5-beta

Arguments

$mailbox

string

Mailbox name

$user

string

User name

Response

array

List of user rights

Returns list of subscribed mailboxes

listSubscribed(string $ref, string $mailbox, array $return_opts = array()) : array|boolean

Arguments

$ref

string

Reference name

$mailbox

string

Mailbox name

$return_opts

array

(see self::_listMailboxes)

Response

array|boolean

List of mailboxes or hash of options if STATUS/MYROGHTS response is requested, False on error.

Changes flag of the message(s)

modFlag(string $mailbox, string|array $messages, string $flag, string $mod = '+') : boolean

Arguments

$mailbox

string

Mailbox name

$messages

string|array

Message UID(s)

$flag

string

Flag name

$mod

string

Modifier [+|-]. Default: "+".

Response

boolean

True on success, False on failure

Moves message(s) from one folder to another.

move(string|array $messages, string $from, string $to) : boolean

Arguments

$messages

string|array

Message UID(s)

$from

string

Mailbox name

$to

string

Destination mailbox name

Response

boolean

True on success, False on failure

Reads more data from the connection stream when provided data contain string literal

multLine(string $line, boolean $escape = false) : string

Arguments

$line

string

Response text

$escape

boolean

Enables escaping

Response

string

Line of text response

Send the MYRIGHTS command (RFC4314)

myRights(string $mailbox) : array
since 0.5-beta

Arguments

$mailbox

string

Mailbox name

Response

array

MYRIGHTS response on success, NULL on error

Creates next command identifier (tag)

nextTag() : string
since 0.5-beta

Response

string

Command identifier

CAPABILITY response parser

parseCapability( $str,  $trusted = false)

Arguments

$str

$trusted

Response parser.

parseResult(string $string, string $err_prefix = '') : integer

Arguments

$string

string

Response text

$err_prefix

string

Error message prefix

Response

integer

Response status

Send simple (one line) command to the connection stream

putLine(string $string, boolean $endln = true, boolean $anonymized = false)

Arguments

$string

string

Command string

$endln

boolean

True if CRLF need to be added at the end of command

$anonymized

boolean

Don't write the given data to log but a placeholder

Send command to the connection stream with Command Continuation Requests (RFC3501 7.5) and LITERAL+ (RFC2088) support

putLineC(string $string, boolean $endln = true, boolean $anonymized = false) : integer|boolean

Arguments

$string

string

Command string

$endln

boolean

True if CRLF need to be added at the end of command

$anonymized

boolean

Don't write the given data to log but a placeholder

Response

integer|boolean

Number of bytes sent, False on error

r_implode

r_implode( $element)
static

Arguments

$element

Reads specified number of bytes from the connection stream

readBytes(integer $bytes) : string

Arguments

$bytes

integer

Number of bytes to get

Response

string

Response text

Reads line from the connection stream

readLine(integer $size = 1024) : string

Arguments

$size

integer

Buffer size

Response

string

Line of text response

Reads complete response to the IMAP command

readReply(array &$untagged = null) : string

Arguments

$untagged

array

Will be filled with untagged response lines

Response

string

Response text

Folder renaming (RENAME)

renameFolder( $from,  $to) : boolean

Arguments

$from

$to

Response

boolean

True on success, False on error

Executes SEARCH command

search(string $mailbox, string $criteria, boolean $return_uid = false, array $items = array()) : \rcube_result_index

Arguments

$mailbox

string

Mailbox name

$criteria

string

Searching criteria

$return_uid

boolean

Enable UID in result instead of sequence ID

$items

array

Return items (MIN, MAX, COUNT, ALL)

Response

\rcube_result_index

Result data

Executes SELECT command (if mailbox is already not in selected state)

select(string $mailbox, array $qresync_data = null) : boolean

Arguments

$mailbox

string

Mailbox name

$qresync_data

array

QRESYNC data (RFC5162)

Response

boolean

True on success, false on error

Initializes environment

set_prefs( $prefs)

Arguments

$prefs

Send the SETACL command (RFC4314)

setACL(string $mailbox, string $user, mixed $acl) : boolean
since 0.5-beta

Arguments

$mailbox

string

Mailbox name

$user

string

User name

$acl

mixed

ACL string or array

Response

boolean

True on success, False on failure

Send the SETANNOTATION command (draft-daboo-imap-annotatemore)

setAnnotation(string $mailbox, array $data) : boolean
since 0.5-beta

Arguments

$mailbox

string

Mailbox name

$data

array

Data array where each item is an array with three elements: entry name, attribute name, value

Response

boolean

True on success, False on failure

Set the value of the debugging flag.

setDebug(boolean $debug, callback $handler = null)
since 0.5-stable

Arguments

$debug

boolean

New value for the debugging flag.

$handler

callback

Logging handler function

Error code/message setter.

setError( $code,  $msg = '')

Arguments

$code

$msg

Send the SETMETADATA command (RFC5464)

setMetadata(string $mailbox, array $entries) : boolean
since 0.5-beta

Arguments

$mailbox

string

Mailbox name

$entries

array

Entry-value array (use NULL value as NIL)

Response

boolean

True on success, False on failure

Executes SORT command

sort(string $mailbox, string $field = 'ARRIVAL', string $criteria = '', boolean $return_uid = false, string $encoding = 'US-ASCII') : \rcube_result_index

Arguments

$mailbox

string

Mailbox name

$field

string

Field to sort by (ARRIVAL, CC, DATE, FROM, SIZE, SUBJECT, TO)

$criteria

string

Searching criteria

$return_uid

boolean

Enables UID SORT usage

$encoding

string

Character set

Response

\rcube_result_index

Response data

Sort messages by specified header field

sortHeaders(array $messages, string $field, string $flag) : array
static

Arguments

$messages

array

Array of rcube_message_header objects

$field

string

Name of the property to sort by

$flag

string

Sorting order (ASC|DESC)

Response

array

Sorted input array

Checks response status.

startsWith(string $string, string $match, boolean $error = false, boolean $nonempty = false) : boolean

Checks if command response line starts with specified prefix (or * BYE/BAD)

Arguments

$string

string

Response text

$match

string

Prefix to match with (case-sensitive)

$error

boolean

Enables BYE/BAD checking

$nonempty

boolean

Enables empty response checking

Response

boolean

True any check is true or connection is closed.

Executes STATUS command

status(string $mailbox, array $items = array()) : array
since 0.5-beta

Arguments

$mailbox

string

Mailbox name

$items

array

Additional requested item names. By default MESSAGES and UNSEEN are requested. Other defined in RFC3501: UIDNEXT, UIDVALIDITY, RECENT

Response

array

Status item-value hash

Converts datetime string into unix timestamp

strToTime(string $date) : integer
static

Arguments

$date

string

Date string

Response

integer

Unix timestamp

Folder subscription (SUBSCRIBE)

subscribe(string $mailbox) : boolean

Arguments

$mailbox

string

Mailbox name

Response

boolean

True on success, False on error

Executes THREAD command

thread(string $mailbox, string $algorithm = 'REFERENCES', string $criteria = '', boolean $return_uid = false, string $encoding = 'US-ASCII') : \rcube_result_thread

Arguments

$mailbox

string

Mailbox name

$algorithm

string

Threading algorithm (ORDEREDSUBJECT, REFERENCES, REFS)

$criteria

string

Searching criteria

$return_uid

boolean

Enables UIDs in result instead of sequence numbers

$encoding

string

Character set

Response

\rcube_result_thread

Thread data

Splits IMAP response into string tokens

tokenizeResponse( &$str, integer $num) : mixed
static
since 0.5-beta

Arguments

$str

$num

integer

Number of tokens to return

Response

mixed

Tokens array or string if $num=1

Returns message sequence identifier

UID2ID(string $mailbox, integer $uid) : integer

Arguments

$mailbox

string

Mailbox name

$uid

integer

Message unique identifier (UID)

Response

integer

Message sequence identifier

Converts message sequence-set into array

uncompressMessageSet(string $messages) : array
static

Arguments

$messages

string

Message identifiers

Response

array

List of message identifiers

Unsets flag of the message(s)

unflag(string $mailbox, string|array $messages, string $flag) : boolean

Arguments

$mailbox

string

Mailbox name

$messages

string|array

Message UID(s)

$flag

string

Flag name

Response

boolean

True on success, False on failure

Folder unsubscription (UNSUBSCRIBE)

unsubscribe(string $mailbox) : boolean

Arguments

$mailbox

string

Mailbox name

Response

boolean

True on success, False on error

Constants

ERROR_OK

ERROR_OK

ERROR_NO

ERROR_NO

ERROR_BAD

ERROR_BAD

ERROR_BYE

ERROR_BYE

ERROR_UNKNOWN

ERROR_UNKNOWN

ERROR_COMMAND

ERROR_COMMAND

ERROR_READONLY

ERROR_READONLY

COMMAND_NORESPONSE

COMMAND_NORESPONSE

COMMAND_CAPABILITY

COMMAND_CAPABILITY

COMMAND_LASTLINE

COMMAND_LASTLINE

COMMAND_ANONYMIZED

COMMAND_ANONYMIZED

DEBUG_LINE_LENGTH

DEBUG_LINE_LENGTH

Properties

error

error :

Type(s)

errornum

errornum :

Type(s)

result

result :

Type(s)

resultcode

resultcode :

Type(s)

selected

selected :

Type(s)

data

data :

Type(s)

flags

flags :

Type(s)

fp

fp :

Type(s)

host

host :

Type(s)

cmd_tag

cmd_tag :

Type(s)

cmd_num

cmd_num :

Type(s)

resourceid

resourceid :

Type(s)

prefs

prefs :

Type(s)

logged

logged :

Type(s)

capability

capability :

Type(s)

capability_readed

capability_readed :

Type(s)

debug

debug :

Type(s)

debug_handler

debug_handler :

Type(s)