Tutorial

Tutorial -- A tutorial for Mail_Queue

Mail_Queue usage with a simple example

We are using the db-container for the example and a mysql database. You need to create some tables in the mysql-database to store the messages:

mysql.sql


CREATE TABLE mail_queue (
  id bigint(20) NOT NULL default '0',
  create_time datetime NOT NULL default '0000-00-00 00:00:00',
  time_to_send datetime NOT NULL default '0000-00-00 00:00:00',
  sent_time datetime default NULL,
  id_user bigint(20) NOT NULL default '0',
  ip varchar(20) NOT NULL default 'unknown',
  sender varchar(50) NOT NULL default '',
  recipient text NOT NULL,
  headers text NOT NULL,
  body longtext NOT NULL,
  try_sent tinyint(4) NOT NULL default '0',
  delete_after_send tinyint(1) NOT NULL default '1',
  PRIMARY KEY  (id),
  KEY id (id),
  KEY time_to_send (time_to_send),
  KEY id_user (id_user)
);

First you need to define some options. As you need them two times (once for adding messages, once for sending the messages) its always good to add them to a config-file. Lets call it config.php

config.php


<?php

require_once "Mail/Queue.php";

// options for storing the messages
// type is the container used, currently there are 'creole', 'db', 'mdb' and 'mdb2' available
$db_options['type']       = 'mdb2';
// the others are the options for the used container
// here are some for db
$db_options['dsn']        = 'mysql://user:password@host/database';
$db_options['mail_table'] = 'mail_queue';

// here are the options for sending the messages themselves
// these are the options needed for the Mail-Class, especially used for Mail::factory()
$mail_options['driver']    = 'smtp';
$mail_options['host']      = 'your_server_smtp.com';
$mail_options['port']      = 25;
$mail_options['localhost'] = 'localhost'; //optional Mail_smtp parameter
$mail_options['auth']      = false;
$mail_options['username']  = '';
$mail_options['password']  = '';

?>

So we are done configuring it, now let's use it. First we need to construct a mail-message and add it to the queue:

add_message.php


<?php
include './config.php';
/* we use the db_options and mail_options here */
$mail_queue =& new Mail_Queue($db_options, $mail_options);


$from = 'user@server.com';
$to = "user2@server.com";
$message = 'Hi! This is test message!! :)';

$hdrs = array( 'From'    => $from,
               'To'      => $to,
               'Subject' => "test message body"  );

/* we use Mail_mime() to construct a valid mail */
$mime =& new Mail_mime();
$mime->setTXTBody($message);
$body = $mime->get();
$hdrs = $mime->headers($hdrs);


/* Put message to queue */
$mail_queue->put( $from, $to, $hdrs, $body );

?>

Ok, now we've used the simple way to add a message ... there are more advanced options, please check docs of the put-function for these. Now we need to send the messages. This is most often done by using a cron-job which regularly runs a script to send the messages. Here is a simple script to achieve this:

send_messages.php


<?php
include './config.php';

/* How many mails could we send each time the script is called */
$max_amount_mails = 50;

/* we use the db_options and mail_options from the config again  */
$mail_queue =& new Mail_Queue($db_options, $mail_options);

/* really sending the messages */
$mail_queue->sendMailsInQueue($max_amount_mails);
?>

We are done. Now run the last script regularly and add your mails to the queue as needed.

Since Mail_Queue v.1.1, the preload() method doesn't preload ALL the mails in memory, but just a few of them each time. When the buffer is empty, it is filled again automatically. You can set the size of the buffer via the new setBufferSize() method.

You can also send the stored emails one by one. Here is a simple script to achieve this:

send_messages_one_by_one.php


<?php
// set the internal buffer size according your
// memory resources (the number indicates how
// many emails can stay in the buffer at any
// given time)

$mail_queue->setBufferSize(20);

//set the queue size (i.e. the number of mails to send)
$limit = 50;
$mail_queue->container->setOption($limit);

// loop through the stored emails and send them
while ($mail = $mail_queue->get()) {
    $result = $mail_queue->sendMail($mail);
}
?>


Class Summary Mail_Queue	constructor Mail_Queue::Mail_Queue

Mail_Queue

PEAR Manual


Class Summary Mail_Queue	constructor Mail_Queue::Mail_Queue

Mail_Queue

PEAR Manual