Home » Mail » Mail_Mbox » Manual

Class Summary Mail_Mbox

Class Summary Mail_Mbox – Class to read mbox mail files.

Reading and writing mbox files.

An mbox mail file is contains plain emails concatenated in one big file. Since each mail starts with "From ", and ends with a newline, they can be separated from each other.

This class takes a mbox filename in the constructor, generates an index where the mails start and end when calling open() and returns single mails with get(), using the positions in the index.

With the help of this class, you also can insert(), remove() and update() messages in the mbox file. When calling one of this methods, the class checks if the file has been modified since the index was created - changing the file with the wrong positions in the index would very likely corrupt it. This check is not done when retrieving single messages via get(), as this would slow down the process if you retrieve thousands of mails. You can, however, call hasBeenModified() before using get() to check for modification yourself. If the method returns true, you should close() and re-open() the file.

If something strange happens and you don't know why, activate debugging with setDebug(true). You also can modify the temporary directory in which changed mboxes are stored when adding/removing/modifying by using setTmpDir('/path/')

Class Tree for Mail_Mbox

• PEAR
  • Mail_Mbox

Tutorial

Tutorial – How to use Mail_Mbox

How to use Mail_Mbox

Before you can do anything with the mbox file, you need to create an instance of the Mail_Mbox class and open() it.

<?php
require_once 'Mail/Mbox.php';
$mbox = new Mail_Mbox('/path/to/mbox');
$mbox->open();
//do more here
?>

After opening the file, you can retrieve single messages via get(). The size() method helps you to determine the number of messages:

<?php
//... initialisation
for ($n = 0; $n < $mbox->size(); $n++) {
    $message = $mbox->get($n);
    //do something with the message text
}
?>

If you're done working with the file, close() it.

<?php
//... other code
$mbox->close();
?>

Also have a look at the Mail_Mbox examples directory in /path/to/pear/docs/Mail_Mbox/examples/.

constructor Mail_Mbox::Mail_Mbox

constructor Mail_Mbox::Mail_Mbox() – Create a new Mbox class instance.

Synopsis

void constructor Mail_Mbox::Mail_Mbox ( string $file )

Description

After creating a new instance, you should use open() to open an mbox file.

Parameter

string $file

Filename to open.

Mail_Mbox::close

Mail_Mbox::close() – Close a Mbox

Synopsis

mixed Mail_Mbox::close ( )

Description

Close the Mbox file opened by open().

Return value

returns true on success, else PEAR_Error

Mail_Mbox::get

Mail_Mbox::get() – Get a message from the mbox

Synopsis

string Mail_Mbox::get ( int $message )

Description

Returns the full email message at the given position.

Note: Message number start from 0.

Parameter

integer $message

The number of the message to retrieve.

Return value

returns Return the message, or PEAR_Error on error.

Mail_Mbox::getDebug

Mail_Mbox::getDebug() – Returns the debug flag setting

Synopsis

boolean Mail_Mbox::getDebug ( )

Description

Returns true if debugging is enabled.

Return value

returns true if debug is enabled.

Mail_Mbox::getTmpDir

Mail_Mbox::getTmpDir() – Returns the temporary directory

Synopsis

string Mail_Mbox::getTmpDir ( )

Description

Returns the temporary directory.

Return value

returns The temporary directory.

Mail_Mbox::hasBeenModified

Mail_Mbox::hasBeenModified() – Checks if the file was modified since it has been loaded.

Synopsis

boolean Mail_Mbox::hasBeenModified ( )

Description

Checks if the mbox file has been modified since opening. If this is true, the file needs to be re-opened.

Return value

returns True if it has been modified.

Mail_Mbox::insert

Mail_Mbox::insert() – Insert a message

Synopsis

mixed Mail_Mbox::insert ( string $content , mixed $offset = null )

Description

Mail_Mbox will insert the message according to the specified offset. (Remember: message 3 is the fourth message). The default is to insert the message AFTER the last message (offset = null).

Note: Mail_Mbox automatically adds \n\n at end of the message.

Parameter

string $content

The content of the new message.

mixed $offset

Return value

returns Return true or the PEAR_Error object on failure.

Mail_Mbox::open

Mail_Mbox::open() – Open the mbox file

Synopsis

void Mail_Mbox::open ( )

Description

Also, this function will process the mbox file and create a cache that tells each message start and end bytes.

Mail_Mbox::remove

Mail_Mbox::remove() – Remove a message from Mbox and save it.

Synopsis

mixed Mail_Mbox::remove ( int $message )

Description

Removes the message with the given id.

Note: messages start with 0.

Parameter

integer $message

The number of the message to remove, or array of message ids to remove.

Return value

returns Return true or PEAR_Error object on failure.

Mail_Mbox::setDebug

Mail_Mbox::setDebug() – Set the debug flag

Synopsis

void Mail_Mbox::setDebug ( boolean $debug )

Description

Sets the debug flag. If debugging is enabled, you will get more output.

Parameter

boolean $debug

True if debug is on, otherwise false.

See

see Mail_Mbox::$debug

Mail_Mbox::setTmpDir

Mail_Mbox::setTmpDir() – Set the directory for temporary files.

Synopsis

void Mail_Mbox::setTmpDir ( string $tmpdir )

Description

Sets the temporary directory in which new mbox files are stored.

Parameter

string $tmpdir

The new temporary directory.

See

see Mail_Mbox::$tmpdir

Mail_Mbox::size

Mail_Mbox::size() – Get number of messages in this mbox

Synopsis

int Mail_Mbox::size ( )

Description

Returns the number of messages in the mbox file.

Return value

returns Number of messages on Mbox (starting on 1, 0 if no message exists).

Mail_Mbox::update

Mail_Mbox::update() – Update a message

Synopsis

mixed Mail_Mbox::update ( int $message , string $content )

Description

Replaces a given message with the text passed to this method.

Mail_Mbox auto adds \n\n at end of the message

messages start with 0.

Parameter

integer $message

The number of the Message to update.

string $content

The new content of the Message.

Return value

returns Return true if all is ok, otherwise PEAR_Error

Mail_Mbox::_move

Mail_Mbox::_move() – Copy a file to another

Synopsis

void Mail_Mbox::_move ( string $ftempname , string $filename )

Description

Used internally to copy the content of the temp file to the mbox file.

Parameter

string $ftempname

Source file - will be removed

string $filename

Output file

Mail_Mbox::_process

Mail_Mbox::_process() – Process the Mbox

Synopsis

void Mail_Mbox::_process ( )

Description

• Get start bytes and end bytes of each messages.