phpBB

Development Wiki

Sending e-mails

From phpBB Development Wiki

Basic Usage of Messenger Class

Here is a simple example how to send e-mails (or jabber messages, depending on what the user selected in his profile):

include_once($phpbb_root_path 'includes/functions_messenger.' $phpEx);
$messenger = new messenger();
$result /*your sql query here. you must include username, user_lang, user_email, user_jabber, user_notify_type*/
while ($row $db->sql_fetchrow($result))
{
    
$messenger->template('your_email_template'$row['user_lang']);
    
$messenger->to($row['user_email'], $row['username']);
    
$messenger->im($row['user_jabber'], $row['username']);
    
$messenger->assign_vars(array(
        
'FOO'    => $foo,
        
'BAR'    => $bar
    
));
    
$messenger->send($row['user_notify_type']);
}
$messenger->save_queue();

Setting Email Headers

Optional headers can be added to email messages using the messenger as well.

Examples:

/* Carbon Copy */
    
$messenger->cc($row['user_email'], $row['username']);
    
/* Blind Carbon Copy */
    
$messenger->bcc($row['user_jabber'], $row['username']);
    
/* From */
    
$messenger->from('webmeister@example.org''Potomac Tavern Webmeister');
    
/* Message Subject */
    
$messenger->subject('Hello World');
    
/* Arbitrary headers */
    
$messenger->headers('X-AntiAbuse: User IP - ' $user->ip);

Sending Immediately vs. Enqueueing

In the first example, the save_queue() method is required at the end of message preparation to save the contents of the message to the message delivery queue. [need to add why the queue is valuable]

If the messenger is constructed with an optional boolean parameter value of false, messages will not use the message queue (default behavior) and the save_queue() method can be omitted:

$messenger = new messenger(false);
$result /*your sql query here. as above */
while ($row $db->sql_fetchrow($result))
{
       
/* perform other message related operation, as above */
    
$messenger->send($row['user_notify_type']);
}

In this case when the send() method is invoked, the message is sent immediately.[1][2]

Sending messages by email only

In this example, the send() method is passing a hint to the messenger regarding the type of message to send in the first parameter, as the messenger can send message via either email or Jabber (XMMP).

The default invocation of the send() method with no parameters will send an email:
$messenger->send();

More Usage Examples

More examples of usage can be found in the phpbb code base. For example see the user_notification() function in includes/functions_posting.php.

This article is a stub. You can help in improving Olympus Documentation by expanding it.