Mail_Mbox
[ class tree: Mail_Mbox ] [ index: Mail_Mbox ] [ all elements ]
Packages:
Mail_Mbox


Classes:
Mail_Mbox
Files:
Mbox.php
mimedecode.php
modify.php
read.php

Class: Mail_Mbox

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

Class Overview

PEAR
   |
   --Mail_Mbox

Class to read mbox mail files.


Author(s):

Variables

Methods

Inherited Variables

Inherited Methods

Class Details

[line 118]
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/');

See @link tags for specifications.



[ Top ]

Class Variables

$autoReopen =  true

[line 181]

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

Debug mode

Set to true to turn on debug mode.


Type:   bool


[ Top ]

$tmpdir =  '/tmp'

[line 170]

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.


Type:   string


[ Top ]

$_index =  null

[line 136]

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

Timestamp at which the file has been modified last.
  • Access: protected

Type:   int


[ Top ]

$_resource =  null

[line 126]

File resource / handle
  • Access: protected

Type:   resource


[ Top ]


Method Detail

Mail_Mbox (Constructor)   [line 193]

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

mixed append( string $content)

Appends a message at the end of the file.

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

  • Return: Return true else PEAR_Error object
  • Access: public

Parameters:

string   $content   —   The content of the new message

[ Top ]

close   [line 296]

mixed close( )

Close a Mbox

Close the Mbox file opened by open()

  • Return: true on success, else PEAR_Error
  • Access: public

[ Top ]

get   [line 341]

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

bool getAutoReopen( )

Returns the automatically reopening setting

[ Top ]

getDebug   [line 871]

bool getDebug( )

Returns the debug flag setting

[ Top ]

getTmpDir   [line 846]

string getTmpDir( )

Returns the temporary directory
  • Return: The temporary directory

[ Top ]

hasBeenModified   [line 805]

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

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

Insert a message

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

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

  • 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 207]

boolean|PEAR_Error open( [ $create = false])

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

Parameters:

   $create   —   

[ Top ]

remove   [line 399]

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

void setAutoReopen( bool $autoReopen)

Sets if the mbox is reloaded after modification automatically.

Parameters:

bool   $autoReopen   —   If the mbox is reloaded automatically

[ Top ]

setDebug   [line 859]

void setDebug( bool $debug)

Set the debug flag

Parameters:

bool   $debug   —   If debug is on or off

[ Top ]

setTmpDir   [line 828]

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

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

mixed update( int $message, string $content)

Update a 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 ]

_create   [line 250]

boolean _create( )

Creates the file
  • Return: True if it was created, false if it already existed. PEAR_Error in case it could not be created.
  • Access: protected

[ Top ]

_escapeMessage   [line 764]

string _escapeMessage( string $message)

Quotes "From " lines in the midst of the message.

And quoted "From " lines, too :) Also appends the trailing newline. After escaping, the message can be written to file.


Parameters:

string   $message   —   Message content

[ Top ]

_move   [line 672]

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

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

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 ]

_unescapeMessage   [line 788]

string _unescapeMessage( string $message)

Removes quoted "From " lines from the message

Parameters:

string   $message   —   Message content

[ Top ]
Documentation generated on Wed, 11 Nov 2009 08:00:02 +0000 by phpDocumentor 1.4.2. PEAR Logo Copyright © PHP Group 2004.