Mail_IMAPv2
[ class tree: Mail_IMAPv2 ] [ index: Mail_IMAPv2 ] [ all elements ]

Class: Mail_IMAPv2

Source Location: /Mail_IMAPv2-0.2.1/Mail/IMAPv2.php

Class Overview


Mail_IMAPv2 provides a flexible API for connecting to and retrieving mail from mailboxes using the IMAP, POP3 or NNTP mail protocols.


Author(s):

Version:

  • 0.2.0

Copyright:

  • (c) Copyright 2004, Richard York, All Rights Reserved.

Variables

Methods


Child classes:

Mail_IMAPv2_ManageMB
This class provides an extension to Mail_IMAPv2 that adds mailbox management
Mail_IMAPv2_Debug
This class provides an extension to Mail_IMAPv2 that adds debugging utilities for the base IMAP.php class. The debugging functionality provided by this class is currently accessed by supplying various $_GET method arguments.

Inherited Variables

Inherited Methods


Class Details

[line 114]
Mail_IMAPv2 provides a flexible API for connecting to and retrieving mail from mailboxes using the IMAP, POP3 or NNTP mail protocols.

Connection to a mailbox is acheived through the c-client extension to PHP (http://www.php.net/imap). Meaning installation of the c-client extension is required to use Mail_IMAPv2.

Mail_IMAPv2 can be used to retrieve the contents of a mailbox, whereas it may serve as the backend for a webmail application or mailing list manager.

Since Mail_IMAPv2 is an abstracted object, it allows for complete customization of the UI for any application.

By default Mail_IMAPv2 parses and retrieves information about multipart message in a threaded fashion similar to MS Outlook, e.g. only top level attachments are retrieved initially, then when message part id and message id are passed to Mail_IMAPv2, it retrieves attachments and information relevant to that message part. getParts can be supplied an argument to turn off threading, whereas all parts are retrieved at once.

Mail_IMAPv2 also, by default retrieves the alternative message parts of multipart messages. This is most useful for debugging applications that send out multipart mailers where both a text/html and alterntaive text/plain part are included. This can also be turned off by supplying an additional argument to getParts.

Mail_IMAPv2 always searches for a text/html part to display as the primary part. This can be reversed so that it always looks for a text/plain part initially by supplying the necessary arguments to getParts, and getBody.

PLEASE REPORT BUGS FOLLOWING THE GUIDELINES AT: http://www.smilingsouls.net/Mail_IMAP

  • Tutorial: http://www.smilingsouls.net/Mail_IMAP
  • Author: Richard York <rich_y@php.net>
  • Version: 0.2.0
  • Copyright: (c) Copyright 2004, Richard York, All Rights Reserved.
  • Since: PHP 4.2.0
  • Since: C-Client 2001
  • Example: example not found
  • Example: example not found
  • Example: example not found
  • Example: example not found
  • License: BSD
  • Example: example not found


[ Top ]


Class Variables

$error =

[line 122]

Contains an instance of the PEAR_ErrorStack object.
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/error
  • Access: public

Type:   object


[ Top ]

$fields = array(
       'fname',
        'pid',
        'ftype',
        'fsize',
        'has_at',
        'charset',
        'cid'
    )

[line 230]

(string) Contains the fields searched for and added to inline and attachment part arrays. These are the 'in' and 'at' associative indices of the $msg member variable.
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/fields
  • Access: public

Type:   array


[ Top ]

$header = array()

[line 189]

(array)(mixed) Associative array containing information gathered by imap_headerinfo or imap_rfc822_parse_headers.

Type:   header


[ Top ]

$mailbox =

[line 132]

Contains the imap resource stream.
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/mailbox
  • See: open
  • See: Mail_IMAPv2
  • Access: public

Type:   resource


[ Top ]

$mailboxInfo = array()

[line 142]

Contains information about the current mailbox.

Type:   array


[ Top ]

$msg = array()

[line 177]

Contains various information about a message, separates inline parts from attachments and contains the default part id for each message.
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/msg
  • Access: public

Type:   array


[ Top ]

$option = array()

[line 156]

Set flags for various imap_* functions.

Use associative indices to indicate the imap_* function to set flags for, create the indice omitting the 'imap_' portion of the function name. see: setOptions for more information.


Type:   array


[ Top ]

$structure = array()

[line 167]

Contains various information returned by imap_fetchstructure.

The object returned by imap_fetchstructure stored in $this->structure[$mid]['obj'].


Type:   array


[ Top ]



Method Detail

Mail_IMAPv2 (Constructor)   [line 263]

BOOL|null|PEAR_Error Mail_IMAPv2( [string $connection = null], [ $get_info = true], int $action)

Constructor. Optionally set the IMAP resource stream.

If IMAP connection arguments are not supplied, returns null. Accepts a URI abstraction of the standard imap_open connection argument (see connect) or the imap resource indicator.

If the optional flags argument of imap_open needs to be set, then connect should be called after either setting the $option member variable or calling setOptions.

Since Mail_IMAPv2 0.1.0 creates an instance of PEAR_ErrorStack. $options argument became $get_info argument see connect.

  • Tutorial: http://www.smilingsouls.net/?content=Mail_IMAP/Mail_IMAP
  • See: Mail_IMAPv2::connect()
  • See: imap_open
  • Access: public

Parameters:

string   $connection     (optional) server URI | imap resource identifier
int   $action     
   $get_info     

[ Top ]

alerts   [line 1840]

bool|string alerts( [bool $handler = true], [string $seperator = "<br />\n"])

Wrapper function for imap_alerts. Implodes the array returned by imap_alerts, (if any) and returns the text.
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/alerts
  • See: Mail_IMAPv2::errors()
  • See: imap_alerts
  • Access: public

Parameters:

bool   $handler     How to handle the imap error stack, true by default. If true adds the alerts to the PEAR_ErrorStack object. If false, returns the imap alert stack.
string   $seperator     Characters to seperate each alert message. '
\n' by default.

[ Top ]

close   [line 465]

BOOL close( )

Wrapper method for imap_close. Close the IMAP resource stream.
  • Tutorial: http://www.smilingsouls.net/index.php?content=Mail_IMAP/close
  • See: imap_close
  • Access: public

[ Top ]

connect   [line 321]

BOOL connect( string $uri, [bool $get_info = true])

Wrapper method for imap_open. Accepts a URI abstraction in the following format: imap://user:pass@mail.example.com:143/INBOX#notls instead of the standard connection arguments used in imap_open.

Replace the protocol with one of pop3|pop3s imap|imaps nntp|nntps. Place intial folder in the file path portion, and optionally append tls|notls|novalidate-cert in the anchor portion of the URL. A port number is optional, however, leaving it off could lead to a serious degradation in preformance.

Since Mail_IMAPv2 0.1.0 the $options argument became the $get_info argument. constants for action were removed and the argument is now a BOOL toggle.

  • Tutorial: http://www.smilingsouls.net/index.php?content=Mail_IMAP/connect
  • See: imap_open
  • Access: public

Parameters:

string   $uri     server URI
bool   $get_info     (optional) true by default. If true, make a call to getMailboxInfo if false do not call getMailboxInfo

[ Top ]

convertBytes   [line 1697]

string convertBytes( int $bytes)

Converts an integer containing the number of bytes in a file to one of Bytes, Kilobytes, Megabytes, or Gigabytes, appending the unit of measurement.

This method may be called statically.

  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/convertBytes
  • Access: public

Parameters:

int   $bytes     

[ Top ]

delete   [line 1731]

BOOL delete( int &$mid, [ $separator = "<br />\n"])

Wrapper function for imap_delete. Sets the marked for deletion flag. Note: POP3 mailboxes do not remember flag settings between connections, for POP3 mailboxes this function should be used in addtion to expunge.
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/delete
  • See: imap_delete
  • See: Mail_IMAPv2::expunge()
  • Access: public

Parameters:

int   &$mid     message id
   $separator     

[ Top ]

errors   [line 1803]

bool|string errors( [bool $handler = true], [string $seperator = "<br />\n"])

Wrapper function for imap_errors. Implodes the array returned by imap_errors, (if any) and returns the error text.
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/errors
  • See: Mail_IMAPv2::alerts()
  • See: imap_errors
  • Access: public

Parameters:

bool   $handler     How to handle the imap error stack, true by default. If true adds the errors to the PEAR_ErrorStack object. If false, returns the imap error stack.
string   $seperator     (optional) Characters to seperate each error message. "
\n" by default.

[ Top ]

errorTemplate   [line 286]

void errorTemplate( )

  • Todo: Finish writing this method, and test it.

[ Top ]

expunge   [line 1776]

BOOL expunge( )

Wrapper function for imap_expunge. Expunges messages marked for deletion.
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/expunge
  • See: imap_expunge
  • See: Mail_IMAPv2::delete()
  • Access: public

[ Top ]

extractMIME   [line 1346]

array|false extractMIME( int &$mid, string|array $MIMEs)

Searches all message parts for the specified MIME type. Use getBody with $action option Mail_IMAPv2_LITERAL_DECODE to view MIME type parts retrieved.

If you need to access the MIME type with filename use normal getBody with no action specified.

Returns an array of part ids on success. Returns false if MIME couldn't be found, or on failure.

  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/extractMIME
  • Access: public

Parameters:

int   &$mid     message id
string|array   $MIMEs     mime type to extract

[ Top ]

getBody   [line 1081]

array|string|false getBody( int &$mid, [string $pid = '1'], [int $action = 0], [ $get_mime = 'text/html'], [int $attempt = 1], string $getPart)

Searches parts array set in $this->_declareParts() for a displayable message.

If the part id passed is message/rfc822 looks in subparts for a displayable body. Attempts to return a text/html inline message part by default. And will automatically attempt to find a text/plain part if a text/html part could not be found.

Returns an array containing three associative indices; 'ftype', 'fname' and 'message'. 'ftype' contains the MIME type of the message, 'fname', the original file name, if any, empty string otherwise. And 'message', which contains the message body itself which is returned decoded from base64 or quoted-printable if either of those encoding types are specified, returns untouched otherwise. Returns false on failure.

  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/getBody
  • See: $this->getParts
  • See: imap_fetchbody
  • Since: PHP 4.2.0
  • Access: public

Parameters:

int   &$mid     message id
string   $pid     part id
int   $action     (optional) options for body return. Set to one of the following: Mail_IMAPv2_BODY (default), if part is message/rfc822 searches subparts for a displayable body and returns the body decoded as part of an array. Mail_IMAPv2_LITERAL, return the message for the specified $pid without searching subparts or decoding the message (may return unparsed message) body is returned undecoded as a string. Mail_IMAPv2_LITERAL_DECODE, same as Mail_IMAPv2_LITERAL, except message decoding is attempted from base64 or quoted-printable encoding, returns undecoded string if decoding failed.
string   $getPart     (optional) one of text/plain or text/html, allows the specification of the default part to return from multipart messages, text/html by default.
int   $attempt     (optional) used internally by getBody to track attempts at finding the right part to display for the body of the message.
   $get_mime     

[ Top ]

getHeaders   [line 1472]

Array|BOOL getHeaders( int &$mid, [ $pid = '0'], [bool $rtn = false], [array $args = array()], string &$pid)

Set member variable containing header information. Creates an array containing associative indices referring to various header information. Use http://www.php.net/var_dump or http://www.php.net/print_r on the $header member variable to view information gathered by this function.

If $ret is true, returns array containing header information on success and false on failure.

If $ret is false, adds the header information to the $header member variable and returns BOOL.

  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/getHeaders
  • See: imap_headerinfo
  • See: imap_rfc822_parse_headers
  • See: imap_fetchbody
  • See: imap_fetchheader
  • See: Mail_IMAPv2::getParts()
  • Access: public

Parameters:

int   &$mid     message id
string   &$pid     (optional) part id to retrieve headers for.
bool   $rtn     (optional) If true return the headers, if false, assign to $header member variable.
array   $args     

(optional) Associative array containing extra arguments.

$args['from_length'] int From field length for imap_headerinfo.

$args['subject_length'] int Subject field length for imap_headerinfo

$args['default_host'] string Default host for imap_headerinfo & imap_rfc822_parse_headers

   $pid     

[ Top ]

getMailboxes   [line 2007]

array|false getMailboxes( [string $host = null], [ $pattern = '*'], [ $rtn = true])

Wrapper method for imap_list. Calling on this function will return a list of mailboxes.

This method receives the host argument automatically via $this->connect in the $this->mailboxInfo['host'] variable if a connection URI is used.

  • Return: list of mailboxes on the current server.
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/getMailboxes
  • See: imap_list
  • Access: public

Parameters:

string   $host     (optional) host name.
   $pattern     
   $rtn     

[ Top ]

getMailboxInfo   [line 395]

void getMailboxInfo( [ $ret = true])


Parameters:

   $ret     

[ Top ]

getParts   [line 689]

BOOL|Array getParts( int &$mid, [ $pid = '0'], [bool $ret = false], [string $args = array()], int &$pid)

sets up member variables containing inline parts and attachments for a specific

part in member variable arrays beginning with 'in' and 'attach'. If inline parts are present, sets $inPid, $inFtype, $inFsize, $inHasAttach, $inInlineId (if an inline CID is specified). If attachments are present, sets, $attachPid, $attachFsize, $attachHasAttach, $attachFname (if a filename is present, empty string otherwise).

  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/getParts
  • Since: PHP 4.2.0
  • Access: public

Parameters:

int   &$mid     message id
int   &$pid     part id
bool   $ret     false by default, if true returns the contents of the $in* and $attach* arrays. If false method returns BOOL.
string   $args     

(optional) Associative array containing optional extra arguments. The following are the possible indices.

$args['get_mime'] STRING Values: text/plain|text/html, text/html by default. The MIME type for the part to be displayed by default for each level of nesting.

$agrs['get_alternative'] BOOL If true, includes the alternative part of a multipart/alternative message in the $in* array. If veiwing text/html part by default this places the text/plain part in the $in* (inline attachment array).

$args['retrieve_all'] BOOL If true, gets all the message parts at once, this option will index the entire message in the $in* and $attach* member variables regardless of nesting (method indexes parts relevant to the current level of nesting by default).

   $pid     

[ Top ]

getQuota   [line 1876]

array|false getQuota( [string $folder = null], [BOOL $rtn = true])

Retreives information about the current mailbox's quota. Rounds up quota sizes and appends the unit of measurment. Returns information in a multi-dimensional associative array.
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/getQuota
  • See: imap_get_quotaroot
  • Access: public

Parameters:

string   $folder     Folder to retrieve quota for.
BOOL   $rtn     (optional) true by default, if true return the quota if false merge quota information into the $mailboxInfo member variable.

[ Top ]

getRawHeaders   [line 1397]

string|false getRawHeaders( int &$mid, [string $pid = '0'], [bool $rtn = true], [ $pid_check = false])

Set member variable $rawHeaders to contain Raw Header information for a part. Returns default header part id on success, returns false on failure.
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/getRawHeaders
  • See: imap_fetchbody
  • See: Mail_IMAPv2::getHeaders()
  • Access: public

Parameters:

int   &$mid     message_id
string   $pid     (optional) part id to retrieve headers for
bool   $rtn     Decides what to return. One of true|false|return_pid If true return the raw headers (returns the headers by default)
   $pid_check     

[ Top ]

getRawMessage   [line 1033]

string|null getRawMessage( int &$mid)

Returns entire unparsed message body. See imap_body for options.
  • Tutorial: http://www.smilingsouls.net/index.php?content=Mail_IMAPv2/getRawMessage
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/getRawMessage
  • See: imap_body
  • Access: public

Parameters:

int   &$mid     message id

[ Top ]

getRelatedParts   [line 908]

array|false getRelatedParts( int &$mid, string &$pid, [array $secureMIME = array()])

Looks to see if this part has any inline parts associated with it.

It looks up the message tree for parts with CID entries and indexes those entries, whereas an algorithm may be ran to replace inline CIDs with a part viewer.

  • Return: On success returns an array of parts associated with the current message, including the cid of the part, the part id and the MIME type.
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/getRelatedParts
  • Access: public

Parameters:

int   &$mid     message id
string   &$pid     part id
array   $secureMIME     

array of acceptable CID MIME types.

The $secureMIME argument allows you to limit the types of files allowed in a multipart/related message, for instance, to prevent a browser from automatically initiating download of a part that could contain potentially malicious code.

Suggested MIME types: text/plain, text/html, text/css, image/jpeg, image/pjpeg, image/gif image/png, image/x-png, application/xml, application/xhtml+xml, text/xml

MIME types are not limited by default.


[ Top ]

messageCount   [line 479]

int messageCount( )

Wrapper method for imap_num_msg.
  • Return: mailbox message count
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/messageCount
  • See: imap_num_msg
  • Access: public

[ Top ]

setFlags   [line 1938]

BOOL setFlags( array $mids, array $flags, [int $action = 'set'], int $options)

Wrapper function for imap_setflag_full. Sets various message flags.

Accepts an array of message ids and an array of flags to be set.

The flags which you can set are "\\Seen", "\\Answered", "\\Flagged", "\\Deleted", and "\\Draft" (as defined by RFC2060).

Warning: POP3 mailboxes do not remember flag settings from connection to connection.

  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/setFlags
  • See: imap_clearflag_full
  • See: imap_setflag_full
  • Throws: Message IDs and Flags are to be supplied as arrays. Remedy: place message ids and flags in arrays.
  • Access: public

Parameters:

array   $mids     Array of message ids to set flags on.
array   $flags     Array of flags to set on messages.
int   $action     Flag operation toggle one of set|clear
int   $options     (optional) sets the forth argument of imap_setflag_full or {@imap_clearflag_full}.

[ Top ]

setOptions   [line 433]

PEAR_Error|true setOptions( array $options, string $constant)

Set the $option member variable, which is used to specify optional imap_* function arguments (labeled in the manual as flags or options e.g. FT_UID, OP_READONLY, etc).

Example:

  1.     $msg->setOptions(array('body''fetchbody''fetchheader')'FT_UID');

This results in imap_body, imap_fetchbody and imap_fetchheader being passed the FT_UID option in the flags/options argument where ever these are called on by Mail_IMAPv2.

Note: this method only sets optional imap_* arguments labeled as flags/options.

  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/setOptions
  • See: Mail_IMAPv2::$option
  • Access: public

Parameters:

array   $options     - function names to pass the arugument to
string   $constant     
  • constant name to pass.

[ Top ]

unsetHeaders   [line 1679]

void unsetHeaders( int &$mid)

Destroys variables set by getHeaders.
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/unsetHeaders
  • See: Mail_IMAPv2::getHeaders()
  • Access: public

Parameters:

int   &$mid     message id

[ Top ]

unsetParts   [line 995]

void unsetParts( integer &$mid)

Destroys variables set by getParts and _declareParts.
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/unsetParts
  • See: Mail_IMAPv2::getParts()
  • Access: public

Parameters:

integer   &$mid     message id

[ Top ]

_checkIfParsed   [line 638]

void _checkIfParsed( int &$mid, [bool $checkPid = true], [ $get_mime = 'text/html'])

Checks if the part has been parsed, if not calls on _declareParts to parse the message.
  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/_checkIfParsed
  • Access: protected

Parameters:

int   &$mid     message id
bool   $checkPid     
   $get_mime     

[ Top ]

_declareParts   [line 503]

mixed _declareParts( int &$mid, [array $sub_part = null], [string $sub_pid = null], [int $n = 0], [bool $is_sub_part = false], [bool $skip_part = false], [ $last_was_signed = false])

Gather message information returned by imap_fetchstructure and recursively iterate

through each parts array. Concatenate part numbers in the following format `1.1` each part id is separated by a period, each referring to a part or subpart of a multipart message. Create part numbers as such that they are compatible with imap_fetchbody.

  • Tutorial: http://www.smilingsouls.net/Mail_IMAP?content=Mail_IMAP/_declareParts
  • See: imap_fetchbody
  • See: imap_fetchstructure
  • Access: protected

Parameters:

int   &$mid     message id
array   $sub_part     recursive
string   $sub_pid     recursive parent part id
int   $n     recursive counter
bool   $is_sub_part     recursive
bool   $skip_part     recursive
   $last_was_signed     

[ Top ]


Documentation generated on Tue, 12 Oct 2010 13:30:05 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.