Class: Mail_Mbox

Source Location: /Mail_Mbox-0.5.1/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>

Version:

CVS: $Id: Mbox.php,v 1.6 2006/06/26 06:29:08 cweiske Exp $

Inherited Variables

Inherited Methods

Class Details

[line 106]
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>
Version: CVS: $Id: Mbox.php,v 1.6 2006/06/26 06:29:08 cweiske Exp $
License: LGPL

[ Top ]

Class Variables

$autoReopen = true

[line 169]

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

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

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

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

Timestamp at which the file has been modified last.

Access: protected

Type:

int

[ Top ]

$_resource = null

[line 114]

File resource / handle

Access: protected

Type:

resource

[ Top ]

Method Detail

Mail_Mbox (Constructor) [line 180]

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

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

mixed close(
)

Close a Mbox

Close the Mbox file opened by open()

Return: true on success, else PEAR_Error
Access: public

[ Top ]

get [line 288]

string get(
int
$message)

Get a message from the mbox

Note: Message number start from 0.

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

Parameters:

int $message — The number of Message

[ Top ]

getAutoReopen [line 738]

bool getAutoReopen(
)

Returns the automatically reopening setting

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

[ Top ]

getDebug [line 715]

bool getDebug(
)

Returns the debug flag setting

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

[ Top ]

getTmpDir [line 693]

string getTmpDir(
)

Returns the temporary directory

Return: The temporary directory

[ Top ]

hasBeenModified [line 655]

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

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 class
Access: public

Parameters:

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

[ Top ]

open [line 193]

void open(
)

Open the mbox file

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

Access: public

[ Top ]

remove [line 339]

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

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

void setDebug(
bool
$debug)

Set the debug flag

See: Mail_Mbox::$debug

Parameters:

bool $debug — If debug is on or off

[ Top ]

setTmpDir [line 675]

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

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

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 updated
string	`$content`	—	The new content of the Message

[ Top ]

_move [line 572]

void _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.

Access: protected

Parameters:

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

[ Top ]

_process [line 595]

void _process(
)

Process the Mbox

Get start bytes and end bytes of each messages

Access: protected

[ Top ]

_reopen [line 228]

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 ]