Class: Mail_Mbox

Source Location: /Mail_Mbox-0.5.2/Mail/Mbox.php

Class Overview

PEAR
   |
   --Mail_Mbox

Class to read mbox mail files.

Author(s):

Christian Weiske <cweiske at php.net>
Roberto Berto <darkelder at php.net>

Inherited Variables

Inherited Methods

Class Details

[line 114]
Class to read mbox mail 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 add(), 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/');

Author: Christian Weiske <cweiske@php.net>
Author: Roberto Berto <darkelder@php.net>
Link: http://pear.php.net/package/Mail_Mbox
License: LGPL License 2.1

[ Top ]

Class Variables

$autoReopen = true

[line 177]

Determines if the file is automatically re-opened and its structure is parsed after modifying it. Setting this to false makes you responsible for calling open() by hand, but is *a lot* faster when appending many messages.

Access: public

Type:

bool

[ Top ]

$debug = false

[line 152]

Debug mode

Set to true to turn on debug mode.

See: Mail_Mbox::getDebug()
See: Mail_Mbox::setDebug()
Access: public

Type:

bool

[ Top ]

$tmpdir = '/tmp'

[line 166]

Directory in which the temporary mbox files are created.

Even if it's a unix directory, it does work on windows as the only function it's used in is tempnam which automatically chooses the right temp directory if this here doesn't exist. So this variable is for special needs only.

See: Mail_Mbox::setTmpDir()
See: Mail_Mbox::getTmpDir()
Access: public

Type:

string

[ Top ]

$_index = null

[line 132]

Message index. Each mail has its own subarray, which contains the start position and end position as first and second subindex.

Access: protected

Type:

array

[ Top ]

$_lastModified = null

[line 140]

Timestamp at which the file has been modified last.

Access: protected

Type:

int

[ Top ]

$_resource = null

[line 122]

File resource / handle

Access: protected

Type:

resource

[ Top ]

Method Detail

Mail_Mbox (Constructor) [line 189]

Mail_Mbox Mail_Mbox(
string
$file)

Create a new Mbox class instance.

After creating it, you should use open().

Access: public

Parameters:

string $file — Filename to open.

[ Top ]

append [line 568]

mixed append(
string
$content)

Appends a message at the end of the file.

This method is also used by insert() since it's faster.

Note: PEAR::Mail_Mbox auto adds \n\n at end of the message

Return: Return true else PEAR_Error object
Access: public

Parameters:

string $content — The content of the new message

[ Top ]

close [line 255]

mixed close(
)

Close a Mbox

Close the Mbox file opened by open()

Return: true on success, else PEAR_Error
Access: public

[ Top ]

get [line 300]

string get(
int
$message)

Get a message from the mbox

Note: Message numbers start from 0.

Return: Return the message, PEAR_Error on error
Access: public

Parameters:

int $message — The number of the message to retrieve

[ Top ]

getAutoReopen [line 807]

bool getAutoReopen(
)

Returns the automatically reopening setting

Return: If the mbox is reloaded automatically.
See: Mail_Mbox::$autoReopen

[ Top ]

getDebug [line 781]

bool getDebug(
)

Returns the debug flag setting

Return: If debug is enabled.
See: Mail_Mbox::$debug

[ Top ]

getTmpDir [line 756]

string getTmpDir(
)

Returns the temporary directory

Return: The temporary directory

[ Top ]

hasBeenModified [line 715]

bool hasBeenModified(
)

Checks if the file was modified since it has been loaded.

If this is true, the file needs to be re-opened.

Return: True if it has been modified.
Access: public

[ Top ]

insert [line 496]

mixed insert(
string
$content, [int
$offset = null])

Insert a message

PEAR::Mail_Mbox will insert the message according its offset.

means before the actual message 0. 3 means before the message 3

(Remember: message 3 is the fourth message). The default is put AFTER the last message (offset = null).

Note: PEAR::Mail_Mbox auto adds \n\n at end of the message

Return: Return true else PEAR_Error object
Access: public

Parameters:

string	`$content`	—	The content of the new message
int	`$offset`	—	Before the offset. Default: last message (null)

[ Top ]

open [line 203]

boolean|PEAR_Error open(
)

Open the mbox file

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

Return: True if all went ok, PEAR_Error on failure
Access: public

[ Top ]

remove [line 353]

mixed remove(
int
$message)

Remove a message from Mbox and save it.

Note: messages start with 0.

Return: Return true else PEAR_Error
Access: public

Parameters:

int $message — The number of the message to remove, or array of message ids to remove

[ Top ]

setAutoReopen [line 795]

void setAutoReopen(
bool
$autoReopen)

Sets if the mbox is reloaded after modification automatically.

See: Mail_Mbox::$autoReopen

Parameters:

bool $autoReopen — If the mbox is reloaded automatically

[ Top ]

setDebug [line 769]

void setDebug(
bool
$debug)

Set the debug flag

See: Mail_Mbox::$debug

Parameters:

bool $debug — If debug is on or off

[ Top ]

setTmpDir [line 738]

mixed setTmpDir(
string
$tmpdir)

Set the directory for temporary files.

Return: True if all is ok, PEAR_Error if $tmpdir is a dir but not writable
See: Mail_Mbox::$tmpdir

Parameters:

string $tmpdir — The new temporary directory

[ Top ]

size [line 281]

int size(
)

Get number of messages in this mbox

Return: Number of messages on Mbox (starting on 1,
1. if no message exists)
Access: public

[ Top ]

update [line 426]

mixed update(
int
$message, string
$content)

Update a message

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

Note: messages start with 0.

Return: Return true if all is ok, else PEAR_Error
Access: public

Parameters:

int	`$message`	—	The number of Message to update
string	`$content`	—	The new content of the Message

[ Top ]

_move [line 629]

boolean|PEAR_Error _move(
string
$ftempname, string
$filename)

Move a file to another.

Used internally to move the content of the temp file to the mbox file. Note that we can't use rename() internally, as it behaves very, very strange on windows.

Return: True if everything went fine, PEAR_Error when an error happened.
Access: protected

Parameters:

string	`$ftempname`	—	Source file - will be removed
string	`$filename`	—	Output file

[ Top ]

_process [line 653]

boolean|PEAR_Error _process(
)

Process the Mbox

Put start bytes and end bytes of each message into _index array

Return: True if all went ok, PEAR_Error on failure
Access: protected

[ Top ]

_reopen [line 239]

mixed _reopen(
)

Re-opens the file and parses the messages again.

Used by other methods to be able to be able to prevent re-opening the file.

Return: See open() for return values. Returns true if $this->autoReopen is false.
Access: protected

[ Top ]