source: trunk/lib/Email.inc.php @ 622

Last change on this file since 622 was 622, checked in by anonymous, 6 years ago

Add Email() sandbox mode. Add Email->send() test. Fix minor bugs.
File size: 19.7 KB
Line 
1<?php
2/**
3 * The Strangecode Codebase - a general application development framework for PHP
4 * For details visit the project site: <http://trac.strangecode.com/codebase/>
5 * Copyright 2001-2012 Strangecode, LLC
6 *
7 * This file is part of The Strangecode Codebase.
8 *
9 * The Strangecode Codebase is free software: you can redistribute it and/or
10 * modify it under the terms of the GNU General Public License as published by the
11 * Free Software Foundation, either version 3 of the License, or (at your option)
12 * any later version.
13 *
14 * The Strangecode Codebase is distributed in the hope that it will be useful, but
15 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
16 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
17 * details.
18 *
19 * You should have received a copy of the GNU General Public License along with
20 * The Strangecode Codebase. If not, see <http://www.gnu.org/licenses/>.
21 */
22
23/*
24* Email.inc.php
25*
26* Easy email template usage.
27*
28* @author  Quinn Comendant <quinn@strangecode.com>
29* @version 1.0
30*
31* Example of use:
32---------------------------------------------------------------------
33// Setup email object.
34$email = new Email(array(
35    'to' => array($frm['email'], 'q@lovemachine.local'),
36    'from' => sprintf('"%s" <%s>', addcslashes($app->getParam('site_name'), '"'), $app->getParam('site_email')),
37    'subject' => 'Your account has been activated',
38));
39$email->setTemplate('email_registration_confirm.ihtml');
40// $email->setString('Or you can pass your message body as a string, also with {VARIABLES}.');
41$email->replace(array(
42    'site_name' => $app->getParam('site_name'),
43    'site_url' => $app->getParam('site_url'),
44    'username' => $frm['username'],
45    'password' => $frm['password1'],
46));
47if ($email->send()) {
48    $app->raiseMsg(sprintf(_("A confirmation email has been sent to %s."), $frm['email']), MSG_SUCCESS, __FILE__, __LINE__);
49} else {
50    $app->logMsg(sprintf('Error sending confirmation email to address %s', $frm['email']), LOG_NOTICE, __FILE__, __LINE__);
51}
52---------------------------------------------------------------------
53*/
54
55class Email
56{
57
58    // Default parameters, to be overwritten by setParam() and read with getParam()
59    protected $_params = array(
60        'to' => null,
61        'from' => null,
62        'subject' => null,
63        'headers' => null,
64        'envelope_sender_address' => null, // AKA the bounce-to address. Will default to 'from' if left null.
65        'regex' => null,
66
67        // A single carriage return (\n) should terminate lines for locally injected mail.
68        // A carriage return + line-feed (\r\n) should be used if sending mail directly with SMTP.
69        'crlf' => "\n",
70
71        // RFC 2822 says line length MUST be no more than 998 characters, and SHOULD be no more than 78 characters, excluding the CRLF.
72        // http://mailformat.dan.info/body/linelength.html
73        'wrap' => true,
74        'line_length' => 75,
75
76        'sandbox_mode' => null,
77        'sandbox_to_addr' => null,
78    );
79
80    // String that contains the email body.
81    protected $_template;
82
83    // String that contains the email body after replacements.
84    protected $_template_replaced;
85
86    // Email debug modes.
87    const SANDBOX_MODE_REDIRECT = 1; // Send all mail to 'sandbox_to_addr'
88    const SANDBOX_MODE_STDERR = 2; // Log all mail to stderr
89
90    /**
91     * Constructor.
92     *
93     * @access  public
94     * @param   array   $params     Array of object parameters.
95     * @author  Quinn Comendant <quinn@strangecode.com>
96     * @since   28 Nov 2005 12:59:41
97     */
98    public function __construct($params=null)
99    {
100        // The regex used in validEmail(). Set here instead of in the default _params above so we can use the concatenation . dot.
101        // This matches a (valid) email address as complex as:
102        //      "Jane & Bob Smith" <bob&smith's/dep=sales!@smith-wick.ca.us > (Sales department)
103        // ...and something as simple as:
104        //      x@x.com
105        $this->setParam(array('regex' => '/^(?:(?:"[^"]*?"\s*|[^,@]*)(<\s*)|(?:"[^"]*?"|[^,@]*)\s+|)'   // Display name
106        . '((?:[^.<>\s@",\[\]]+[^<>\s@",\[\]])*[^.<>\s@",\[\]]+)'       // Local-part
107        . '@'                                                           // @
108        . '((?:(\[)|[A-Z0-9]?)'                                         // Domain, first char
109        . '(?(4)'                                                       // Domain conditional for if first domain char is [
110        . '(?:[0-9]{1,3}\.){3}[0-9]{1,3}\]'                             // TRUE, matches IP address
111        . '|'
112        . '[.-]?(?:[A-Z0-9]+[-.])*(?:[A-Z0-9]+\.)+[A-Z]{2,6}))'         // FALSE, matches domain name
113        . '(?(1)'                                                       // Comment conditional for if initial < exists
114        . '(?:\s*>\s*|>\s+\([^,@]+\)\s*)'                               // TRUE, ensure ending >
115        . '|'
116        . '(?:|\s*|\s+\([^,@]+\)\s*))$/i'));                            // FALSE ensure there is no ending >
117
118        if (isset($params)) {
119            $this->setParam($params);
120        }
121    }
122
123    /**
124     * Set (or overwrite existing) parameters by passing an array of new parameters.
125     *
126     * @access public
127     * @param  array    $params     Array of parameters (key => val pairs).
128     */
129    public function setParam($params)
130    {
131        $app =& App::getInstance();
132
133        if (isset($params) && is_array($params)) {
134            // Enforce valid email addresses.
135            if (isset($params['to']) && !$this->validEmail($params['to'])) {
136                $params['to'] = null;
137            }
138            if (isset($params['from']) && !$this->validEmail($params['from'])) {
139                $params['from'] = null;
140            }
141            if (isset($params['envelope_sender_address']) && !$this->validEmail($params['envelope_sender_address'])) {
142                $params['envelope_sender_address'] = null;
143            }
144
145            // Merge new parameters with old overriding only those passed.
146            $this->_params = array_merge($this->_params, $params);
147        } else {
148            $app->logMsg(sprintf('Parameters are not an array: %s', $params), LOG_ERR, __FILE__, __LINE__);
149        }
150    }
151
152    /**
153     * Return the value of a parameter, if it exists.
154     *
155     * @access public
156     * @param string $param        Which parameter to return.
157     * @return mixed               Configured parameter value.
158     */
159    public function getParam($param)
160    {
161        $app =& App::getInstance();
162
163        if (array_key_exists($param, $this->_params)) {
164            return $this->_params[$param];
165        } else {
166            $app->logMsg(sprintf('Parameter is not set: %s', $param), LOG_DEBUG, __FILE__, __LINE__);
167            return null;
168        }
169    }
170
171    /**
172     * Loads template from file to generate email body.
173     *
174     * @access  public
175     * @param   string  $template   Filename of email template.
176     * @author  Quinn Comendant <quinn@strangecode.com>
177     * @since   28 Nov 2005 12:56:23
178     */
179    public function setTemplate($template)
180    {
181        $app =& App::getInstance();
182
183        // Load file, using include_path.
184        if (!$this->_template = file_get_contents($template, true)) {
185            $app->logMsg(sprintf('Email template file does not exist: %s', $template), LOG_ERR, __FILE__, __LINE__);
186            $this->_template = null;
187            $this->_template_replaced = null;
188            return false;
189        }
190
191        // Ensure template is UTF-8.
192        $detected_encoding = mb_detect_encoding($this->_template, array('UTF-8', 'ISO-8859-1', 'WINDOWS-1252'), true);
193        if ('UTF-8' != strtoupper($detected_encoding)) {
194            $this->_template = mb_convert_encoding($this->_template, 'UTF-8', $detected_encoding);
195        }
196
197        // This could be a new template, so reset the _template_replaced.
198        $this->_template_replaced = null;
199        return true;
200    }
201
202    /**
203     * Loads template from string to generate email body.
204     *
205     * @access  public
206     * @param   string  $template   Filename of email template.
207     * @author  Quinn Comendant <quinn@strangecode.com>
208     * @since   28 Nov 2005 12:56:23
209     */
210    public function setString($string)
211    {
212        $app =& App::getInstance();
213
214        if ('' == trim($string)) {
215            $app->logMsg(sprintf('Empty string provided.', null), LOG_ERR, __FILE__, __LINE__);
216            $this->_template_replaced = null;
217            return false;
218        } else {
219            $this->_template = $string;
220            // This could be a new template, so reset the _template_replaced.
221            $this->_template_replaced = null;
222            return true;
223        }
224    }
225
226    /**
227     * Replace variables in template with argument data.
228     *
229     * @access  public
230     * @param   array   $replacements   Array keys are the values to search for, array vales are the replacement values.
231     * @author  Quinn Comendant <quinn@strangecode.com>
232     * @since   28 Nov 2005 13:08:51
233     */
234    public function replace($replacements)
235    {
236        $app =& App::getInstance();
237
238        // Ensure template exists.
239        if (!isset($this->_template)) {
240            $app->logMsg(sprintf('Cannot replace variables, no template defined.', null), LOG_ERR, __FILE__, __LINE__);
241            return false;
242        }
243
244        // Ensure replacements argument is an array.
245        if (!is_array($replacements)) {
246            $app->logMsg(sprintf('Cannot replace variables, invalid replacements.', null), LOG_ERR, __FILE__, __LINE__);
247            return false;
248        }
249
250        // Apply regex pattern to search elements.
251        $search = array_keys($replacements);
252        array_walk($search, create_function('&$v', '$v = "{" . mb_strtoupper($v) . "}";'));
253
254        // Replacement values.
255        $replace = array_values($replacements);
256
257        // Search and replace all values at once.
258        $this->_template_replaced = str_replace($search, $replace, $this->_template);
259    }
260
261    /*
262    * Returns the body of the current email. This can be used to store the message that is being sent.
263    * It will use the original template, or the replaced template if it has been processed.
264    * You can also use this function to do post-processing on the email body before sending it,
265    * like removing extraneous lines:
266    * $email->setString(preg_replace('/(?:(?:\r\n|\r|\n)\s*){2}/s', "\n\n", $email->getBody()));
267    *
268    * @access   public
269    * @return   string  Message body.
270    * @author   Quinn Comendant <quinn@strangecode.com>
271    * @version  1.0
272    * @since    18 Nov 2014 21:15:19
273    */
274    public function getBody()
275    {
276        $app =& App::getInstance();
277
278        $final_body = isset($this->_template_replaced) ? $this->_template_replaced : $this->_template;
279        // Ensure all placeholders have been replaced. Find anything with {...} characters.
280        if (preg_match('/({[^}]+})/', $final_body, $unreplaced_match)) {
281            unset($unreplaced_match[0]);
282            $app->logMsg(sprintf('Cannot get email body. Unreplaced variables in template: %s', getDump($unreplaced_match)), LOG_ERR, __FILE__, __LINE__);
283            return false;
284        }
285        return $final_body;
286    }
287
288    /**
289     * Send email using PHP's mail() function.
290     *
291     * @access  public
292     * @param   string  $to
293     * @param   string  $from
294     * @param   string  $subject
295     * @author  Quinn Comendant <quinn@strangecode.com>
296     * @since   28 Nov 2005 12:56:09
297     */
298    public function send($to=null, $from=null, $subject=null, $headers=null)
299    {
300        $app =& App::getInstance();
301
302        // Use arguments if provided.
303        if (isset($to)) {
304            $this->setParam(array('to' => $to));
305        }
306        if (isset($from)) {
307            $this->setParam(array('from' => $from));
308        }
309        if (isset($subject)) {
310            $this->setParam(array('subject' => $subject));
311        }
312        if (isset($headers)) {
313            $this->setParam(array('headers' => $headers));
314        }
315
316        // Ensure required values exist.
317        if (!isset($this->_params['subject'])) {
318            $app->logMsg('Cannot send email. SUBJECT not defined.', LOG_ERR, __FILE__, __LINE__);
319            return false;
320        } else if (!isset($this->_template)) {
321            $app->logMsg(sprintf('Cannot send email: "%s". Template not set.', $this->_params['subject']), LOG_ERR, __FILE__, __LINE__);
322            return false;
323        } else if (!isset($this->_params['to'])) {
324            $app->logMsg(sprintf('Cannot send email: "%s". TO not defined.', $this->_params['subject']), LOG_NOTICE, __FILE__, __LINE__);
325            return false;
326        } else if (!isset($this->_params['from'])) {
327            $app->logMsg(sprintf('Cannot send email: "%s". FROM not defined.', $this->_params['subject']), LOG_ERR, __FILE__, __LINE__);
328            return false;
329        }
330
331        // Wrap email text body, using _template_replaced if replacements have been used, or just a fresh _template if not.
332        $final_body = isset($this->_template_replaced) ? $this->_template_replaced : $this->_template;
333        if (false !== $this->getParam('wrap')) {
334            $final_body = wordwrap($final_body, $this->getParam('line_length'), $this->getParam('crlf'));
335        }
336
337        // Ensure all placeholders have been replaced. Find anything with {...} characters.
338        if (preg_match('/({[^}]+})/', $final_body, $unreplaced_match)) {
339            unset($unreplaced_match[0]);
340            $app->logMsg(sprintf('Cannot send email. Unreplaced variables in template: %s', getDump($unreplaced_match)), LOG_ERR, __FILE__, __LINE__);
341            return false;
342        }
343
344        // Final "to" header can have multiple addresses if in an array.
345        $final_to = is_array($this->_params['to']) ? join(', ', $this->_params['to']) : $this->_params['to'];
346
347        // From headers are custom headers.
348        $headers = array('From' => $this->_params['from']);
349
350        // Additional headers.
351        if (isset($this->_params['headers']) && is_array($this->_params['headers'])) {
352            $headers = array_merge($this->_params['headers'], $headers);
353        }
354
355        // Process headers.
356        $final_headers = array();
357        foreach ($headers as $key => $val) {
358            // Validate key and values.
359            if (empty($val)) {
360                $app->logMsg(sprintf('Empty email header provided: %s', $key), LOG_DEBUG, __FILE__, __LINE__);
361                continue;
362            }
363            if (empty($key) || !is_string($key) || !is_string($val) || preg_match("/[\n\r]/", $key . $val) || preg_match('/[^\w-]/', $key)) {
364                $app->logMsg(sprintf('Broken email header provided: %s=%s', $key, $val), LOG_WARNING, __FILE__, __LINE__);
365                continue;
366            }
367            // If the envelope_sender_address was given as a header, move it to the correct place.
368            if ('envelope_sender_address' == strtolower($key)) {
369                $this->_params['envelope_sender_address'] = isset($this->_params['envelope_sender_address']) ? $this->_params['envelope_sender_address'] : $val;
370                continue;
371            }
372            // If we're sending in sandbox mode, remove any headers with recipient addresses.
373            if ($this->getParam('sandbox_mode') == self::SANDBOX_MODE_REDIRECT && in_array(strtolower($key), array('to', 'cc', 'bcc')) && mb_strpos($val, '@') !== false) {
374                // Don't carry this into the $final_headers.
375                $app->logMsg(sprintf('Skipping header in sandbox mode: %s=%s', $key, $val), LOG_DEBUG, __FILE__, __LINE__);
376                continue;
377            }
378            $final_headers[] = sprintf('%s: %s', $key, $val);
379        }
380        $final_headers = join($this->getParam('crlf'), $final_headers);
381
382        // This is the address where delivery problems are sent to. We must strip off everything except the local@domain part.
383        if (isset($this->_params['envelope_sender_address'])) {
384            $envelope_sender_address = sprintf('<%s>', trim($this->_params['envelope_sender_address'], '<>'));
385        } else {
386            $envelope_sender_address = preg_replace('/^.*<?([^\s@\[\]<>()]+\@[A-Za-z0-9.-]{1,}\.[A-Za-z]{2,5})>?$/iU', '$1', $this->_params['from']);
387        }
388        if ('' != $envelope_sender_address && $this->validEmail($envelope_sender_address)) {
389            $additional_parameter = sprintf('-f %s', $envelope_sender_address);
390        } else {
391            $additional_parameter = '';
392        }
393
394        // Check for mail header injection attacks.
395        $full_mail_content = join($this->getParam('crlf'), array($final_to, $this->_params['subject'], $final_body));
396        if (preg_match("/(^|[\n\r])(Content-Type|MIME-Version|Content-Transfer-Encoding|Bcc|Cc)\s*:/i", $full_mail_content)) {
397            $app->logMsg(sprintf('Mail header injection attack in content: %s', $full_mail_content), LOG_WARNING, __FILE__, __LINE__);
398            return false;
399        }
400
401        // Enter sandbox mode, if specified.
402        switch ($this->getParam('sandbox_mode')) {
403        case self::SANDBOX_MODE_REDIRECT:
404            if (!$this->getParam('sandbox_to_addr')) {
405                $app->logMsg(sprintf('Email sandbox_mode is SANDBOX_MODE_REDIRECT but sandbox_to_addr is not set.', null), LOG_ERR, __FILE__, __LINE__);
406                break;
407            }
408            $final_to = $this->getParam('sandbox_to_addr');
409            break;
410
411        case self::SANDBOX_MODE_STDERR:
412            file_put_contents('php://stderr', sprintf("Subject: %s\nTo: %s\n%s\n\n%s", $this->getParam('subject'), $final_to, str_replace($this->getParam('crlf'), "\n", $final_headers), $final_body), FILE_APPEND);
413            return true;
414        }
415
416        // Send email without 5th parameter if safemode is enabled.
417        if (ini_get('safe_mode')) {
418            $ret = mb_send_mail($final_to, $this->_params['subject'], $final_body, $final_headers);
419        } else {
420            $ret = mb_send_mail($final_to, $this->_params['subject'], $final_body, $final_headers, $additional_parameter);
421        }
422
423        // Ensure message was successfully accepted for delivery.
424        if ($ret) {
425            $app->logMsg(sprintf('Email successfully sent to %s', $final_to), LOG_INFO, __FILE__, __LINE__);
426            return true;
427        } else {
428            $app->logMsg(sprintf('Email failure: %s, %s, %s, %s', $final_to, $this->_params['subject'], str_replace("\r\n", '\r\n', $final_headers), $additional_parameter), LOG_WARNING, __FILE__, __LINE__);
429            return false;
430        }
431    }
432
433    /**
434     * Validates an email address based on the recommendations in RFC 3696.
435     * Is more loose than restrictive, to allow the many valid variants of
436     * email addresses while catching the most common mistakes. Checks an array too.
437     * http://www.faqs.org/rfcs/rfc822.html
438     * http://www.faqs.org/rfcs/rfc2822.html
439     * http://www.faqs.org/rfcs/rfc3696.html
440     * http://www.faqs.org/rfcs/rfc1035.html
441     *
442     * @access  public
443     * @param   mixed  $email  Address to check, string or array.
444     * @return  bool    Validity of address.
445     * @author  Quinn Comendant <quinn@strangecode.com>
446     * @since   30 Nov 2005 22:00:50
447     */
448    public function validEmail($email)
449    {
450        $app =& App::getInstance();
451
452        // If an array, check values recursively.
453        if (is_array($email)) {
454            foreach ($email as $e) {
455                if (!$this->validEmail($e)) {
456                    return false;
457                }
458            }
459            return true;
460        } else {
461            // To be valid email address must match regex and fit within the length constraints.
462            if (preg_match($this->getParam('regex'), $email, $e_parts) && mb_strlen($e_parts[2]) < 64 && mb_strlen($e_parts[3]) < 255) {
463                return true;
464            } else {
465                $app->logMsg(sprintf('Invalid email address: %s', $email), LOG_INFO, __FILE__, __LINE__);
466                return false;
467            }
468        }
469    }
470}
471
Note: See TracBrowser for help on using the repository browser.