From ba31059fef3f609673178c7a041c397540da1789 Mon Sep 17 00:00:00 2001 From: Evan Prodromou Date: Tue, 23 Dec 2008 12:33:30 -0500 Subject: reformat and document lib/mail.php for phpcs conformance darcs-hash:20081223173330-84dde-8cbbfd3953e8a67d5e58679431f93651ddf3122a.gz --- lib/mail.php | 704 ++++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 480 insertions(+), 224 deletions(-) (limited to 'lib/mail.php') diff --git a/lib/mail.php b/lib/mail.php index c90140d3c..5638ae9bf 100644 --- a/lib/mail.php +++ b/lib/mail.php @@ -1,9 +1,12 @@ . + * + * @category Mail + * @package Laconica + * @author Evan Prodromou + * @author Zach Copley + * @author Robin Millette + * @author Sarven Capadisli + * @copyright 2008 Control Yourself, Inc. + * @license http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0 + * @link http://laconi.ca/ */ -if (!defined('LACONICA')) { exit(1); } +if (!defined('LACONICA')) { + exit(1); +} -require_once('Mail.php'); +require_once 'Mail.php'; -function mail_backend() { - static $backend = NULL; +/** + * return the configured mail backend + * + * Uses the $config array to make a mail backend. Cached so it is safe to call + * more than once. + * + * @return Mail backend + */ - if (!$backend) { - global $config; - $backend = Mail::factory($config['mail']['backend'], - ($config['mail']['params']) ? $config['mail']['params'] : array()); - if (PEAR::isError($backend)) { - common_server_error($backend->getMessage(), 500); - } - } - return $backend; +function mail_backend() +{ + static $backend = null; + + if (!$backend) { + global $config; + $backend = Mail::factory($config['mail']['backend'], + ($config['mail']['params']) ? + $config['mail']['params'] : + array()); + if (PEAR::isError($backend)) { + common_server_error($backend->getMessage(), 500); + } + } + return $backend; } -# XXX: use Mail_Queue... maybe +/** + * send an email to one or more recipients + * + * @param array $recipients array of strings with email addresses of recipients + * @param array $headers array mapping strings to strings for email headers + * @param string $body body of the email + * + * @return boolean success flag + */ -function mail_send($recipients, $headers, $body) { - $backend = mail_backend(); +function mail_send($recipients, $headers, $body) +{ + // XXX: use Mail_Queue... maybe + $backend = mail_backend(); if (!isset($headers['Content-Type'])) { $headers['Content-Type'] = 'text/plain; charset=UTF-8'; } - assert($backend); # throws an error if it's bad - $sent = $backend->send($recipients, $headers, $body); - if (PEAR::isError($sent)) { - common_log(LOG_ERR, 'Email error: ' . $sent->getMessage()); - return false; - } - return true; + assert($backend); // throws an error if it's bad + $sent = $backend->send($recipients, $headers, $body); + if (PEAR::isError($sent)) { + common_log(LOG_ERR, 'Email error: ' . $sent->getMessage()); + return false; + } + return true; } -function mail_domain() { - $maildomain = common_config('mail', 'domain'); - if (!$maildomain) { - $maildomain = common_config('site', 'server'); - } - return $maildomain; -} +/** + * returns the configured mail domain + * + * Defaults to the server name. + * + * @return string mail domain, suitable for making email addresses. + */ -function mail_notify_from() { - $notifyfrom = common_config('mail', 'notifyfrom'); - if (!$notifyfrom) { - $domain = mail_domain(); - $notifyfrom = common_config('site', 'name') .' '; - } - return $notifyfrom; +function mail_domain() +{ + $maildomain = common_config('mail', 'domain'); + if (!$maildomain) { + $maildomain = common_config('site', 'server'); + } + return $maildomain; } -function mail_to_user(&$user, $subject, $body, $address=NULL) { - if (!$address) { - $address = $user->email; - } +/** + * returns a good address for sending email from this server + * + * Uses either the configured value or a faked-up value made + * from the mail domain. + * + * @return string notify from address + */ + +function mail_notify_from() +{ + $notifyfrom = common_config('mail', 'notifyfrom'); - $recipients = $address; - $profile = $user->getProfile(); + if (!$notifyfrom) { - $headers['From'] = mail_notify_from(); - $headers['To'] = $profile->getBestName() . ' <' . $address . '>'; - $headers['Subject'] = $subject; + $domain = mail_domain(); - return mail_send($recipients, $headers, $body); + $notifyfrom = common_config('site', 'name') .' '; + } + + return $notifyfrom; } -# For confirming a Jabber address +/** + * sends email to a user + * + * @param User &$user user to send email to + * @param string $subject subject of the email + * @param string $body body of the email + * @param string $address optional specification of email address + * + * @return boolean success flag + */ -function mail_confirm_address($user, $code, $nickname, $address) { +function mail_to_user(&$user, $subject, $body, $address=null) +{ + if (!$address) { + $address = $user->email; + } - $subject = _('Email address confirmation'); + $recipients = $address; + $profile = $user->getProfile(); - $body = sprintf(_("Hey, %s.\n\nSomeone just entered this email address on %s.\n\n" . - "If it was you, and you want to confirm your entry, use the URL below:\n\n\t%s\n\n" . - "If not, just ignore this message.\n\nThanks for your time, \n%s\n") - , $nickname, common_config('site', 'name') - , common_local_url('confirmaddress', array('code' => $code)), common_config('site', 'name')); - return mail_to_user($user, $subject, $body, $address); + $headers['From'] = mail_notify_from(); + $headers['To'] = $profile->getBestName() . ' <' . $address . '>'; + $headers['Subject'] = $subject; + + return mail_send($recipients, $headers, $body); } -function mail_subscribe_notify($listenee, $listener) { - $other = $listener->getProfile(); - mail_subscribe_notify_profile($listenee, $other); +/** + * Send an email to confirm a user's control of an email address + * + * @param User $user User claiming the email address + * @param string $code Confirmation code + * @param string $nickname Nickname of user + * @param string $address email address to confirm + * + * @see common_confirmation_code() + * + * @return success flag + */ + +function mail_confirm_address($user, $code, $nickname, $address) +{ + $subject = _('Email address confirmation'); + + $body = sprintf(_("Hey, %s.\n\n". + "Someone just entered this email address on %s.\n\n" . + "If it was you, and you want to confirm your entry, ". + "use the URL below:\n\n\t%s\n\n" . + "If not, just ignore this message.\n\n". + "Thanks for your time, \n%s\n"), + $nickname, common_config('site', 'name'), + common_local_url('confirmaddress', array('code' => $code)), + common_config('site', 'name')); + return mail_to_user($user, $subject, $body, $address); +} + +/** + * notify a user of subscription by another user + * + * This is just a wrapper around the profile-based version. + * + * @param User $listenee user who is being subscribed to + * @param User $listener user who is subscribing + * + * @see mail_subscribe_notify_profile() + * + * @return void + */ + +function mail_subscribe_notify($listenee, $listener) +{ + $other = $listener->getProfile(); + mail_subscribe_notify_profile($listenee, $other); } -function mail_subscribe_notify_profile($listenee, $other) { - if ($listenee->email && $listenee->emailnotifysub) { - // use the recipients localization +/** + * notify a user of subscription by a profile (remote or local) + * + * This function checks to see if the listenee has an email + * address and wants subscription notices. + * + * @param User $listenee user who's being subscribed to + * @param Profile $other profile of person who's listening + * + * @return void + */ + +function mail_subscribe_notify_profile($listenee, $other) +{ + if ($listenee->email && $listenee->emailnotifysub) { + + // use the recipient's localization common_init_locale($listenee->language); - $profile = $listenee->getProfile(); - $name = $profile->getBestName(); - $long_name = ($other->fullname) ? ($other->fullname . ' (' . $other->nickname . ')') : $other->nickname; - $recipients = $listenee->email; - $headers['From'] = mail_notify_from(); - $headers['To'] = $name . ' <' . $listenee->email . '>'; - $headers['Subject'] = sprintf(_('%1$s is now listening to your notices on %2$s.'), + + $profile = $listenee->getProfile(); + + $name = $profile->getBestName(); + + $long_name = ($other->fullname) ? + ($other->fullname . ' (' . $other->nickname . ')') : $other->nickname; + + $recipients = $listenee->email; + + $headers['From'] = mail_notify_from(); + $headers['To'] = $name . ' <' . $listenee->email . '>'; + $headers['Subject'] = sprintf(_('%1$s is now listening to '. + 'your notices on %2$s.'), $other->getBestName(), - common_config('site', 'name')); - $body = sprintf(_('%1$s is now listening to your notices on %2$s.'."\n\n". - "\t".'%3$s'."\n\n". - '%4$s'. - '%5$s'. - '%6$s'. - "\n".'Faithfully yours,'."\n".'%7$s.'."\n\n". - "----\n". - "Change your email address or notification options at %8$s"), - $long_name, - common_config('site', 'name'), - $other->profileurl, - ($other->location) ? sprintf(_("Location: %s\n"), $other->location) : '', - ($other->homepage) ? sprintf(_("Homepage: %s\n"), $other->homepage) : '', - ($other->bio) ? sprintf(_("Bio: %s\n\n"), $other->bio) : '', - common_config('site', 'name'), - common_local_url('emailsettings')); + common_config('site', 'name')); + + $body = sprintf(_('%1$s is now listening to your notices on %2$s.'."\n\n". + "\t".'%3$s'."\n\n". + '%4$s'. + '%5$s'. + '%6$s'. + "\n".'Faithfully yours,'."\n".'%7$s.'."\n\n". + "----\n". + "Change your email address or ". + "notification options at %8$s\n"), + $long_name, + common_config('site', 'name'), + $other->profileurl, + ($other->location) ? + sprintf(_("Location: %s\n"), $other->location) : '', + ($other->homepage) ? + sprintf(_("Homepage: %s\n"), $other->homepage) : '', + ($other->bio) ? + sprintf(_("Bio: %s\n\n"), $other->bio) : '', + common_config('site', 'name'), + common_local_url('emailsettings')); + // reset localization common_init_locale(); - mail_send($recipients, $headers, $body); - } + mail_send($recipients, $headers, $body); + } } -function mail_new_incoming_notify($user) { +/** + * notify a user of their new incoming email address + * + * User's email and incoming fields should already be updated. + * + * @param User $user user with the new address + * + * @return void + */ + +function mail_new_incoming_notify($user) +{ + $profile = $user->getProfile(); - $profile = $user->getProfile(); - $name = $profile->getBestName(); + $name = $profile->getBestName(); - $headers['From'] = $user->incomingemail; - $headers['To'] = $name . ' <' . $user->email . '>'; - $headers['Subject'] = sprintf(_('New email address for posting to %s'), - common_config('site', 'name')); + $headers['From'] = $user->incomingemail; + $headers['To'] = $name . ' <' . $user->email . '>'; + $headers['Subject'] = sprintf(_('New email address for posting to %s'), + common_config('site', 'name')); - $body = sprintf(_("You have a new posting address on %1\$s.\n\n". - "Send email to %2\$s to post new messages.\n\n". - "More email instructions at %3\$s.\n\n". - "Faithfully yours,\n%4\$s"), - common_config('site', 'name'), - $user->incomingemail, - common_local_url('doc', array('title' => 'email')), - common_config('site', 'name')); + $body = sprintf(_("You have a new posting address on %1\$s.\n\n". + "Send email to %2\$s to post new messages.\n\n". + "More email instructions at %3\$s.\n\n". + "Faithfully yours,\n%4\$s"), + common_config('site', 'name'), + $user->incomingemail, + common_local_url('doc', array('title' => 'email')), + common_config('site', 'name')); - mail_send($user->email, $headers, $body); + mail_send($user->email, $headers, $body); } -function mail_new_incoming_address() { - $prefix = common_confirmation_code(64); - $suffix = mail_domain(); - return $prefix . '@' . $suffix; +/** + * generate a new address for incoming messages + * + * @todo check the database for uniqueness + * + * @return string new email address for incoming messages + */ + +function mail_new_incoming_address() +{ + $prefix = common_confirmation_code(64); + $suffix = mail_domain(); + return $prefix . '@' . $suffix; } -function mail_broadcast_notice_sms($notice) { +/** + * broadcast a notice to all subscribers with SMS notification on + * + * This function sends SMS messages to all users who have sms addresses; + * have sms notification on; and have sms enabled for this particular + * subscription. + * + * @param Notice $notice The notice to broadcast + * + * @return success flag + */ - # Now, get users subscribed to this profile +function mail_broadcast_notice_sms($notice) +{ + // Now, get users subscribed to this profile - $user = new User(); + $user = new User(); - $user->query('SELECT nickname, smsemail, incomingemail ' . - 'FROM user JOIN subscription ' . - 'ON user.id = subscription.subscriber ' . - 'WHERE subscription.subscribed = ' . $notice->profile_id . ' ' . - 'AND user.smsemail IS NOT NULL ' . - 'AND user.smsnotify = 1 ' . + $user->query('SELECT nickname, smsemail, incomingemail ' . + 'FROM user JOIN subscription ' . + 'ON user.id = subscription.subscriber ' . + 'WHERE subscription.subscribed = ' . $notice->profile_id . ' ' . + 'AND user.smsemail IS NOT null ' . + 'AND user.smsnotify = 1 ' . 'AND subscription.sms = 1 '); - while ($user->fetch()) { - common_log(LOG_INFO, - 'Sending notice ' . $notice->id . ' to ' . $user->smsemail, - __FILE__); - $success = mail_send_sms_notice_address($notice, $user->smsemail, $user->incomingemail); - if (!$success) { - # XXX: Not sure, but I think that's the right thing to do - common_log(LOG_WARNING, - 'Sending notice ' . $notice->id . ' to ' . $user->smsemail . ' FAILED, cancelling.', - __FILE__); - return false; - } - } - - $user->free(); - unset($user); - - return true; + while ($user->fetch()) { + common_log(LOG_INFO, + 'Sending notice ' . $notice->id . ' to ' . $user->smsemail, + __FILE__); + $success = mail_send_sms_notice_address($notice, + $user->smsemail, + $user->incomingemail); + if (!$success) { + // XXX: Not sure, but I think that's the right thing to do + common_log(LOG_WARNING, + 'Sending notice ' . $notice->id . ' to ' . + $user->smsemail . ' FAILED, cancelling.', + __FILE__); + return false; + } + } + + $user->free(); + unset($user); + + return true; } -function mail_send_sms_notice($notice, $user) { - return mail_send_sms_notice_address($notice, $user->smsemail, $user->incomingemail); +/** + * send a notice to a user via SMS + * + * A convenience wrapper around mail_send_sms_notice_address() + * + * @param Notice $notice notice to send + * @param User $user user to receive notice + * + * @see mail_send_sms_notice_address() + * + * @return boolean success flag + */ + +function mail_send_sms_notice($notice, $user) +{ + return mail_send_sms_notice_address($notice, + $user->smsemail, + $user->incomingemail); } -function mail_send_sms_notice_address($notice, $smsemail, $incomingemail) { +/** + * send a notice to an SMS email address from a given address + * + * We use the user's incoming email address as the "From" address to make + * replying to notices easier. + * + * @param Notice $notice notice to send + * @param string $smsemail email address to send to + * @param string $incomingemail email address to set as 'from' + * + * @return boolean success flag + */ - $to = $nickname . ' <' . $smsemail . '>'; - $other = $notice->getProfile(); +function mail_send_sms_notice_address($notice, $smsemail, $incomingemail) +{ + $to = $nickname . ' <' . $smsemail . '>'; - common_log(LOG_INFO, "Sending notice " . $notice->id . " to " . $smsemail, __FILE__); + $other = $notice->getProfile(); - $headers = array(); - $headers['From'] = (isset($incomingemail)) ? $incomingemail : mail_notify_from(); - $headers['To'] = $to; - $headers['Subject'] = sprintf(_('%s status'), - $other->getBestName()); - $body = $notice->content; + common_log(LOG_INFO, 'Sending notice ' . $notice->id . + ' to ' . $smsemail, __FILE__); - return mail_send($smsemail, $headers, $body); + $headers = array(); + + $headers['From'] = ($incomingemail) ? $incomingemail : mail_notify_from(); + $headers['To'] = $to; + $headers['Subject'] = sprintf(_('%s status'), + $other->getBestName()); + + $body = $notice->content; + + return mail_send($smsemail, $headers, $body); } -function mail_confirm_sms($code, $nickname, $address) { +/** + * send a message to confirm a claim for an SMS number + * + * @param string $code confirmation code + * @param string $nickname nickname of user claiming number + * @param string $address email address to send the confirmation to + * + * @see common_confirmation_code() + * + * @return void + */ - $recipients = $address; +function mail_confirm_sms($code, $nickname, $address) +{ + $recipients = $address; - $headers['From'] = mail_notify_from(); - $headers['To'] = $nickname . ' <' . $address . '>'; - $headers['Subject'] = _('SMS confirmation'); + $headers['From'] = mail_notify_from(); + $headers['To'] = $nickname . ' <' . $address . '>'; + $headers['Subject'] = _('SMS confirmation'); - $body = "$nickname: confirm you own this phone number with this code:"; - $body .= "\n\n"; - $body .= $code; - $body .= "\n\n"; + // FIXME: I18N - mail_send($recipients, $headers, $body); + $body = "$nickname: confirm you own this phone number with this code:"; + $body .= "\n\n"; + $body .= $code; + $body .= "\n\n"; + + mail_send($recipients, $headers, $body); } -function mail_notify_nudge($from, $to) { +/** + * send a mail message to notify a user of a 'nudge' + * + * @param User $from user nudging + * @param User $to user being nudged + * + * @return boolean success flag + */ + +function mail_notify_nudge($from, $to) +{ common_init_locale($to->language); - $subject = sprintf(_('You\'ve been nudged by %s'), $from->nickname); - - $from_profile = $from->getProfile(); - - $body = sprintf(_("%1\$s (%2\$s) is wondering what you are up to these days and is inviting you to post some news.\n\n". - "So let's hear from you :)\n\n". - "%3\$s\n\n". - "Don't reply to this email; it won't get to them.\n\n". - "With kind regards,\n". - "%4\$s\n"), - $from_profile->getBestName(), - $from->nickname, - common_local_url('all', array('nickname' => $to->nickname)), - common_config('site', 'name')); + $subject = sprintf(_('You\'ve been nudged by %s'), $from->nickname); + + $from_profile = $from->getProfile(); + + $body = sprintf(_("%1\$s (%2\$s) is wondering what you are up to ". + "these days and is inviting you to post some news.\n\n". + "So let's hear from you :)\n\n". + "%3\$s\n\n". + "Don't reply to this email; it won't get to them.\n\n". + "With kind regards,\n". + "%4\$s\n"), + $from_profile->getBestName(), + $from->nickname, + common_local_url('all', array('nickname' => $to->nickname)), + common_config('site', 'name')); common_init_locale(); - return mail_to_user($to, $subject, $body); + return mail_to_user($to, $subject, $body); } -function mail_notify_message($message, $from=NULL, $to=NULL) { +/** + * send a message to notify a user of a direct message (DM) + * + * This function checks to see if the recipient wants notification + * of DMs and has a configured email address. + * + * @param Message $message message to notify about + * @param User $from user sending message; default to sender + * @param User $to user receiving message; default to recipient + * + * @return boolean success code + */ - if (is_null($from)) { - $from = User::staticGet('id', $message->from_profile); - } +function mail_notify_message($message, $from=null, $to=null) +{ + if (is_null($from)) { + $from = User::staticGet('id', $message->from_profile); + } - if (is_null($to)) { - $to = User::staticGet('id', $message->to_profile); - } + if (is_null($to)) { + $to = User::staticGet('id', $message->to_profile); + } - if (is_null($to->email) || !$to->emailnotifymsg) { - return true; - } + if (is_null($to->email) || !$to->emailnotifymsg) { + return true; + } common_init_locale($to->language); - $subject = sprintf(_('New private message from %s'), $from->nickname); - - $from_profile = $from->getProfile(); - - $body = sprintf(_("%1\$s (%2\$s) sent you a private message:\n\n". - "------------------------------------------------------\n". - "%3\$s\n". - "------------------------------------------------------\n\n". - "You can reply to their message here:\n\n". - "%4\$s\n\n". - "Don't reply to this email; it won't get to them.\n\n". - "With kind regards,\n". - "%5\$s\n"), - $from_profile->getBestName(), - $from->nickname, - $message->content, - common_local_url('newmessage', array('to' => $from->id)), - common_config('site', 'name')); + $subject = sprintf(_('New private message from %s'), $from->nickname); + + $from_profile = $from->getProfile(); + + $body = sprintf(_("%1\$s (%2\$s) sent you a private message:\n\n". + "------------------------------------------------------\n". + "%3\$s\n". + "------------------------------------------------------\n\n". + "You can reply to their message here:\n\n". + "%4\$s\n\n". + "Don't reply to this email; it won't get to them.\n\n". + "With kind regards,\n". + "%5\$s\n"), + $from_profile->getBestName(), + $from->nickname, + $message->content, + common_local_url('newmessage', array('to' => $from->id)), + common_config('site', 'name')); common_init_locale(); - return mail_to_user($to, $subject, $body); + return mail_to_user($to, $subject, $body); } -function mail_notify_fave($other, $user, $notice) { +/** + * notify a user that one of their notices has been chosen as a 'fave' + * + * Doesn't check that the user has an email address nor if they + * want to receive notification of faves. Maybe this happens higher + * up the stack...? + * + * @param User $other The user whose notice was faved + * @param User $user The user who faved the notice + * @param Notice $notice The notice that was faved + * + * @return void + */ + +function mail_notify_fave($other, $user, $notice) +{ + $profile = $user->getProfile(); + + $bestname = $profile->getBestName(); - $profile = $user->getProfile(); - $bestname = $profile->getBestName(); common_init_locale($other->language); - $subject = sprintf(_('%s added your notice as a favorite'), $bestname); - $body = sprintf(_("%1\$s just added your notice from %2\$s as one of their favorites.\n\n" . - "In case you forgot, you can see the text of your notice here:\n\n" . - "%3\$s\n\n" . - "You can see the list of %1\$s's favorites here:\n\n" . - "%4\$s\n\n" . - "Faithfully yours,\n" . - "%5\$s\n"), - $bestname, - common_exact_date($notice->created), - common_local_url('shownotice', array('notice' => $notice->id)), - common_local_url('showfavorites', array('nickname' => $user->nickname)), - common_config('site', 'name')); + + $subject = sprintf(_('%s added your notice as a favorite'), $bestname); + + $body = sprintf(_("%1\$s just added your notice from %2\$s". + " as one of their favorites.\n\n" . + "In case you forgot, you can see the text". + " of your notice here:\n\n" . + "%3\$s\n\n" . + "You can see the list of %1\$s's favorites here:\n\n" . + "%4\$s\n\n" . + "Faithfully yours,\n" . + "%5\$s\n"), + $bestname, + common_exact_date($notice->created), + common_local_url('shownotice', + array('notice' => $notice->id)), + common_local_url('showfavorites', + array('nickname' => $user->nickname)), + common_config('site', 'name')); common_init_locale(); - mail_to_user($other, $subject, $body); + mail_to_user($other, $subject, $body); } -- cgit v1.2.3-54-g00ecf