class.emailgateway.php

<?php

/**
 * @package toolkit
 */
/**
 * A base class for email gateways.
 * All email-gateways should extend this class in order to work.
 *
 * @todo add validation to all set functions.
 */
abstract class EmailGateway
{
    protected $_recipients = array();
    protected $_sender_name;
    protected $_sender_email_address;
    protected $_subject;
    protected $_body;
    protected $_text_plain;
    protected $_text_html;
    protected $_attachments = array();
    protected $_validate_attachment_errors = true;
    protected $_reply_to_name;
    protected $_reply_to_email_address;
    protected $_header_fields = array();
    protected $_boundary_mixed;
    protected $_boundary_alter;
    protected $_text_encoding = 'quoted-printable';

    /**
     * Indicates whether the connection to the SMTP server should be
     * kept alive, or closed after sending each email. Defaults to false.
     *
     * @since Symphony 2.3.1
     * @var boolean
     */
    protected $_keepalive = false;

    /**
     * The constructor sets the `_boundary_mixed` and `_boundary_alter` variables
     * to be unique hashes based off PHP's `uniqid` function.
     */
    public function __construct()
    {
        $this->_boundary_mixed = '=_mix_'.md5(uniqid());
        $this->_boundary_alter = '=_alt_'.md5(uniqid());
    }

    /**
     * The destructor ensures that any open connections to the Email Gateway
     * is closed.
     */
    public function __destruct()
    {
        $this->closeConnection();
    }

    /**
     * Sends the actual email. This function should be implemented in the
     * Email Gateway itself and should return true or false if the email
     * was successfully sent.
     * See the default gateway for an example.
     *
     * @return boolean
     */
    abstract public function send();

    /**
     * Open new connection to the email server.
     * This function is used to allow persistent connections.
     *
     * @since Symphony 2.3.1
     * @return boolean
     */
    public function openConnection()
    {
        $this->_keepalive = true;
        return true;
    }

    /**
     * Close the connection to the email Server.
     * This function is used to allow persistent connections.
     *
     * @since Symphony 2.3.1
     * @return boolean
     */
    public function closeConnection()
    {
        $this->_keepalive = false;
        return true;
    }

    /**
     * Sets the sender-email and sender-name.
     *
     * @param string $email
     *  The email-address emails will be sent from.
     * @param string $name
     *  The name the emails will be sent from.
     * @throws EmailValidationException
     * @return void
     */
    public function setFrom($email, $name)
    {
        $this->setSenderEmailAddress($email);
        $this->setSenderName($name);
    }

    /**
     * Does some basic checks to validate the
     * value of a header field. Currently only checks
     * if the value contains a carriage return or a new line.
     *
     * @param string $value
     *
     * @return boolean
     */
    protected function validateHeaderFieldValue($value)
    {
        // values can't contains carriage returns or new lines
        $carriage_returns = preg_match('%[\r\n]%', $value);

        return !$carriage_returns;
    }

    /**
     * Sets the sender-email.
     *
     * @throws EmailValidationException
     * @param string $email
     *  The email-address emails will be sent from.
     * @return void
     */
    public function setSenderEmailAddress($email)
    {
        if (!$this->validateHeaderFieldValue($email)) {
            throw new EmailValidationException(__('Sender Email Address can not contain carriage return or newlines.'));
        }

        $this->_sender_email_address = $email;
    }

    /**
     * Sets the sender-name.
     *
     * @throws EmailValidationException
     * @param string $name
     *  The name emails will be sent from.
     * @return void
     */
    public function setSenderName($name)
    {
        if (!$this->validateHeaderFieldValue($name)) {
            throw new EmailValidationException(__('Sender Name can not contain carriage return or newlines.'));
        }

        $this->_sender_name = $name;
    }

    /**
     * Sets the recipients.
     *
     * @param string|array $email
     *  The email-address(es) to send the email to.
     * @throws EmailValidationException
     * @return void
     */
    public function setRecipients($email)
    {
        if (!is_array($email)) {
            $email = explode(',', $email);
            // trim all values
            array_walk($email, function(&$val) {
                return $val = trim($val);
            });
            // remove empty elements
            $email = array_filter($email);
        }

        foreach ($email as $e) {
            if (!$this->validateHeaderFieldValue($e)) {
                throw new EmailValidationException(__('Recipient address can not contain carriage return or newlines.'));
            }
        }

        $this->_recipients = $email;
    }

    /**
     * This functions takes a string to be used as the plaintext
     * content for the Email
     *
     * @todo sanitizing and security checking
     * @param string $text_plain
     */
    public function setTextPlain($text_plain)
    {
        $this->_text_plain = $text_plain;
    }

    /**
     * This functions takes a string to be used as the HTML
     * content for the Email
     *
     * @todo sanitizing and security checking
     * @param string $text_html
     */
    public function setTextHtml($text_html)
    {
        $this->_text_html = $text_html;
    }

    /**
     * This function sets one or multiple attachment files
     * to the email. It deletes all previously attached files.
     *
     * Passing `null` to this function will
     * erase the current values with an empty array.
     *
     * @param string|array $files
     *   Accepts the same parameters format as `EmailGateway::addAttachment()`
     *   but you can also all multiple values at once if all files are
     *   wrap in a array.
     *
     *   Example:
     *   ````
     *   $email->setAttachments(array(
     *      array(
     *          'file' => 'http://example.com/foo.txt',
     *          'charset' => 'UTF-8'
     *      ),
     *      'path/to/your/webspace/foo/bar.csv',
     *      ...
     *   ));
     *   ````
     */
    public function setAttachments($files)
    {
        // Always erase
        $this->_attachments = array();

        // check if we have an input value
        if ($files == null) {
            return;
        }

        // make sure we are dealing with an array
        if (!is_array($files)) {
            $files = array($files);
        }

        // Append each attachment one by one in order
        // to normalize each input
        foreach ($files as $key => $file) {
            if (is_numeric($key)) {
                // key is numeric, assume keyed array or string
                $this->appendAttachment($file);
            } else {
                // key is not numeric, assume key is filename
                // and file is a string, key needs to be preserved
                $this->appendAttachment(array($key => $file));
            }
        }
    }

    /**
     * Appends one file attachment to the attachments array.
     *
     * @since Symphony 3.0.0
     *   The file array can contain a 'cid' key.
     *   When set to true, the Content-ID header field is added with the filename as id.
     *   The file array can contain a 'disposition' key.
     *   When set, it is used in the Content-Disposition header
     * @throws EmailGatewayException if the parameter is not valid.
     *
     * @since Symphony 2.3.5
     *
     * @param string|array $file
     *   Can be a string representing the file path, absolute or relative, i.e.
     *   `'http://example.com/foo.txt'` or `'path/to/your/webspace/foo/bar.csv'`.
     *
     *   Can also be a keyed array. This will enable more options, like setting the
     *   charset used by mail agent to open the file or a different filename.
     *   Only the "file" key is required.
     *
     *   Example:
     *   ````
     *   $email->appendAttachment(array(
     *      'file' => 'http://example.com/foo.txt',
     *      'filename' => 'bar.txt',
     *      'charset' => 'UTF-8',
     *      'mime-type' => 'text/csv',
     *      'cid' => false,
     *      'disposition' => 'inline',
     *   ));
     *   ````
     */
    public function appendAttachment($file)
    {
        if (!is_array($file)) {
            // treat the param as string
            $file = array(
                'file' => $file,
            );

            // is array, but not the right key
        } elseif (!isset($file['file'])) {
            throw new EmailGatewayException('The file key is missing from the attachment array.');
        }

        // push properly formatted file entry
        $this->_attachments[] = $file;
    }

    /**
     * Sets the property `$_validate_attachment_errors`
     *
     * This property is true by default, so sending will break if any attachment
     * can not be loaded; if it is false, attachment errors error will be ignored.
     *
     * @since Symphony 2.7
     * @param boolean $validate_attachment_errors
     * @return void
     */
    public function setValidateAttachmentErrors($validate_attachment_errors)
    {
        if (!is_bool($validate_attachment_errors)) {
            throw new EmailGatewayException(__('%s accepts boolean values only.', array('<code>setValidateAttachmentErrors</code>')));
        } else {
            $this->_validate_attachment_errors = $validate_attachment_errors;
        }
    }

    /**
     * @todo Document this function
     * @throws EmailGatewayException
     * @param string $encoding
     *  Must be either `quoted-printable` or `base64`.
     */
    public function setTextEncoding($encoding = null)
    {
        if ($encoding == 'quoted-printable') {
            $this->_text_encoding = 'quoted-printable';
        } elseif ($encoding == 'base64') {
            $this->_text_encoding = 'base64';
        } elseif (!$encoding) {
            $this->_text_encoding = false;
        } else {
            throw new EmailGatewayException(__('%1$s is not a supported encoding type. Please use %2$s or %3$s. You can also use %4$s for no encoding.', array($encoding, '<code>quoted-printable</code>', '<code>base-64</code>', '<code>false</code>')));
        }
    }

    /**
     * Sets the subject.
     *
     * @param string $subject
     *  The subject that the email will have.
     * @return void
     */
    public function setSubject($subject)
    {
        //TODO: sanitizing and security checking;
        $this->_subject = $subject;
    }

    /**
     * Sets the reply-to-email.
     *
     * @throws EmailValidationException
     * @param string $email
     *  The email-address emails should be replied to.
     * @return void
     */
    public function setReplyToEmailAddress($email)
    {
        if (preg_match('%[\r\n]%', $email)) {
            throw new EmailValidationException(__('Reply-To Email Address can not contain carriage return or newlines.'));
        }

        $this->_reply_to_email_address = $email;
    }

    /**
     * Sets the reply-to-name.
     *
     * @throws EmailValidationException
     * @param string $name
     *  The name emails should be replied to.
     * @return void
     */
    public function setReplyToName($name)
    {
        if (preg_match('%[\r\n]%', $name)) {
            throw new EmailValidationException(__('Reply-To Name can not contain carriage return or newlines.'));
        }

        $this->_reply_to_name = $name;
    }

    /**
     * Sets all configuration entries from an array.
     * This enables extensions like the ENM to create email settings panes that work regardless of the email gateway.
     * Every gateway should extend this method to add their own settings.
     *
     * @throws EmailValidationException
     * @param array $config
     * @since Symphony 2.3.1
     *  All configuration entries stored in a single array. The array should have the format of the $_POST array created by the preferences HTML.
     * @return boolean
     */
    public function setConfiguration($config)
    {
        return true;
    }

    /**
     * Appends a single header field to the header fields array.
     * The header field should be presented as a name/body pair.
     *
     * @throws EmailGatewayException
     * @param string $name
     *  The header field name. Examples are From, Bcc, X-Sender and Reply-to.
     * @param string $body
     *  The header field body.
     * @return void
     */
    public function appendHeaderField($name, $body)
    {
        if (is_array($body)) {
            throw new EmailGatewayException(__('%s accepts strings only; arrays are not allowed.', array('<code>appendHeaderField</code>')));
        }

        $this->_header_fields[$name] = $body;
    }

    /**
     * Appends one or more header fields to the header fields array.
     * Header fields should be presented as an array with name/body pairs.
     *
     * @param array $header_array
     *  The header fields. Examples are From, X-Sender and Reply-to.
     * @throws EmailGatewayException
     * @return void
     */
    public function appendHeaderFields(array $header_array = array())
    {
        foreach ($header_array as $name => $body) {
            $this->appendHeaderField($name, $body);
        }
    }

    /**
     * Makes sure the Subject, Sender Email and Recipients values are
     * all set and are valid. The message body is checked in
     * `prepareMessageBody`
     *
     * @see prepareMessageBody()
     * @throws EmailValidationException
     * @return boolean
     */
    public function validate()
    {
        if (strlen(trim($this->_subject)) <= 0) {
            throw new EmailValidationException(__('Email subject cannot be empty.'));
        } elseif (strlen(trim($this->_sender_email_address)) <= 0) {
            throw new EmailValidationException(__('Sender email address cannot be empty.'));
        } elseif (!filter_var($this->_sender_email_address, FILTER_VALIDATE_EMAIL)) {
            throw new EmailValidationException(__('Sender email address must be a valid email address.'));
        } else {
            foreach ($this->_recipients as $address) {
                if (strlen(trim($address)) <= 0) {
                    throw new EmailValidationException(__('Recipient email address cannot be empty.'));
                } elseif (!filter_var($address, FILTER_VALIDATE_EMAIL)) {
                    throw new EmailValidationException(__('The email address ‘%s’ is invalid.', array($address)));
                }
            }
        }

        return true;
    }

    /**
     * Build the message body and the content-describing header fields
     *
     * The result of this building is an updated body variable in the
     * gateway itself.
     *
     * @throws EmailGatewayException
     * @throws Exception
     * @return boolean
     */
    protected function prepareMessageBody()
    {
        $attachments = $this->getSectionAttachments();
        if ($attachments) {
            $this->appendHeaderFields($this->contentInfoArray('multipart/mixed'));
            if (!empty($this->_text_plain) && !empty($this->_text_html)) {
                $this->_body = $this->boundaryDelimiterLine('multipart/mixed')
                            . $this->contentInfoString('multipart/alternative')
                            . $this->getSectionMultipartAlternative()
                            . $attachments
                ;
            } elseif (!empty($this->_text_plain)) {
                $this->_body = $this->boundaryDelimiterLine('multipart/mixed')
                            . $this->contentInfoString('text/plain')
                            . $this->getSectionTextPlain()
                            . $attachments
                ;
            } elseif (!empty($this->_text_html)) {
                $this->_body = $this->boundaryDelimiterLine('multipart/mixed')
                            . $this->contentInfoString('text/html')
                            . $this->getSectionTextHtml()
                            . $attachments
                ;
            } else {
                $this->_body = $attachments;
            }
            $this->_body .= $this->finalBoundaryDelimiterLine('multipart/mixed');
        } elseif (!empty($this->_text_plain) && !empty($this->_text_html)) {
            $this->appendHeaderFields($this->contentInfoArray('multipart/alternative'));
            $this->_body = $this->getSectionMultipartAlternative();
        } elseif (!empty($this->_text_plain)) {
            $this->appendHeaderFields($this->contentInfoArray('text/plain'));
            $this->_body = $this->getSectionTextPlain();
        } elseif (!empty($this->_text_html)) {
            $this->appendHeaderFields($this->contentInfoArray('text/html'));
            $this->_body = $this->getSectionTextHtml();
        } else {
            throw new EmailGatewayException(__('No attachments or body text was set. Can not send empty email.'));
        }
    }

    /**
     * Build multipart email section. Used by sendmail and smtp classes to
     * send multipart email.
     *
     * Will return a string containing the section. Can be used to send to
     * an email server directly.
     * @return string
     */
    protected function getSectionMultipartAlternative()
    {
        $output = $this->boundaryDelimiterLine('multipart/alternative')
                . $this->contentInfoString('text/plain')
                . $this->getSectionTextPlain()
                . $this->boundaryDelimiterLine('multipart/alternative')
                . $this->contentInfoString('text/html')
                . $this->getSectionTextHtml()
                . $this->finalBoundaryDelimiterLine('multipart/alternative')
        ;

        return $output;
    }

    /**
     * Builds the attachment section of a multipart email.
     *
     * Will return a string containing the section. Can be used to send to
     * an email server directly.
     *
     * @throws EmailGatewayException
     * @throws Exception
     * @return string
     */
    protected function getSectionAttachments()
    {
        $output = '';

        foreach ($this->_attachments as $key => $file) {
            $tmp_file = false;

            // If the attachment is a URL, download the file to a temporary location.
            // This prevents downloading the file twice - once for info, once for data.
            if (filter_var($file['file'], FILTER_VALIDATE_URL)) {
                $gateway = new Gateway();
                $gateway->init($file['file']);
                $gateway->setopt('TIMEOUT', 30);
                $file_content = $gateway->exec();

                $tmp_file = tempnam(TMP, 'attachment');
                General::writeFile($tmp_file, $file_content, Symphony::Configuration()->get('write_mode', 'file'));

                $original_filename = $file['file'];
                $file['file'] = $tmp_file;

                // Without this the temporary filename will be used. Ugly!
                if (is_null($file['filename'])) {
                    $file['filename'] = basename($original_filename);
                }
            } else {
                $file_content = file_get_contents($file['file']);
            }

            if ($file_content !== false && !empty($file_content)) {
                $output .= $this->boundaryDelimiterLine('multipart/mixed')
                     . $this->contentInfoString(
                            isset($file['mime-type']) ? $file['mime-type'] : null,
                            $file['file'],
                            isset($file['filename']) ? $file['filename'] : null,
                            isset($file['charset']) ? $file['charset'] : null,
                            isset($file['cid']) ? $file['cid'] : null,
                            isset($file['disposition']) ? $file['disposition'] : 'attachment'
                        )
                     . EmailHelper::base64ContentTransferEncode($file_content);
            } else {
                if ($this->_validate_attachment_errors) {
                    if (!$tmp_file === false) {
                        $filename = $original_filename;
                    } else {
                        $filename = $file['file'];
                    }

                    throw new EmailGatewayException(__('The content of the file `%s` could not be loaded.', array($filename)));
                }
            }

            if (!$tmp_file === false) {
                General::deleteFile($tmp_file);
            }
        }
        return $output;
    }

    /**
     * Builds the text section of a text/plain email.
     *
     * Will return a string containing the section. Can be used to send to
     * an email server directly.
     * @return string
     */
    protected function getSectionTextPlain()
    {
        if ($this->_text_encoding == 'quoted-printable') {
            return EmailHelper::qpContentTransferEncode($this->_text_plain)."\r\n";
        } elseif ($this->_text_encoding == 'base64') {
            // don't add CRLF if using base64 - spam filters don't
            // like this
            return EmailHelper::base64ContentTransferEncode($this->_text_plain);
        }

        return $this->_text_plain."\r\n";
    }

    /**
     * Builds the html section of a text/html email.
     *
     * Will return a string containing the section. Can be used to send to
     * an email server directly.
     * @return string
     */
    protected function getSectionTextHtml()
    {
        if ($this->_text_encoding == 'quoted-printable') {
            return EmailHelper::qpContentTransferEncode($this->_text_html)."\r\n";
        } elseif ($this->_text_encoding == 'base64') {
            // don't add CRLF if using base64 - spam filters don't
            // like this
            return EmailHelper::base64ContentTransferEncode($this->_text_html);
        }
        return $this->_text_html."\r\n";
    }

    /**
     * Builds the right content-type/encoding types based on file and
     * content-type.
     *
     * Will try to match a common description, based on the $type param.
     * If nothing is found, will return a base64 attached file disposition.
     *
     * Can be used to send to an email server directly.
     *
     * @param string $type optional mime-type
     * @param string $file optional the path of the attachment
     * @param string $filename optional the name of the attached file
     * @param string $charset optional the charset of the attached file
     * @param string|boolean $cid optional add a Content-ID header field. If true, uses the filename as the cid
     * @param string $disposition optional the value of the Content-Disposition header field
     *
     * @return array
     */
    public function contentInfoArray($type = null, $file = null, $filename = null, $charset = null, $cid = false, $disposition = 'attachment')
    {
        // Common descriptions
        $description = array(
            'multipart/mixed' => array(
                'Content-Type' => 'multipart/mixed; boundary="'
                                  .$this->getBoundary('multipart/mixed').'"',
            ),
            'multipart/alternative' => array(
                'Content-Type' => 'multipart/alternative; boundary="'
                                  .$this->getBoundary('multipart/alternative').'"',
            ),
            'text/plain' => array(
                'Content-Type'              => 'text/plain; charset=UTF-8',
                'Content-Transfer-Encoding' => $this->_text_encoding ? $this->_text_encoding : '8bit',
            ),
            'text/html' => array(
                'Content-Type'              => 'text/html; charset=UTF-8',
                'Content-Transfer-Encoding' => $this->_text_encoding ? $this->_text_encoding : '8bit',
            ),
        );

        // Try common
        if (!empty($type) && !empty($description[$type])) {
            // return it if found
            return $description[$type];
        }

        // assure we have a file name
        $filename = !is_null($filename) ? $filename : basename($file);

        // Format charset for insertion in content-type, if needed
        if (!empty($charset)) {
            $charset = sprintf('charset=%s;', $charset);
        } else {
            $charset = '';
        }
        // if the mime type is not set, try to obtain using the getMimeType
        if (empty($type)) {
            //assume that the attachment mimetime is appended
            $type = General::getMimeType($file);
        }
        // Return binary description
        $bin = [
            'Content-Type'              => $type.';'.$charset.' name="'.$filename.'"',
            'Content-Transfer-Encoding' => 'base64',
        ];
        if ($disposition) {
            $bin['Content-Disposition'] = $disposition . '; filename="' .$filename .'"';
        }
        if ($cid) {
            $bin['Content-ID'] = $cid === true ? "<$filename>" : $cid;
        }
        return $bin;
    }

    /**
     * Creates the properly formatted InfoString based on the InfoArray.
     *
     * @see EmailGateway::contentInfoArray()
     *
     * @return string|null
     */
    protected function contentInfoString($type = null, $file = null, $filename = null, $charset = null, $cid = false, $disposition = 'attachment')
    {
        $data = $this->contentInfoArray($type, $file, $filename, $charset, $cid, $disposition);
        $fields = array();

        foreach ($data as $key => $value) {
            $fields[] = EmailHelper::fold(sprintf('%s: %s', $key, $value));
        }

        return !empty($fields) ? implode("\r\n", $fields)."\r\n\r\n" : null;
    }

    /**
     * Returns the bondary based on the $type parameter
     *
     * @param string $type the multipart type
     * @return string|void
     */
    protected function getBoundary($type)
    {
        switch ($type) {
            case 'multipart/mixed':
                return $this->_boundary_mixed;
            case 'multipart/alternative':
                return $this->_boundary_alter;
        }
    }

    /**
     * @param string $type
     * @return string
     */
    protected function boundaryDelimiterLine($type)
    {
        // As requested by RFC 2046: 'The CRLF preceding the boundary
        // delimiter line is conceptually attached to the boundary.'
        return $this->getBoundary($type) ? "\r\n--".$this->getBoundary($type)."\r\n" : null;
    }

    /**
     * @param string $type
     * @return string
     */
    protected function finalBoundaryDelimiterLine($type)
    {
        return $this->getBoundary($type) ? "\r\n--".$this->getBoundary($type)."--\r\n" : null;
    }

    /**
     * Sets a property.
     *
     * Magic function, supplied by php.
     * This function will try and find a method of this class, by
     * camelcasing the name, and appending it with set.
     * If the function can not be found, an exception will be thrown.
     *
     * @param string $name
     *  The property name.
     * @param string $value
     *  The property value;
     * @throws EmailGatewayException
     * @return void|boolean
     */
    public function __set($name, $value)
    {
        if (method_exists(get_class($this), 'set'.$this->__toCamel($name, true))) {
            return $this->{'set'.$this->__toCamel($name, true)}($value);
        } else {
            throw new EmailGatewayException(__('The %1$s gateway does not support the use of %2$s', array(get_class($this), $name)));
        }
    }

    /**
     * Gets a property.
     *
     * Magic function, supplied by php.
     * This function will attempt to find a variable set with `$name` and
     * returns it. If the variable is not set, it will return false.
     *
     * @since Symphony 2.2.2
     * @param string $name
     *  The property name.
     * @return boolean|mixed
     */
    public function __get($name)
    {
        return isset($this->{'_'.$name}) ? $this->{'_'.$name} : false;
    }

    /**
     * The preferences to add to the preferences pane in the admin area.
     *
     * @return XMLElement
     */
    public function getPreferencesPane()
    {
        return new XMLElement('fieldset');
    }

    /**
     * Internal function to turn underscored variables into camelcase, for
     * use in methods.
     * Because Symphony has a difference in naming between properties and
     * methods (underscored vs camelcased) and the Email class uses the
     * magic __set function to find property-setting-methods, this
     * conversion is needed.
     *
     * @param string $string
     *  The string to convert
     * @param boolean $caseFirst
     *  If this is true, the first character will be uppercased. Useful
     *  for method names (setName).
     *  If set to false, the first character will be lowercased. This is
     *  default behaviour.
     * @return string
     */
    private function __toCamel($string, $caseFirst = false)
    {
        $string = strtolower($string);
        $a = explode('_', $string);
        $a = array_map('ucfirst', $a);

        if (!$caseFirst) {
            $a[0] = lcfirst($a[0]);
        }

        return implode('', $a);
    }

    /**
     * The reverse of the __toCamel function.
     *
     * @param string $string
     *  The string to convert
     * @return string
     */
    private function __fromCamel($string)
    {
        $string[0] = strtolower($string[0]);

        return preg_replace_callback('/([A-Z])/', function($c) {
            return "_" . strtolower($c[1]);
        }, $string);
    }
}