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

Last change on this file since 759 was 759, checked in by anonymous, 2 years ago

Minor
File size: 20.8 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 filename of the template used (for logging).
81    protected $_template_filename;
82
83    // String that contains the email body.
84    protected $_template;
85
86    // String that contains the email body after replacements.
87    protected $_template_replaced;
88
89    // Email debug modes.
90    const SANDBOX_MODE_REDIRECT = 1; // Send all mail to 'sandbox_to_addr'
91    const SANDBOX_MODE_STDERR = 2; // Log all mail to stderr
92    const SANDBOX_MODE_LOG = 3; // Log all mail using $app->logMsg(
)
93
94    /**
95     * Constructor.
96     *
97     * @access  public
98     * @param   array   $params     Array of object parameters.
99     * @author  Quinn Comendant <quinn@strangecode.com>
100     * @since   28 Nov 2005 12:59:41
101     */
102    public function __construct($params=null)
103    {
104        $app =& App::getInstance();
105
106        // The regex used in validEmail(). Set here instead of in the default _params above so we can use the concatenation . dot.
107        // This matches a (valid) email address as complex as:
108        //      "Jane & Bob Smith" <bob&smith's/dep=sales!@smith-wick.ca.us > (Sales department)
109        // ...and something as simple as:
110        //      x@x.com
111        $this->setParam(array('regex' => '/^(?:(?:"[^"]*?"\s*|[^,@]*)(<\s*)|(?:"[^"]*?"|[^,@]*)\s+|)'   // Display name
112        . '((?:[^.<>\s@",\[\]]+[^<>\s@",\[\]])*[^.<>\s@",\[\]]+)'       // Local-part
113        . '@'                                                           // @
114        . '((?:(\[)|[a-z0-9]?)'                                         // Domain, first char
115        . '(?(4)'                                                       // Domain conditional for if first domain char is [
116        . '(?:[0-9]{1,3}\.){3}[0-9]{1,3}\]'                             // TRUE, matches IP address
117        . '|'
118        . '[.-]?(?:[a-z0-9]+[-.])*(?:[a-z0-9]+\.)+[a-z]{2,19}))'        // FALSE, matches domain name
119        . '(?(1)'                                                       // Comment conditional for if initial < exists
120        . '(?:\s*>\s*|>\s+\([^,@]+\)\s*)'                               // TRUE, ensure ending >
121        . '|'
122        . '(?:|\s*|\s+\([^,@]+\)\s*))$/i' . $app->getParam('preg_u'))); // FALSE ensure there is no ending >
123
124        if (isset($params)) {
125            $this->setParam($params);
126        }
127    }
128
129    /**
130     * Set (or overwrite existing) parameters by passing an array of new parameters.
131     *
132     * @access public
133     * @param  array    $params     Array of parameters (key => val pairs).
134     */
135    public function setParam($params)
136    {
137        $app =& App::getInstance();
138
139        if (isset($params) && is_array($params)) {
140            // Enforce valid email addresses.
141            if (isset($params['to']) && !$this->validEmail($params['to'])) {
142                $params['to'] = null;
143            }
144            if (isset($params['from']) && !$this->validEmail($params['from'])) {
145                $params['from'] = null;
146            }
147            if (isset($params['envelope_sender_address']) && !$this->validEmail($params['envelope_sender_address'])) {
148                $params['envelope_sender_address'] = null;
149            }
150
151            // Merge new parameters with old overriding only those passed.
152            $this->_params = array_merge($this->_params, $params);
153        } else {
154            $app->logMsg(sprintf('Parameters are not an array: %s', $params), LOG_ERR, __FILE__, __LINE__);
155        }
156    }
157
158    /**
159     * Return the value of a parameter, if it exists.
160     *
161     * @access public
162     * @param string $param        Which parameter to return.
163     * @return mixed               Configured parameter value.
164     */
165    public function getParam($param)
166    {
167        $app =& App::getInstance();
168
169        if (array_key_exists($param, $this->_params)) {
170            return $this->_params[$param];
171        } else {
172            $app->logMsg(sprintf('Parameter is not set: %s', $param), LOG_DEBUG, __FILE__, __LINE__);
173            return null;
174        }
175    }
176
177    /**
178     * Loads template from file to generate email body.
179     *
180     * @access  public
181     * @param   string  $template   Filename of email template.
182     * @author  Quinn Comendant <quinn@strangecode.com>
183     * @since   28 Nov 2005 12:56:23
184     */
185    public function setTemplate($template)
186    {
187        $app =& App::getInstance();
188
189        // Load file, using include_path.
190        if (!$this->_template = file_get_contents($template, true)) {
191            $app->logMsg(sprintf('Email template file does not exist: %s', $template), LOG_ERR, __FILE__, __LINE__);
192            $this->_template = null;
193            $this->_template_replaced = null;
194            return false;
195        }
196
197        // Ensure template is UTF-8.
198        $detected_encoding = mb_detect_encoding($this->_template, array('UTF-8', 'ISO-8859-1', 'WINDOWS-1252'), true);
199        if ('UTF-8' != strtoupper($detected_encoding)) {
200            $this->_template = mb_convert_encoding($this->_template, 'UTF-8', $detected_encoding);
201        }
202
203        // This could be a new template, so reset the _template_replaced.
204        $this->_template_replaced = null;
205
206        $this->_template_filename = $template;
207
208        return true;
209    }
210
211    /**
212     * Loads template from string to generate email body.
213     *
214     * @access  public
215     * @param   string  $template   Filename of email template.
216     * @author  Quinn Comendant <quinn@strangecode.com>
217     * @since   28 Nov 2005 12:56:23
218     */
219    public function setString($string)
220    {
221        $app =& App::getInstance();
222
223        if ('' == trim($string)) {
224            $app->logMsg(sprintf('Empty string provided.', null), LOG_ERR, __FILE__, __LINE__);
225            $this->_template_replaced = null;
226            return false;
227        } else {
228            $this->_template = $string;
229            // This could be a new template, so reset the _template_replaced.
230            $this->_template_replaced = null;
231
232            $this->_template_filename = '(using Email::setString)';
233
234            return true;
235        }
236    }
237
238    /**
239     * Replace variables in template with argument data.
240     *
241     * @access  public
242     * @param   array   $replacements   Array keys are the values to search for, array vales are the replacement values.
243     * @author  Quinn Comendant <quinn@strangecode.com>
244     * @since   28 Nov 2005 13:08:51
245     */
246    public function replace($replacements)
247    {
248        $app =& App::getInstance();
249
250        // Ensure template exists.
251        if (!isset($this->_template)) {
252            $app->logMsg(sprintf('Cannot replace variables, no template defined.', null), LOG_ERR, __FILE__, __LINE__);
253            return false;
254        }
255
256        // Ensure replacements argument is an array.
257        if (!is_array($replacements)) {
258            $app->logMsg(sprintf('Cannot replace variables, invalid replacements.', null), LOG_ERR, __FILE__, __LINE__);
259            return false;
260        }
261
262        // Apply regex pattern to search elements.
263        $search = array_keys($replacements);
264        array_walk($search, function (&$v) {
265            $v = sprintf('{%s}', mb_strtoupper($v));
266        });
267
268        // Replacement values.
269        $replace = array_values($replacements);
270
271        // Search and replace all values at once.
272        $this->_template_replaced = str_replace($search, $replace, $this->_template);
273    }
274
275    /*
276    * Returns the body of the current email. This can be used to store the message that is being sent.
277    * It will use the original template, or the replaced template if it has been processed.
278    * You can also use this function to do post-processing on the email body before sending it,
279    * like removing extraneous lines:
280    * $email->setString(preg_replace('/(?:(?:\r\n|\r|\n)\s*){2}/su', "\n\n", $email->getBody()));
281    *
282    * @access   public
283    * @return   string  Message body.
284    * @author   Quinn Comendant <quinn@strangecode.com>
285    * @version  1.0
286    * @since    18 Nov 2014 21:15:19
287    */
288    public function getBody()
289    {
290        $app =& App::getInstance();
291
292        $final_body = isset($this->_template_replaced) ? $this->_template_replaced : $this->_template;
293        // Ensure all placeholders have been replaced. Find anything with {...} characters.
294        if (preg_match('/({[^}]+})/', $final_body, $unreplaced_match)) {
295            unset($unreplaced_match[0]);
296            $app->logMsg(sprintf('Cannot get email body. Unreplaced variable(s) "%s" in template "%s"', getDump($unreplaced_match), $this->_template_filename), LOG_ERR, __FILE__, __LINE__);
297            return false;
298        }
299        return $final_body;
300    }
301
302    /**
303     * Send email using PHP's mail() function.
304     *
305     * @access  public
306     * @param   string  $to
307     * @param   string  $from
308     * @param   string  $subject
309     * @author  Quinn Comendant <quinn@strangecode.com>
310     * @since   28 Nov 2005 12:56:09
311     */
312    public function send($to=null, $from=null, $subject=null, $headers=null)
313    {
314        $app =& App::getInstance();
315
316        // Use arguments if provided.
317        if (isset($to)) {
318            $this->setParam(array('to' => $to));
319        }
320        if (isset($from)) {
321            $this->setParam(array('from' => $from));
322        }
323        if (isset($subject)) {
324            $this->setParam(array('subject' => $subject));
325        }
326        if (isset($headers)) {
327            $this->setParam(array('headers' => $headers));
328        }
329
330        // Ensure required values exist.
331        if (!isset($this->_params['subject'])) {
332            $app->logMsg('Cannot send email. SUBJECT not defined.', LOG_ERR, __FILE__, __LINE__);
333            return false;
334        } else if (!isset($this->_template)) {
335            $app->logMsg(sprintf('Cannot send email: "%s". Template not set.', $this->_params['subject']), LOG_ERR, __FILE__, __LINE__);
336            return false;
337        } else if (!isset($this->_params['to'])) {
338            $app->logMsg(sprintf('Cannot send email: "%s". TO not defined.', $this->_params['subject']), LOG_NOTICE, __FILE__, __LINE__);
339            return false;
340        } else if (!isset($this->_params['from'])) {
341            $app->logMsg(sprintf('Cannot send email: "%s". FROM not defined.', $this->_params['subject']), LOG_ERR, __FILE__, __LINE__);
342            return false;
343        }
344
345        // Wrap email text body, using _template_replaced if replacements have been used, or just a fresh _template if not.
346        $final_body = isset($this->_template_replaced) ? $this->_template_replaced : $this->_template;
347        if (false !== $this->getParam('wrap')) {
348            $final_body = wordwrap($final_body, $this->getParam('line_length'), $this->getParam('crlf'));
349        }
350
351        // Ensure all placeholders have been replaced. Find anything with {...} characters.
352        if (preg_match('/({[^}]+})/', $final_body, $unreplaced_match)) {
353            unset($unreplaced_match[0]);
354            $app->logMsg(sprintf('Unreplaced variable(s) "%s" in template "%s"', getDump($unreplaced_match), $this->_template_filename), LOG_ERR, __FILE__, __LINE__);
355            return false;
356        }
357
358        // Final "to" header can have multiple addresses if in an array.
359        $final_to = is_array($this->_params['to']) ? join(', ', $this->_params['to']) : $this->_params['to'];
360
361        // From headers are custom headers.
362        $headers = array('From' => $this->_params['from']);
363
364        // Additional headers.
365        if (isset($this->_params['headers']) && is_array($this->_params['headers'])) {
366            $headers = array_merge($this->_params['headers'], $headers);
367        }
368
369        // Process headers.
370        $final_headers_arr = array();
371        $final_headers = '';
372        foreach ($headers as $key => $val) {
373            // Validate key and values.
374            if (!strlen($val)) {
375                $app->logMsg(sprintf('Empty email header provided: %s', $key), LOG_NOTICE, __FILE__, __LINE__);
376                continue;
377            }
378            if (!strlen($key) || preg_match("/[\n\r]/", $key . $val) || preg_match('/[^\w-]/', $key)) {
379                $app->logMsg(sprintf('Broken email header provided: %s=%s', $key, $val), LOG_WARNING, __FILE__, __LINE__);
380                continue;
381            }
382            // If the envelope_sender_address was given as a header, move it to the correct place.
383            if ('envelope_sender_address' == strtolower($key)) {
384                $this->_params['envelope_sender_address'] = isset($this->_params['envelope_sender_address']) ? $this->_params['envelope_sender_address'] : $val;
385                continue;
386            }
387            // If we're sending in sandbox mode, remove any headers with recipient addresses.
388            if ($this->getParam('sandbox_mode') == self::SANDBOX_MODE_REDIRECT && in_array(strtolower($key), array('to', 'cc', 'bcc')) && mb_strpos($val, '@') !== false) {
389                // Don't carry this into the $final_headers.
390                $app->logMsg(sprintf('Skipping header in sandbox mode: %s=%s', $key, $val), LOG_DEBUG, __FILE__, __LINE__);
391                continue;
392            }
393            $final_headers_arr[] = sprintf('%s: %s', $key, $val);
394        }
395        $final_headers = join($this->getParam('crlf'), $final_headers_arr);
396
397        // This is the address where delivery problems are sent to. We must strip off everything except the local@domain part.
398        if (isset($this->_params['envelope_sender_address'])) {
399            $envelope_sender_address = sprintf('<%s>', trim($this->_params['envelope_sender_address'], '<>'));
400        } else {
401            $envelope_sender_address = preg_replace('/^.*<?([^\s@\[\]<>()]+\@[A-Za-z0-9.-]{1,}\.[A-Za-z]{2,19})>?$/iU' . $app->getParam('preg_u'), '$1', $this->_params['from']);
402        }
403        if ('' != $envelope_sender_address && $this->validEmail($envelope_sender_address)) {
404            $additional_parameter = sprintf('-f %s', $envelope_sender_address);
405        } else {
406            $additional_parameter = '';
407        }
408
409        // Check for mail header injection attacks.
410        $full_mail_content = join($this->getParam('crlf'), array($final_to, $this->_params['subject'], $final_body));
411        if (preg_match("/(^|[\n\r])(Content-Type|MIME-Version|Content-Transfer-Encoding|Bcc|Cc)\s*:/i", $full_mail_content)) {
412            $app->logMsg(sprintf('Mail header injection attack in content: %s', $full_mail_content), LOG_WARNING, __FILE__, __LINE__);
413            return false;
414        }
415
416        // Enter sandbox mode, if specified.
417        switch ($this->getParam('sandbox_mode')) {
418        case self::SANDBOX_MODE_REDIRECT:
419            if (!$this->getParam('sandbox_to_addr')) {
420                $app->logMsg(sprintf('Email sandbox_mode is SANDBOX_MODE_REDIRECT but sandbox_to_addr is not set.', null), LOG_ERR, __FILE__, __LINE__);
421                break;
422            }
423            $final_to = $this->getParam('sandbox_to_addr');
424            break;
425
426        case self::SANDBOX_MODE_STDERR:
427            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);
428            return true;
429
430        case self::SANDBOX_MODE_LOG:
431            // Temporarily modify log settings to allow full multi-line emails to appear in logs.
432            $log_serialize = $app->getParam('log_serialize');
433            $log_message_max_length = $app->getParam('log_message_max_length');
434            $app->setParam(array('log_serialize' => false, 'log_message_max_length' => 65536));
435            $app->logMsg(sprintf("\nSubject: %s\nTo: %s\n%s\n\n%s", $this->getParam('subject'), $final_to, trim(str_replace($this->getParam('crlf'), "\n", $final_headers)), trim($final_body)), LOG_DEBUG, __FILE__, __LINE__);
436            $app->setParam(array('log_serialize' => $log_serialize, 'log_message_max_length' => $log_message_max_length));
437            return true;
438        }
439
440        // Send email without 5th parameter if safemode is enabled.
441        if (ini_get('safe_mode')) {
442            $ret = mb_send_mail($final_to, $this->_params['subject'], $final_body, $final_headers);
443        } else {
444            $ret = mb_send_mail($final_to, $this->_params['subject'], $final_body, $final_headers, $additional_parameter);
445        }
446
447        // Ensure message was successfully accepted for delivery.
448        if ($ret) {
449            $app->logMsg(sprintf('Email successfully sent to %s', $final_to), LOG_INFO, __FILE__, __LINE__);
450            return true;
451        } else {
452            $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__);
453            return false;
454        }
455    }
456
457    /**
458     * Validates an email address based on the recommendations in RFC 3696.
459     * Is more loose than restrictive, to allow the many valid variants of
460     * email addresses while catching the most common mistakes. Checks an array too.
461     * http://www.faqs.org/rfcs/rfc822.html
462     * http://www.faqs.org/rfcs/rfc2822.html
463     * http://www.faqs.org/rfcs/rfc3696.html
464     * http://www.faqs.org/rfcs/rfc1035.html
465     *
466     * @access  public
467     * @param   mixed  $email  Address to check, string or array.
468     * @return  bool    Validity of address.
469     * @author  Quinn Comendant <quinn@strangecode.com>
470     * @since   30 Nov 2005 22:00:50
471     */
472    public function validEmail($email)
473    {
474        $app =& App::getInstance();
475
476        // If an array, check values recursively.
477        if (is_array($email)) {
478            foreach ($email as $e) {
479                if (!$this->validEmail($e)) {
480                    return false;
481                }
482            }
483            return true;
484        } else {
485            // To be valid email address must match regex and fit within the length constraints.
486            if (preg_match($this->getParam('regex'), $email, $e_parts) && mb_strlen($e_parts[2]) < 64 && mb_strlen($e_parts[3]) < 255) {
487                return true;
488            } else {
489                $app->logMsg(sprintf('Invalid email address: %s', $email), LOG_INFO, __FILE__, __LINE__);
490                return false;
491            }
492        }
493    }
494}
495
Note: See TracBrowser for help on using the repository browser.