svn: /pear/peardoc/trunk/en/package/mail/mail-queue/mail-queue/ sendmailsinqueue.xml tutorial.xml

kguest                                   Fri, 16 Apr 2010 22:54:36 +0000

Revision: http://svn.php.net/viewvc?view=revision&revision=298102

Log:
Doc Bug #17316 documentation re callbacks

Bug: http://pear.php.net/bugs/17316 (unknown) 
      
Changed paths:
    U   pear/peardoc/trunk/en/package/mail/mail-queue/mail-queue/sendmailsinqueue.xml
    U   pear/peardoc/trunk/en/package/mail/mail-queue/mail-queue/tutorial.xml

Modified: pear/peardoc/trunk/en/package/mail/mail-queue/mail-queue/sendmailsinqueue.xml
===================================================================
--- pear/peardoc/trunk/en/package/mail/mail-queue/mail-queue/sendmailsinqueue.xml	2010-04-16 22:44:13 UTC (rev 298101)
+++ pear/peardoc/trunk/en/package/mail/mail-queue/mail-queue/sendmailsinqueue.xml	2010-04-16 22:54:36 UTC (rev 298102)
@@ -14,6 +14,7 @@
       <paramdef choice="opt">integer <parameter> $limit = MAILQUEUE_ALL</parameter></paramdef>
       <paramdef choice="opt">integer <parameter> $offset = MAILQUEUE_START</parameter></paramdef>
       <paramdef choice="opt">integer <parameter> $try = MAILQUEUE_TRY</parameter></paramdef>
+      <paramdef choice="opt">string or array <parameter> $callback = null</parameter></paramdef>
      </funcprototype>
     </funcsynopsis>
     </refsynopsisdiv>
@@ -64,6 +65,19 @@
        </listitem>
       </varlistentry>
      </variablelist>
+     <variablelist>
+      <varlistentry>
+       <term>
+         &type.string;
+         <parameter>$callback</parameter>
+       </term>
+       <listitem>
+        <para>
+         Optional - details of callback function to be used after mail has been sent.
+        </para>
+       </listitem>
+      </varlistentry>
+     </variablelist>
     </para>
    </refsection>
    <refsection xml:id="package.mail.mail-queue.mail-queue.sendmailsinqueue.returns">

Modified: pear/peardoc/trunk/en/package/mail/mail-queue/mail-queue/tutorial.xml
===================================================================
--- pear/peardoc/trunk/en/package/mail/mail-queue/mail-queue/tutorial.xml	2010-04-16 22:44:13 UTC (rev 298101)
+++ pear/peardoc/trunk/en/package/mail/mail-queue/mail-queue/tutorial.xml	2010-04-16 22:54:36 UTC (rev 298102)
@@ -251,4 +251,62 @@
 </example>
 </refsection>

+<refsection xml:id="package.mail.mail-queue.mail-queue.tutorial.part13"><info><title>Utilising Callbacks for Report Generation</title></info>
+
+<para>
+The sendMailsInQueue method, since version 1.2.3, has callback support. This may be utilised for report generation and postprocessing.
+</para>
+<para>
+The callback function is called before the relevant entry is deleted from the mail_queue table in the database so if necessary you could add extra fields to it for inserting into your log/report table. The function should accept only one parameter - an associative array of values; 'id', 'queued_as' and 'greeting'.</para>
+<para>
+You'll need to use recent releases of the <link linkend="package.mail.mail"><classname>PEAR::Mail</classname></link> and <link linkend="package.networking.net-smtp"><classname>PEAR::Net_SMTP</classname></link> packages to be able to retrieve the esmtp id and greeting details if you need them for your reports. Also, if you want to decode the body of the email and store that for your report you'll need to install the <link linkend="package.mail.mail-mimedecode"><classname>PEAR::Mail_mimeDecode</classname></link> package.</para>
+<para>
+Provide the callback function like so:</para>
+  <programlisting role="php">
+<![CDATA[
+<?php
+$returned = $mail_queue->sendMailsInQueue(
+    MAILQUEUE_ALL,
+    MAILQUEUE_START,
+    MAILQUEUE_TRY,
+    'mailqueue_callback');
+
+function mailqueue_callback($args) {
+    $row = get_mail_queue_row($args['id']);
+    $headers = unserialize($row['headers']);
+    $subject = $headers['Subject'];
+    $body = unserialize($row['body']);
+
+    $mail_headers = '';
+    foreach($headers as $key=>$value) {
+        $mail_headers .= "$key:$value\n";
+    }
+    $mail = $mail_headers . "\n" . $body;
+    $decoder = new Mail_mimeDecode($mail);
+    $decoded = $decoder->decode(array(
+        'include_bodies' => TRUE,
+        'decode_bodies'  => TRUE,
+        'decode_headers'  => TRUE,
+    ));
+    $body = $decoded->body;
+
+    $esmtp_id = $args['queued_as'];
+    if (isset($args['greeting'])) {
+        $greeting = $args['greeting'];
+        $greets = explode(' ', $greeting);
+        $server = $greets[0];
+    } else {
+        $server = 'localhost';
+    }
+
+    insert_to_log(compact('server', 'esmtp_id', 'subject', 'body'));
+}
+
+?>
+]]>
+</programlisting>
+
+</refsection>
+
+
 </refentry>