WEB SITES DON'T JUST display Web pages. Often, they also send e-mail messages. For example, sending a confirmation message to a user after he creates an account, changes a password, or places an order is a common practice. Many Web sites also send periodic e-mail newsletters containing new headlines or information about recent site updates. The PEAR Mail and Mail_mime modules provide a flexible, robust way to send e-mail messages from your PHP programs.

This chapter discusses PEAR Mail 1.1.2 and Mail_mime 1.2.1. With the PEAR Mail module, you have more control over how your e-mail messages are sent than if you just use PHP's built-in mail() function. The Mail_mime module supplies a way to send messages that are more complicated than plain-text ones-messages with attachments, HTML, and embedded images.

Sending Plain-Text Mail Messages with PEAR Mail

The PEAR Mail module sends e-mail messages and lets you switch easily between using a local or remote method to send your message and piggybacking on PHP's built-in mail() function. PEAR Mail also automatically takes care of platform dependencies such as line endings.

To send amessage, create a new Mail object using the Mail::factory() method and then call the send() method on that object, passing it the recipient's address, message body, and headers. Listing 9-1 demonstrates sending a message with the Mail module.

Listing 9-1. Sending an E-mail Message

require 'Mail.php';

$mailer =& Mail::factory('mail');

$to = 'destination@example.com';

$headers = array('Subject' => 'Hungry?',

'Cc: other-destination@example.com');

$body=<<<_MSG_

Are you hungry? Wouldn't you like a cold, sweet ice cream cone?

Why not stop by your local ice cream parlor today for a few

scoops of Guava Mint Bouillon?

Sincerely,

Your local ice cream booster

_MSG_;

$res = $mailer->send($to, $headers,$body);

// If the message can't be sent, send() returns a

// PEAR::Error object

if (PEAR::isError($res)) {

print "Couldn't send message: " . ->getMessage();

}

The first argument to Mail::factory() is which driver to use. The driver controls how the Mail object sends the message. Your driver choices are mail, smtp, and sendmail. The mail driver uses PHP's built-in mail() function, and the smtp driver uses an SMTP server. If you have Sendmail or a similar mailer program installed, you can use the sendmail driver as well.

Because the mail driver sends messages with PHP's built-in mail() function, it relies on the mail-related PHP configuration settings: sendmail_path and, on Windows, sendmail_from. The sendmail_path configuration setting should be set to the path of an external mailer program and any arguments you want to pass to the program. If you're using Sendmail on Unix, its path is probably /usr/sbin/sendmail or /usr/lib/sendmail.When you build and install PHP, the configure script looks for Sendmail and sets the configuration setting appropriately.

If you are using a mailer program other than Sendmail, set sendmail_path to the location of a Sendmail-compatible mail program that may have been supplied with your mailer software. For example, use the sendmail wrapper program that comes with qmail or the regular exim binary for Exim.

PHP 5 supports another mail-related configuration setting: mail_force_extra_parameters. The value of this setting is tacked onto the end of the command line when the mail() function runs Sendmail. You can use mail_force_extra_parameters to pass arguments to Sendmail.

Windows doesn't come with a built-in mailer program, but you can instruct the mail() function to send mail via an SMTP server with the SMTP and smtp_port configuration settings. Set SMTP to the name of the SMTP server you want to use, and, if the SMTP server uses a port other than 25 (the default SMTP port), set smtp_port to that alternative port number. With SMTP set and sendmail_path not set, the mail() function connects to the server defined by SMTP and relays the message through that server.

On any platform, you can bypass the mail() function and the intricacies of its configuration directives with the smtp driver. However, this driver requires that the Net_SMTP and Net_Socket PEAR modules be installed. Listing 9-2 shows how to send a message with the smtp driver.