rcube_imap_generic

PHP based wrapper class to connect to an IMAP server

package

Framework

subpackage

Storage

Methods

Object constructor

__construct() 

Send simple (one line) command to the connection stream

putLine(string $string, bool $endln = true) 

Arguments

$string

string

Command string

$endln

bool

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

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

putLineC(string $string, bool $endln = true) : int|bool

Arguments

$string

string

Command string

$endln

bool

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

Response

int|bool

Number of bytes sent, False on error

Reads line from the connection stream

readLine(int $size = 1024) : string

Arguments

$size

int

Buffer size

Response

string

Line of text response

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

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

Arguments

$line

string

Response text

$escape

bool

Enables escaping

Response

string

Line of text response

Reads specified number of bytes from the connection stream

readBytes(int $bytes) : string

Arguments

$bytes

int

Number of bytes to get

Response

string

Response text

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

Response parser.

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

Arguments

$string

string

Response text

$err_prefix

string

Error message prefix

Response

int

Response status

Checks connection stream state.

eof() : bool

Response

bool

True if connection is closed

Closes connection stream.

closeSocket() 

Error code/message setter.

setError($code, $msg = '') 

Arguments

$code

$msg

Checks response status.

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

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

bool

Enables BYE/BAD checking

$nonempty

bool

Enables empty response checking

Response

bool

True any check is true or connection is closed.

hasCapability

hasCapability($name) 

Arguments

$name

Capabilities checker

getCapability(string $name) : mixed

Arguments

$name

string

Capability name

Response

mixed

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

clearCapability

clearCapability() 

DIGEST-MD5/CRAM-MD5/PLAIN Authentication

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

Arguments

$user

string

$pass

string

$type

string

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

Response

resource

Connection resourse on success, error code on error

Detects hierarchy delimiter

getHierarchyDelimiter() : string

Response

string

The delimiter

NAMESPACE handler (RFC 2342)

getNamespace() : array

Response

array

Namespace data hash (personal, other, shared)

Connects to IMAP server and authenticates.

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

Arguments

$host

string

Server hostname or IP

$user

string

User name

$password

string

Password

$options

array

Connection and class options

Response

bool

True on success, False on failure

Initializes environment

set_prefs($prefs) 

Arguments

$prefs

Checks connection status

connected() : bool

Response

bool

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

Closes connection with logout.

closeConnection() 

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

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

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

Executes CLOSE command

close() : boolean
since 0.5

Response

boolean

True on success, False on error

Folder subscription (SUBSCRIBE)

subscribe(string $mailbox) : boolean

Arguments

$mailbox

string

Mailbox name

Response

boolean

True on success, False on error

Folder unsubscription (UNSUBSCRIBE)

unsubscribe(string $mailbox) : boolean

Arguments

$mailbox

string

Mailbox name

Response

boolean

True on success, False on error

Folder creation (CREATE)

createFolder(string $mailbox) : bool

Arguments

$mailbox

string

Mailbox name

Response

bool

True on success, False on error

Folder renaming (RENAME)

renameFolder($from, $to) : bool

Arguments

$from

$to

Response

bool

True on success, False on error

Executes DELETE command

deleteFolder(string $mailbox) : boolean

Arguments

$mailbox

string

Mailbox name

Response

boolean

True on success, False on error

Removes all messages in a folder

clearFolder(string $mailbox) : boolean

Arguments

$mailbox

string

Mailbox name

Response

boolean

True on success, False on error

Returns list of mailboxes

listMailboxes(string $ref, string $mailbox, array $status_opts = array(), array $select_opts = array()) : array

Arguments

$ref

string

Reference name

$mailbox

string

Mailbox name

$status_opts

array

(see self::_listMailboxes)

$select_opts

array

(see self::_listMailboxes)

Response

array

List of mailboxes or hash of options if $status_opts argument

          is non-empty.

Returns list of subscribed mailboxes

listSubscribed(string $ref, string $mailbox, array $status_opts = array()) : array

Arguments

$ref

string

Reference name

$mailbox

string

Mailbox name

$status_opts

array

(see self::_listMailboxes)

Response

array

List of mailboxes or hash of options if $status_opts argument

          is non-empty.

IMAP LIST/LSUB command

_listMailboxes(string $ref, string $mailbox, bool $subscribed = false, array $status_opts = array(), array $select_opts = array()) : array

Arguments

$ref

string

Reference name

$mailbox

string

Mailbox name

$subscribed

bool

Enables returning subscribed mailboxes only

$status_opts

array

List of STATUS options (RFC5819: LIST-STATUS)

                       Possible: MESSAGES, RECENT, UIDNEXT, UIDVALIDITY, UNSEEN

$select_opts

array

List of selection options (RFC5258: LIST-EXTENDED)

                       Possible: SUBSCRIBED, RECURSIVEMATCH, REMOTE

Response

array

List of mailboxes or hash of options if $status_ops argument

          is non-empty.

Returns count of all messages in a folder

countMessages(string $mailbox, $refresh = false) : int

Arguments

$mailbox

string

Mailbox name

$refresh

Response

int

Number of messages, False on error

Returns count of messages with \Recent flag in a folder

countRecent(string $mailbox) : int

Arguments

$mailbox

string

Mailbox name

Response

int

Number of messages, False on error

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

countUnseen(string $mailbox) : int

Arguments

$mailbox

string

Mailbox name

Response

int

Number of messages, False on error

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

Executes ENABLE command (RFC5161)

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

Arguments

$extension

mixed

Extension name to enable (or array of names)

Response

array|bool

List of enabled extensions, False on error

Executes SORT command

sort(string $mailbox, string $field, string $add = '', bool $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)

$add

string

Searching criteria

$return_uid

bool

Enables UID SORT usage

$encoding

string

Character set

Response

\rcube_result_index

Response data

Executes THREAD command

thread(string $mailbox, string $algorithm = 'REFERENCES', string $criteria = '', bool $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

bool

Enables UIDs in result instead of sequence numbers

$encoding

string

Character set

Response

\rcube_result_thread

Thread data

Simulates SORT command by using FETCH and sorting.

index(string $mailbox, string|array $message_set, string $index_field = '', bool $skip_deleted = true, bool $uidfetch = false, bool $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

bool

Makes that DELETED messages will be skipped

$uidfetch

bool

Enables UID FETCH usage

$return_uid

bool

Enables returning UIDs instead of IDs

Response

\rcube_result_index

Response data

fetchHeaderIndex

fetchHeaderIndex($mailbox, $message_set, $index_field = '', $skip_deleted = true, $uidfetch = false, $return_uid = false) 

Arguments

$mailbox

$message_set

$index_field

$skip_deleted

$uidfetch

$return_uid

Returns message sequence identifier

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

Arguments

$mailbox

string

Mailbox name

$uid

int

Message unique identifier (UID)

Response

int

Message sequence identifier

Returns message unique identifier (UID)

ID2UID(string $mailbox, $id) : int

Arguments

$mailbox

string

Mailbox name

$id

Response

int

Message unique identifier

Sets flag of the message(s)

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

Arguments

$mailbox

string

Mailbox name

$messages

string|array

Message UID(s)

$flag

string

Flag name

Response

bool

True on success, False on failure

Unsets flag of the message(s)

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

Arguments

$mailbox

string

Mailbox name

$messages

string|array

Message UID(s)

$flag

string

Flag name

Response

bool

True on success, False on failure

Changes flag of the message(s)

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

Arguments

$mailbox

string

Mailbox name

$messages

string|array

Message UID(s)

$flag

string

Flag name

$mod

string

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

Response

bool

True on success, False on failure

Copies message(s) from one folder to another

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

Arguments

$messages

string|array

Message UID(s)

$from

string

Mailbox name

$to

string

Destination mailbox name

Response

bool

True on success, False on failure

Moves message(s) from one folder to another.

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

Arguments

$messages

string|array

Message UID(s)

$from

string

Mailbox name

$to

string

Destination mailbox name

Response

bool

True on success, False on failure

FETCH command (RFC3501)

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

Arguments

$mailbox

string

Mailbox name

$message_set

mixed

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

$is_uid

bool

True if $message_set contains UIDs

$query_items

array

FETCH command data items

$mod_seq

string

Modification sequence for CHANGEDSINCE (RFC4551) query

$vanished

bool

Enables VANISHED parameter (RFC5162) for CHANGEDSINCE query

Response

array

List of rcube_message_header elements, False on error

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

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

Arguments

$mailbox

string

Mailbox name

$message_set

mixed

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

$is_uid

bool

True if $message_set contains UIDs

$bodystr

bool

Enable to add BODYSTRUCTURE data to the result

$add_headers

array

List of additional headers

Response

bool|array

List of rcube_message_header elements, False on error

Returns message data (flags, headers, etc.)

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

Arguments

$mailbox

string

Mailbox name

$id

int

Message sequence identifier or UID

$is_uid

bool

True if $id is an UID

$bodystr

bool

Enable to add BODYSTRUCTURE data to the result

$add_headers

array

List of additional headers

Response

bool|\rcube_message_header

Message data, False on error

sortHeaders

sortHeaders($a, $field, $flag) 

Arguments

$a

$field

$flag

fetchMIMEHeaders

fetchMIMEHeaders($mailbox, $uid, $parts, $mime = true) 

Arguments

$mailbox

$uid

$parts

$mime

fetchPartHeader

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

Arguments

$mailbox

$id

$is_uid

$part

handlePartBody

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

Handler for IMAP APPEND command

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

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

bool

Enable BINARY append (RFC3516)

Response

string|bool

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, bool $binary = false) : string|bool

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

bool

Enable BINARY append (RFC3516)

Response

string|bool

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

Returns QUOTA information

getQuota() : array

Response

array

Quota information

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 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 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 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

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

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

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

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

Returns BODYSTRUCTURE for the specified message.

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

Arguments

$mailbox

string

Folder name

$id

int

Message sequence number or UID

$is_uid

bool

True if $id is an UID

Response

\array/bool

Body structure array or False on error.

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)

getStructurePartArray

getStructurePartArray($a, $part) 
static

Arguments

$a

$part

Creates next command identifier (tag)

nextTag() : string
since 0.5-beta

Response

string

Command identifier

Sends IMAP command and parses result

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

Arguments

$command

string

IMAP command

$arguments

array

Command arguments

$options

int

Execution options

Response

mixed

Response code or list of response code and data

Splits IMAP response into string tokens

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

Arguments

$str

$num

int

Number of tokens to return

Response

mixed

Tokens array or string if $num=1

r_implode

r_implode($element) 
static

Arguments

$element

Converts message identifiers array into sequence-set syntax

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

Arguments

$messages

array

Message identifiers

$force

bool

Forces compression of any size

Response

string

Compressed sequence-set

Converts message sequence-set into array

uncompressMessageSet(string $messages) : array
static

Arguments

$messages

string

Message identifiers

Response

array

List of message identifiers

_xor

_xor($string, $string2) 

Arguments

$string

$string2

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

Converts datetime string into unix timestamp

strToTime(string $date) : int
static

Arguments

$date

string

Date string

Response

int

Unix timestamp

CAPABILITY response parser

parseCapability($str, $trusted = false) 

Arguments

$str

$trusted

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

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

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

debug(string $message) 
since 0.5-stable

Arguments

$message

string

Debug mesage text.

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

DEBUG_LINE_LENGTH

DEBUG_LINE_LENGTH

Properties

error

error : 

errornum

errornum : 

result

result : 

resultcode

resultcode : 

selected

selected : 

data

data : 

flags

flags : 

mupdate

mupdate : 
static

fp

fp : 

host

host : 

logged

logged : 

capability

capability : 

capability_readed

capability_readed : 

prefs

prefs : 

cmd_tag

cmd_tag : 

cmd_num

cmd_num : 

resourceid

resourceid : 

_debug

_debug : 

_debug_handler

_debug_handler :