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

Class: Mail_IMAP

Source Location: /Mail_IMAP-1.1.0RC2/IMAP.php

Class Overview


<p>Mail_IMAP provides a simplified backend for working with the c-client (IMAP) extension.


Author(s):

Version:

  • 1.1.0

Copyright:

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

Variables

Methods


Inherited Variables

Inherited Methods


Class Details

[line 113]
<p>Mail_IMAP provides a simplified backend for working with the c-client (IMAP) extension.

It serves as an OO wrapper for commonly used c-client functions. It provides structure and header parsing as well as body retrieval.</p> <p>This package requires the c-client extension. To download the latest version of the c-client extension goto: http://www.php.net/imap.</p>

PEAR PREREQUISITES:

  • Net_URL (Required if you will be using a URI abstraction to connect.)
Known Bugs:
<p>Potential bugs may arise from the detection of certain multipart/* messages. Application parses and adjusts for anomalies in multipart/mixed, multipart/related and multipart/alternative messages. Bugs may arise from untested and unincluded multipart message types, multipart/parallel, multipart/report, multipart/signed and multipart/digest.</p> <p>Have been told about a float conversion when passing a pid like 2.10 to array_search, have not yet reproduced.</p> <p>CID handling is not tested or yet perfected, some bugs may rise up there.</p>

What to do when a message bombs on Mail_IMAP:

  1. File a bug report at http://pear.php.net/bugs
  2. Mail a copy of the message preserving the structure as you now see it e.g. don't send as an attachment of another message to demo@smilingsouls.net.
  3. Include "Mail_IMAP", the MIME type and a short summary of what's wrong in the subject line, for instance if bombing on a multipart/related message, include that MIME type, if you aren't sure what MIME type the message is, don't worry about it :). Altering the subject line is important, otherwise I may think the message is spam and delete it.

Having trouble finding the example files? Examples are located in the PEAR install directory under /docs/Mail_IMAP/examples

Extended documentation available at: http://www.spicypeanut.net

The following URL will *sometimes* have a more recent version of IMAP.php than PEAR: <p>http://www.spicypeanut.net/index.html?content=373 This is where I post my working copy of Mail_IMAP between releases, use at your own risk (any API changes made there may not make it into the official release).</p>



[ Top ]


Class Variables

$attachFname =

[line 297]

(str) Attachment original file name (if any, if not file name is empty string).
  • Access: public

Type:   array


[ Top ]

$attachFsize =

[line 290]

(int) Attachment file size in bytes.
  • Access: public

Type:   array


[ Top ]

$attachFtype =

[line 283]

(str) Attachment MIME type.
  • Access: public

Type:   array


[ Top ]

$attachHasAttach =

[line 304]

(bool) Attachment has attachments?
  • Access: public

Type:   array


[ Top ]

$attachPid =

[line 276]

(str) Attachment part id.
  • Access: public

Type:   array


[ Top ]

$defaultPid =

[line 225]

(str) contains the default PID.
  • Access: public

Type:   array


[ Top ]

$header =

[line 320]

(array)(mixed) Associative array containing information gathered by imap_headerinfo or imap_rfc822_parse_headers.
  • Var: array $header

Type:   header


[ Top ]

$inFname =

[line 254]

(int) Inline file name of the part, if any.
  • Access: public

Type:   array


[ Top ]

$inFsize =

[line 247]

(int) Inline file size of the part in bytes.
  • Access: public

Type:   array


[ Top ]

$inFtype =

[line 240]

(str) Inline part MIME type.
  • Access: public

Type:   array


[ Top ]

$inHasAttach =

[line 261]

(bool) Inline part has attachments?
  • Access: public

Type:   array


[ Top ]

$inInlineId =

[line 268]

(str) Inline CID for multipart/related.
  • Access: public

Type:   array


[ Top ]

$inPid =

[line 233]

(str) Inline part id.
  • Access: public

Type:   array


[ Top ]

$mailbox =

[line 121]

Contains the imap resource stream.
  • Access: public

Type:   resource


[ Top ]

$mailboxInfo =

[line 128]

Contains information about the current mailbox.
  • Access: public

Type:   array


[ Top ]

$option =

[line 140]

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: Mail_IMAP::setOptions for more information.

  • Access: public

Type:   array


[ Top ]

$rawHeaders =

[line 313]

(str) Contains raw message headers fetched from imap_fetchbody or imap_fetchheader depending on which message part is being retrieved.
  • Access: public

Type:   array


[ Top ]



Method Detail

Mail_IMAP (Constructor)   [line 343]

BOOL|NULL|PEAR_Error Mail_IMAP( [mixed $connection = NULL], [int $options = NULL], [mixed $error_reporting = E_ALL], string $connect, int $error_reporting )

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.


Parameters:

string   $connect     (optional) server URL to connect to
int   $options     (optional) options see imap_open (DEPRECATED, use $this->option['open'] instead)
int   $error_reporting      (optional), one of E_ALL or 0, tells Mail_IMAP to report more about the messages it is parsing and where hacks are being used, such as fallback PIDs. This level of error reporting can become annoying, to turn it off, set to 0.

[ Top ]

alerts   [line 1666]

string|FALSE alerts( [string $seperator = "
\n"])

Wrapper function for imap_alerts. Implodes the array returned by imap_alerts, (if any) and returns the text.

Parameters:

string   $seperator     Characters to seperate each alert message. '
\n' by default.

[ Top ]

close   [line 552]

PEAR_Error|TRUE close( [int $options = NULL])

Wrapper method for imap_close. Close the IMAP resource stream.
  • See: imap_close
  • Access: public

Parameters:

int   $options     (optional) sets the second argument of imap_close (DEPRECATED, use $this->option['close'] instead)

[ Top ]

connect   [line 422]

PEAR_Error|TRUE connect( string $connect, [int $options = NULL])

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.

Examples of a well-formed connection argument:

For IMAP: imap://user:pass@mail.example.com:143/INBOX

For IMAP SSL: imaps://user:pass@example.com:993/INBOX

For POP3: pop3://user:pass@mail.example.com:110/INBOX

For POP3 SSL: pop3s://user:pass@mail.example.com:993/INBOX

For NNTP: nntp://user:pass@mail.example.com:119/comp.test

For 'notls' OR 'novalidate-cert' append to the URL as an anchor. For 'tls' use secure protocol and add the 'tls' option to the anchor.

Examples:

For notls: imap://user:pass@mail.example.com:143/INBOX#notls

For tls: imaps://user:pass@mail.example.com:143/INBOX#tls

tls no-validate: imaps://user:pass@mail.example.com:143/INBOX#tls/novalidate-cert

ssl no-validate: imaps://user:pass@mail.example.com:143/INBOX#novalidate-cert

If the username is an email address or contains invalid URL characters, urlencode the username portion of the string before passing it.

Use the IMAP.connection_wizard_example.php file to automatically detect the correct URI to pass to this function. This file is located in the examples directory.


Parameters:

string   $connect     server URL
int   $options     (optional) options (DEPRECATED, use $this->option['open'] instead) As of Mail_IMAP 1.1.0 the $options argument accepts an action for retrieving various mailbox information. If set to MAIL_IMAP_GET_INFO (the default action) Mail_IMAP::connect will make a call to getMailboxInfo. If set to MAIL_IMAP_NO_INFO this call will not be made. In the upcoming Mail_IMAP 2.0.0 release the $options argument will be no longer specify optional flags for imap_open and will server exclusively as an action toggle for getMailboxInfo.

[ Top ]

convertBytes   [line 1584]

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.

  • Static: This method can be called statically
  • Access: public

Parameters:

int   $bytes     

[ Top ]

debug   [line 1776]

void debug( [int $mid = 0])

Dumps various information about a message for debugging. Mail_IMAP::debug is called automatically from Mail_IMAP::connect if $_GET['dump_mid'] isset and MAIL_IMAP_ERROR_REPORTING == E_ALL || MAIL_IMAP_E_DEBUG.

$_GET['dump_pid'] - var_dump the $this->_pid[$mid] variable. $_GET['dump_structure'] - var_dump the structure returned by imap_fetchstructure. $_GET['test_pid'] - output the body returned by imap_fetchbody.

Calling on the debugger exits script execution after debugging operations have been completed.

  • Access: public

Parameters:

int   $mid     $mid to debug

[ Top ]

delete   [line 1607]

TRUE|PEAR_Error delete( int &$mid, [mixed $separator = "
\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.

Parameters:

int   &$mid     message id

[ Top ]

dump   [line 1815]

void dump( mixed &$thing)

Calls on var_dump and outputs with HTML
  • Access: public

Parameters:

mixed   $thing     $thing to dump.

[ Top ]

errors   [line 1648]

string|FALSE errors( [string $seperator = "
\n"])

Wrapper function for imap_errors. Implodes the array returned by imap_errors, (if any) and returns the error text.

Parameters:

string   $seperator     Characters to seperate each error message. '
\n' by default.

[ Top ]

expunge   [line 1631]

TRUE|PEAR_Error expunge( )

Wrapper function for imap_expunge. Expunges messages marked for deletion.

[ Top ]

extractMIME   [line 1305]

array|FALSE extractMIME( int &$mid, string|array $MIME)

Searches all message parts for the specified MIME type. Use getBody with $action option MAIL_IMAP_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.

  • Access: public

Parameters:

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

[ Top ]

getBody   [line 1124]

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

Searches parts array set in Mail_IMAP::_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.

  • Since: PHP 4.2.0
  • See: Mail_IMAP::getParts
  • See: imap_fetchbody
  • 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_IMAP_BODY (default), if part is message/rfc822 searches subparts for a displayable body and returns the body decoded as part of an array. MAIL_IMAP_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_IMAP_LITERAL_DECODE, same as MAIL_IMAP_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   $options      (optional) allows the specification of the forth argument of imap_fetchbody (DEPRECATED, use $this->option['fetchbody'] instead)

[ Top ]

getDefaultPid   [line 1224]

string getDefaultPid( int &$mid, [mixed $getPart = 'text/html'], [mixed $attempt = 1], string $getPart )

Searches structure defined in Mail_IMAP::_declareParts for the top-level default message.

Attempts to find a text/html default part, if no text/html part is found, automatically attempts to find a text/plain part. Returns the part id for the default top level message part on success. Returns FALSE on failure.

  • Access: public

Parameters:

int   &$mid     message id
string   $getPart      (optional) default MIME type to look for, one of text/html or text/plain text/html by default.

[ Top ]

getHeaders   [line 1393]

Array|BOOL getHeaders( int &$mid, [mixed $pid = '0'], [int $from_length = 1024], [int $subject_length = 1024], [string $default_host = NULL], [int $options = NULL], 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.

Returns header information on success and FALSE on failure.

  • See: imap_headerinfo
  • See: imap_rfc822_parse_headers
  • See: imap_fetchbody
  • See: imap_fetchheader
  • See: Mail_IMAP::getParts()
  • Access: public

Parameters:

int   &$mid     message id
string   &$pid     part id
int   $from_length     (optional) from length for imap_headerinfo
int   $subject_length     (optional) subject length for imap_headerinfo
string   $default_host     (optional) default host for imap_headerinfo & imap_rfc822_parse_headers
int   $options     (optional) flags/options for imap_fetchbody (DEPRECATED, use $this->option['fetchbody'])

[ Top ]

getMailboxes   [line 1834]

array getMailboxes( [string $host = NULL], [mixed $pattern = '*'])

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

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

  • Return: list of mailboxes on the current server.
  • See: imap_list
  • Access: public

Parameters:

string   $host     (optional) host name.

[ Top ]

getMailboxInfo   [line 493]

PEAR_Error|TRUE getMailboxInfo( [mixed $ret = TRUE], string $connect, bool $get_info )

Adds to the $mailboxInfo member variable information about the current mailbox from imap_mailboxmsginfo.

Note: This method is automatically called on by default by connect.

  • See: imap_open
  • Access: public

Parameters:

string   $connect     server URL
bool   $get_info      (optional) TRUE by default. If TRUE, make a call to getMailboxInfo if FALSE do not call getMailboxInfo

[ Top ]

getParts   [line 765]

bool getParts( int &$mid, int &$pid, [mixed $MIME = 'text/html'], [mixed $getAlternative = TRUE], [mixed $retrieve_all = FALSE], string $MIME , bool $getAlternative , bool $retrieve_all )

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

Typically the text/html part is displayed by default by a message viewer, this part is excluded from the inline member variable arrays thourgh $excludeMime by default. If $getInline is TRUE the text/plain alternative part will be returned in the inline array and may be included as an attachment. Useful for mail developement/debugging of multipart messages.

  • Since: PHP 4.2.0
  • Access: public

Parameters:

int   &$mid     message id
int   &$pid     part id
string   $MIME      (optional) values: text/plain|text/html, the part MIME type that will be retrieved by default.
bool   $getAlternative      (optional) include the plain/text alternative part in the created inline parts array if $MIME is text/html, if $MIME is text/plain, include the text/html alternative part.
bool   $retrieve_all      (optional) Instead of just finding parts relative to this part, get *all* parts using this option *all* sub parts are included in the $in* and $attach* variables.

[ Top ]

getQuota   [line 1685]

array|PEAR_Error getQuota( [string $folder = NULL])

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.
  • See: imap_get_quotaroot
  • Access: public
  • Throws: Quota not available on this server. Remedy: none.

Parameters:

string   $folder     Folder to retrieve quota for.

[ Top ]

getRawHeaders   [line 1351]

string|FALSE getRawHeaders( int &$mid, [string $pid = '0'], [int $options = NULL], [bool $rtn = TRUE])

Set member variable $rawHeaders to contain Raw Header information for a part. Returns default header part id on success, returns FALSE on failure.

Parameters:

int   &$mid     message_id
string   $pid     part id
int   $options     flags/options for imap_fetchbody
bool   $rtn     return the raw headers (returns the headers by default)

[ Top ]

getRawMessage   [line 1072]

void getRawMessage( int &$mid, [int $options = NULL])

Returns entire unparsed message body. See imap_body for options.
  • See: imap_body
  • Access: public

Parameters:

int   &$mid     message id
int   $options     flags (DEPRECATED, use $this->option['body'] instead)

[ Top ]

messageCount   [line 570]

int messageCount( )

Wrapper method for imap_num_msg.
  • Return: mailbox message count
  • See: imap_num_msg
  • Access: public

[ Top ]

setFlags   [line 1735]

BOOL|PEAR_Error setFlags( array $mids, array $flags, [int $action = 3], [mixed $options = NULL], 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.

  • See: imap_clearflag_full
  • See: imap_setflag_full
  • Access: public
  • Throws: Message IDs and Flags are to be supplied as arrays. Remedy: place message ids and flags in arrays.

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 MAIL_IMAP_SET_FLAGS (default) or MAIL_IMAP_CLEAR_FLAGS.
int   $options      (optional) sets the forth argument of imap_setflag_full or {@imap_clearflag_full}.

[ Top ]

setOptions   [line 527]

PEAR_Error|TRUE setOptions( array $option_set, 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: $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_IMAP.

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


Parameters:

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

[ Top ]

unsetHeaders   [line 1564]

void unsetHeaders( int &$mid)

Destroys variables set by getHeaders.

Parameters:

int   &$mid     message id

[ Top ]

unsetParts   [line 977]

void unsetParts( integer &$mid)

Destroys variables set by getParts and _declareParts.

Parameters:

integer   &$mid     message id

[ Top ]


Documentation generated on Tue, 29 Jun 2004 02:10:06 -0400 by phpDocumentor 1.2.3. PEAR Logo Copyright © PHP Group 2004.