• View
• Edit
• History
• Attach
• Print
• Backlinks

WikiMail

Questions answered by this recipe

This section is optional; use it to indicate the types of questions (if any) this recipe is intended to answer.

Description

This is a support recipe to provide a tool for other recipes. But if another recipe wants to read or write email then this "tool" will provide that capability without reinventing the wheel.

Installation and configuration

Begin with the usual, placing wikimail.phpΔ in your cookbook directory and placing this line in your config.php:

include_once("$FarmD/cookbook/wikimail.php");

Depending on how the recipe is configured which USES wikimail, you may or may not have to set these up. Generally it makes sense to give a sensible value to the ones that are emphasized as required/recommended.

For SENDING mail you will want to set up some or all of these (host, user, and passwd are usually required, from is recommended):

$WikiMailSMTP['Host']        // only used on win32 systems
$WikiMailSMTP['User']        // user for SMTP
$WikiMailSMTP['Passwd']      // passwd for SMTP
$WikiMailSMTP['Port']        // only used on win32 systems - 0=default
$WikiMailSMTP['SendmailPath']// only used on unix systems
$WikiMailSMTP['From']        // must be set in config.php unless already set via php.ini

For RECEIVING mail you will want to set up some or all of these (host, user, and pass are usually required):

# Simple example, setting up a profile named 'xyz' to access email for myuser@my.host.com using mypasswd as the password
wmMkProfilePOP3('xyz', 'my.host.com', 'myuser', 'mypasswd');

The rest of the (optional) parameters to MkProfilePOP3 are found in the following list:

PROFILE NAME          // name of the profile - see the using recipe for instructions
host                  // POP3 server host name
user                  // Authentication user name
password              // Authentication password
port                  // POP 3 server host port, usually 110 
                      // but some servers use other ports.  Gmail uses 995.
TLS                   // Establish secure connections using TLS
Realm                 // Authentication realm or domain
Workstation           // Workstation for NTLM authentication
APOP                  // Use APOP authentication
AuthMech              // SASL authentication mechanism
Debug                 // Output debug information
HTMLDebug             // Debug information is in HTML
JoinHeader            // Concatenate headers split in multiple lines

For any options where you are satisfied with the defaults simply pass the string "default".

You can also change the defaults by calling wmMkProfilePOP3('default', ...). The more information you set up in here (i.e., host, username, password) the less you will need to specify each time you create a new profile.

Notes

Developers

If you are a developer wanting to get mail capabilities (either sending or receiving) in your recipe, please see the comments internal to the PHP file for how to do this.

Here is a quick smattering of some of those comments, copied verbatim (from the 2008-08-16 version):

#   // (The wmMkProfilePOP3 call will often be done in config.php - note that
#   //  there are lots of other  optional parameters ro wmMkProfilePOP3)
#   wmMkProfilePOP3('myprofile', 'mail.myhost.com', 'username', 'pass');
#
#   // (This code [below] is what will normally be found in the recipe)
#   if (!wmInitPOP3('myprofile')) {
#       ... (handle failure)
#   } else {
#       while (($msg = wmRetrievePOP3('myprofile')) !== false) {
#          // $headhash is an associative array with, for instance,
#          //     $headhash['from']
#          // $headers is an array of lines from the header section
#          // $body is an array of lines from the body of the message
#          list($headhash, $headers, $body) = $msg;
#          # vvvvv OPTIONAL FROM HERE vvvvv
#          # the following 3 lines support mime handling
#          $bodytext = implode("\n", $body);
#          $headtext = implode("\n", $headers);
#          $mime = wmSimplifyMime($headtext."\n\n".$bodytext);
#          # if I want just the 'text' portion of the message (not html, etc):
#          $textmessage = wmTextMessage($mime);
#          # if I want to mess with an attachment named "filename.txt"
#          list($attach_type, $attach_content, $attach_name) = 
#              wmTextMessage($mime, "filename.txt");
#          # if you wanted to write that attachment to disk...
#          if ($fp = fopen($attach_name, "wb")) {
#              if (!fwrite($fp, $attach_content))
#                  $msg = "Unable to write to \"$attach_name\".";
#              fclose($uploadfp);
#          }
#          # ^^^^^ OPTIONAL TO HERE ^^^^^^
#          ...
#       }
#       if ($WikiMailErr) { // often this section is unnecessary
#          ... (wmRetrievePOP3 had errors - not just no more messages)
#       }
#       if (!wmClosePOP3('myprofile')) {
#          ... (reference $WikiMailErr if desired)
#       }
#   }
#
# Normal usage for sending mail:
#
#   wmSendMail($pagename, 'user@domain.com', 'subject', 
#       '(:include Group.Page:)');
# ---or (demonstrating sending to multiple addresses and using HTML format)---
#   $recipients = array('user1@domain1.com', 'user2@domain2.com');
#   $subject = 'some interesting subject';
#   $message = "This is a much longer message which can optionally\n";
#   $message.= "include markup such as (:include Group1.Page2:)";
#   wmSendMail($pagename, $recipients, $subject, $message, '', '', '',
#       'html', true);

Utility Function Usage:

• wmSimplifyMime()
  • EXAMPLE USAGE:
    • $mime = wmSimplifyMime($message_data)
  • Arguments:
    • This function accepts a complete message (often $headtext."\n\n".$bodytext) as its sole argument
  • Return Value:
    • a mime_parser_class object which can then be passed to other functions such as wmTextMessage and wmAttachment
• wmTextMessage()
  • EXAMPLE USAGE
    • if (($msg = wmTextMessage($mime)) !== FALSE) ...
  • Arguments:
    • This function accepts a mime_parser_class object (from wmSimplifyMime())
  • Return Value:
    • It returns just the TEXT portion of the inline message (no HTML, etc)
• wmAttachment()
  • EXAMPLE USAGE:
    • if (($attachmt = wmAttachment($mime, $which_attach)) !== FALSE) list($type, $content, $name) = $attachmt;
  • Arguments:
    • a mime_parser_class object (from wmSimplifyMime())
    • a variable which specifies which attachment to return. This specification is either
      • a filename -or-
      • a number to return the nth attachment
  • Return Value:
    • FALSE for failure
    • for success, a list containing list($type, $content, $name):
      • $type = the type of the attachment ('text', 'binary', etc.)
      • $content = the content of the attachment (already conveniently decoded)
      • $name = the filename used to create the attachment

Release Notes

• 2008-08-16 Added mime_parse content, again by Manuel Lemos. Also added 3 utility functions: wmSimplifyMime(), wmTextMessage(), and wmAttachment()
• 2008-08-08 Renamed several functions, re-worked the calling sequence for receiving mail, introduced the concept of profiles so that more than 1 recipe can be using wikimail simultaneously. Note that if a recipe is using wikimail and is not updated after this date to work with this version then you should not download this version of wikimail.php. There have been too many changes and the recipes must be in sync with one another.
• 2008-08-03 Added a return value for wmSendMail()
• 2008-08-02 Renamed a function for standardization (must coordinate with MiscMX release of same date)
• 2008-06-12 Initial release

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

See Also

Contributors

• Manuel Lemos (http://www.manuellemos.net/, http://www.phpclasses.org/browse/author/1.html) created pop3.php and mime_parser.php which constitute a significant portion of the content of this script. Appreciation to him for making these available.

Comments