WireMailMailgun.module

<?php

/**
 * Class WireMailMailgun
 *
 * @property string apiKey The API key set in config
 * @property string publicApiKey The public API key set in config
 * @property string domain The domain for the API key
 * @property bool batchMode True by default. See setBatchMode() method of this class for more info.
 */
class WireMailMailgun extends WireMail implements Module, ConfigurableModule
{
	private $apiUrl = 'https://api.mailgun.net/v3/';
	private $batchMode = true;
	private $tags = [];
	private $recipientsVariables = [];

	public static function getModuleInfo()
	{
		return array(
			'title' => 'WireMail Mailgun',
			'version' => '0.4.2',
			'summary' => "Mailgun for ProcessWire",
			'href' => 'https://github.com/plauclair/WireMailMailgun',
			'author' => 'plauclair',
			'singular' => false,
			'autoload' => false
		);
	}

	/**
	 *
	 */
	public function ___send()
	{
		$request = curl_init();

		$postFields = [
			'from' => $this->getFrom(),
			'to' => $this->getToRecipients(),
			'subject' => $this->mail['subject'],
			'o:testmode' => $this->isTestMode(),
		];

		// Batch mode variables
		if ($this->batchMode === true) {
			$postFields['recipient-variables'] = $this->getToRecipientsVariables();
		}

		// Set CC recipients
		if ($this->getCCRecipients() !== false) {
			$postFields['cc'] = $this->getCCRecipients();
		}

		// Set BCC recipients
		if ($this->getBCCRecipients() !== false) {
			$postFields['bcc'] = $this->getBCCRecipients();
		}

		// Set body
		if (!empty($this->mail['bodyHTML'])) {
			$postFields['html'] = $this->mail['bodyHTML'];
			// TODO: Replace the next line with something that
			// will output better plain text (break to newline especially)
			$postFields['text'] = (!empty($this->mail['body'])) ? $this->mail['body'] : strip_tags($this->mail['bodyHTML']);
		} else {
			$postFields['text'] = $this->mail['body'];
		}

		// Email Open Tracking
		$postFields['o:tracking-clicks'] = ($this->clickTracking() === true) ? 'yes' : 'no';

		// Email Click tracking
		$postFields['o:tracking-opens'] = ($this->openTracking() === true) ? 'yes' : 'no';

		// Attachments
		if ($this->getAttachments() !== false) {
			$attachmentIndex = 0;
			foreach ($this->getAttachments() as $attachment) {
				if (function_exists('curl_file_create')) {
					// PHP >= 5.5.0
					$postFields["attachment[$attachmentIndex]"] = curl_file_create($attachment);
				} else {
					// PHP < 5.5.0
					$postFields["attachment[$attachmentIndex]"] = "@{$attachment}";
				}
				$attachmentIndex += 1;
			}
		}

		// Headers
		if ($this->getHeaders() !== false) {
			foreach ($this->getHeaders() as $header => $value) {
				$postFields["h:{$header}"] = $value;
			}
		}

		// Tags
		if ($this->getTags() !== false) {
			$tagIndex = 0;
			foreach ($this->getTags() as $tag) {
				$postFields["o:tag[$tagIndex]"] = $tag;
				$tagIndex += 1;
			}
		}

		$options = array(
			CURLOPT_USERPWD => "api:{$this->apiKey}",
			CURLOPT_URL => "{$this->apiUrl}{$this->domain}/messages",
			CURLOPT_HEADER => false,
			CURLOPT_POST => true,
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_POSTFIELDS => $postFields,
			CURLOPT_SSL_VERIFYPEER => $this->sslCheck(),
		);

		curl_setopt_array($request, $options);

		$response = curl_exec($request);

		if ($response === false) {
			// If an error occurred in cURL
			$this->log()->save('mailgun', 'cURL Error: ' . curl_error($request));
			curl_close($request);
			return 0;
		} else {
			$response = json_decode($response);

			$info = curl_getinfo($request);

			curl_close($request);

			switch ($info['http_code']) {
				case 200:
					return true; // Can't set int for number sent, since Mailgun doesn't return that data
					break;
				case 400:
					$this->log()->save('mailgun', "Code 400: Bad Request - {$response->message}.");
					return 0;
					break;
				case 401:
					$usedKey = (!empty($this->apiKey)) ? "API Key: {$this->apiKey}." : 'NO KEY SET.';
					$this->log()->save('mailgun', "Code 401: Unauthorized - No valid API key provided. {$usedKey}");
					return 0;
					break;
				case 402:
					// TODO: Improve this later
					$this->log()->save('mailgun', "Code 402: Request Failed - Parameters were valid but request failed.");
					return 0;
					break;
				case 404:
					$this->log()->save('mailgun', "Code 404: Not Found - The requested item doesn’t exist.");
					return 0;
					break;
				case 500:
					$this->log()->save('mailgun', "Code 500: Mailgun Server Error.");
					return 0;
					break;
				case 502:
					$this->log()->save('mailgun', "Code 502: Mailgun Server Error.");
					return 0;
					break;
				case 503:
					$this->log()->save('mailgun', "Code 503: Mailgun Server Error.");
					return 0;
					break;
				case 504:
					$this->log()->save('mailgun', "Code 504: Mailgun Server Error.");
					return 0;
					break;
			}
		}
	}


	/**
	 * Handles send() when new WireMail() is used instead
	 * of calling wireMail() directly
	 */
	public function send()
	{
		return $this->___send();
	}

	/**
	 * Overrides the Mailgun API Key setting in config
	 *
	 * @param string $apiKey
	 */
	public function setApiKey($apiKey)
	{
		$this->apiKey = $apiKey;
	}

	/**
	 * Overrides the Domain Name setting in config
	 *
	 * @param string $domainName
	 */
	public function setDomainName($domainName)
	{
		$this->domain = $domainName;
	}

	/**
	 * Overrides the Test Mode setting in config
	 *
	 * @param bool $bool
	 */
	public function setTestMode($bool)
	{
		if (is_bool($bool)) {
			$this->testMode = ($bool === true) ? 'testMode' : false;
		}
	}

	/**
	 * Returns if the current instance is used in Test Mode
	 *
	 * @return bool
	 */
	private function isTestMode()
	{
		return ($this->testMode == 'testMode') ? true : false;
	}

	/**
	 * Returns if the current instance disables SSH check
	 *
	 * This can sometimes be needed on some testing environments,
	 * preferably don't use in production
	 *
	 * @return bool
	 */
	private function sslCheck()
	{
		return ($this->disableSslCheck == 'disableSslCheck') ? false : true;
	}


	/**
	 * Get the recipients of the To field in the proper format
	 *
	 * @return string|false
	 */
	private function getToRecipients()
	{
		$recipients = $this->mail['toName'];
		$to = [];

		foreach ($recipients as $email => $name) {
			$to[] = (empty($name)) ? $email : "{$name} <{$email}>";
		}

		return (!empty($to)) ? implode(',', $to) : false;
	}

	/**
	 * Get the recipient variables
	 *
	 * For now, this is used to emulate the default to()
	 * method behavior. Mailgun hard limit on this calling
	 * style is 1000 recipients per request
	 */
	private function getToRecipientsVariables()
	{
		$recipients = $this->mail['toName'];

		$i = 1;
		foreach ($recipients as $email => $name) {
			if (! array_key_exists($email, $this->recipientsVariables)) {
				$this->recipientsVariables[$email] = [];
			}
			$this->recipientsVariables[$email]['id'] = $i;
			$this->recipientsVariables[$email]['name'] = $name;
			$i += 1;
		}

		return json_encode($this->recipientsVariables);
	}

	/**
	 * Set the recipient variables
	 *
	 * Add variables for a batch email.
	 *
	 * @param array $recipientVariables
	 */
	public function setToRecipientsVariables(array $recipientVariables)
	{
		$this->recipientsVariables = $recipientVariables;

		return $this;
	}

	/**
	 * Enables or disables batch mode
	 *
	 * This is on by default, meaning that all emails in the To field won't see the other recipients.
	 */
	public function setBatchMode($bool)
	{
		if (is_bool($bool)) {
			$this->batchMode = $bool;
		}
	}

	/**
	 * Will allow merging an array of emails with
	 * their recipients variables
	 */
	public function mergeToRecipientsVariables()
	{
		// THIS IS A STUB
		// TODO: Implement this..
	}

	/**
	 * Set the email CC address
	 *
	 * Each added email addresses appends to any addresses already supplied, unless
	 * you specify NULL as the email address, in which case it clears them all.
	 *
	 * @param string|array|null $email Specify any ONE of the following:
	 *    1. Single email address or "User Name <user@example.com>" string.
	 *    2. CSV string of #1.
	 *    3. Non-associative array of #1.
	 *    4. Associative array of (email => name)
	 *    5. NULL (default value, to clear out any previously set values)
	 * @param string $name Optionally provide a FROM name, applicable
	 *    only when specifying #1 (single email) for the first argument.
	 * @return WireMail this
	 * @throws WireException if any provided emails were invalid
	 *
	 */
	public function cc($email = null, $name = null)
	{
		if (is_null($email)) {
			// clear existing values
			$this->mail['cc'] = array();
			$this->mail['ccName'] = array();
			return $this;
		}

		$emails = is_array($email) ? $email : explode(',', $email);

		foreach ($emails as $key => $value) {

			$ccName = '';
			if (is_string($key)) {
				// associative array
				// email provided as $key, and $ccName as value 
				$ccEmail = $key;
				$ccName = $value;

			} else if (strpos($value, '<') !== false && strpos($value, '>') !== false) {
				// ccName supplied as: "User Name <user@example.com"
				list($ccEmail, $ccName) = $this->extractEmailAndName($value);

			} else {
				// just an email address, possibly with name as a function arg
				$ccEmail = $value;
			}

			if (empty($ccName)) $ccName = $name; // use function arg if not overwritten
			$ccEmail = $this->sanitizeEmail($ccEmail);
			$this->mail['cc'][$ccEmail] = $ccEmail;
			$this->mail['ccName'][$ccEmail] = $this->sanitizeHeader($ccName);
		}

		return $this;
	}

	/**
	 * Get the recipients of the CC field in the proper format
	 *
	 * @return string|false
	 */
	private function getCCRecipients()
	{
		if (!empty($this->mail['ccName'])) {
			$recipients = $this->mail['ccName'];
			$cc = [];

			foreach ($recipients as $email => $name) {
				$cc[] = (empty($name)) ? $email : "{$name} <{$email}>";
			}

			return (!empty($cc)) ? implode(', ', $cc) : false;
		} else {
			return false;
		}
	}

	/**
	 * Set the email BCC address
	 *
	 * Each added email addresses appends to any addresses already supplied, unless
	 * you specify NULL as the email address, in which case it clears them all.
	 *
	 * @param string|array|null $email Specify any ONE of the following:
	 *    1. Single email address or "User Name <user@example.com>" string.
	 *    2. CSV string of #1.
	 *    3. Non-associative array of #1.
	 *    4. Associative array of (email => name)
	 *    5. NULL (default value, to clear out any previously set values)
	 * @param string $name Optionally provide a FROM name, applicable
	 *    only when specifying #1 (single email) for the first argument.
	 * @return WireMail this
	 * @throws WireException if any provided emails were invalid
	 *
	 */
	public function bcc($email = null, $name = null)
	{
		if (is_null($email)) {
			// clear existing values
			$this->mail['bcc'] = array();
			$this->mail['bccName'] = array();
			return $this;
		}

		$emails = is_array($email) ? $email : explode(',', $email);

		foreach ($emails as $key => $value) {

			$bccName = '';
			if (is_string($key)) {
				// associative array
				// email provided as $key, and $bccName as value 
				$bccEmail = $key;
				$bccName = $value;

			} else if (strpos($value, '<') !== false && strpos($value, '>') !== false) {
				// bccName supplied as: "User Name <user@example.com"
				list($bccEmail, $bccName) = $this->extractEmailAndName($value);

			} else {
				// just an email address, possibly with name as a function arg
				$bccEmail = $value;
			}

			if (empty($bccName)) $bccName = $name; // use function arg if not overwritten
			$bccEmail = $this->sanitizeEmail($bccEmail);
			$this->mail['bcc'][$bccEmail] = $bccEmail;
			$this->mail['bccName'][$bccEmail] = $this->sanitizeHeader($bccName);
		}

		return $this;
	}

	/**
	 * Get the recipients of the BCC field in the proper format
	 *
	 * @return string|false
	 */
	private function getBCCRecipients()
	{
		if (!empty($this->mail['bccName'])) {
			$recipients = $this->mail['bccName'];
			$bcc = [];

			foreach ($recipients as $email => $name) {
				$bcc[] = (empty($name)) ? $email : "{$name} <{$email}>";
			}

			return (!empty($bcc)) ? implode(', ', $bcc) : false;
		} else {
			return false;
		}
	}

	/**
	 * Get the From field in the proper format
	 *
	 * Will use WireMail()->from() if set first,
	 * module settings second and
	 * revert to default if nothing else is set
	 *
	 * @return string|false
	 */
	private function getFrom()
	{
		$fromEmail = $this->fromEmail;
		$fromName = $this->fromName;

		if (!empty($this->mail['from'])) {
			// Set manually
			return (empty($this->mail['fromName'])) ? $this->mail['from'] : "{$this->mail['fromName']} <{$this->mail['from']}>";
		} else if (!empty($fromEmail)) {
			// Set in settings
			return (empty($fromName)) ? "ProcessWire <{$fromEmail}>" : "{$fromName} <{$fromEmail}>";
		} else {
			// Default
			return "ProcessWire <processwire@{$this->domain}>";
		}
	}

	/**
	 * Overrides "click tracking" module settings on a per-email basis
	 *
	 * Note: per Mailgun constraints, click tracking will
	 * only work on HTML emails
	 *
	 * @param bool $bool
	 */
	public function setClickTracking($bool)
	{
		if ($bool === true) {
			$this->trackClicks = 'trackClicks';
		} else if ($bool === false) {
			$this->trackClicks = null;
		}
	}

	/**
	 * Returns whether the current email has click tracking
	 * enabled or not
	 *
	 * @return bool
	 */
	private function clickTracking()
	{
		return ($this->trackClicks == 'trackClicks') ? true : false;
	}

	/**
	 * Overrides "open tracking module" settings on a per-email basis
	 *
	 * Note: per Mailgun constraints, open tracking will
	 * only work on HTML emails
	 *
	 * @param bool $bool
	 */
	public function setOpenTracking($bool)
	{
		if ($bool === true) {
			$this->trackOpens = 'trackOpens';
		} else if ($bool === false) {
			$this->trackOpens = null;
		}
	}

	/**
	 * Returns whether the current email has open tracking
	 * enabled or not
	 *
	 * @return bool
	 */
	private function openTracking()
	{
		return ($this->trackOpens == 'trackOpens') ? true : false;
	}

	/**
	 * Adds an attachment to the email using a file path
	 *
	 * @param string $filePath
	 */
	public function addAttachment($filePath)
	{
		if (realpath($filePath) !== false) {
			$this->mail['attachments'][] = realpath($filePath);
			return true;
		} else {
			return false;
		}
	}

	/**
	 * Gets attachments, or return false if there are none
	 *
	 * @return array|false
	 */
	private function getAttachments()
	{
		if (isset($this->mail['attachments']) and !empty($this->mail['attachments'])) {
			return $this->mail['attachments'];
		} else {
			return false;
		}
	}

	/**
	 * Returns an array of the custom-defined headers
	 *
	 * @return array
	 */
	private function getHeaders()
	{
		if (isset($this->mail['header']) and !empty($this->mail['header'])) {
			return $this->mail['header'];
		} else {
			return false;
		}
	}

	/**
	 * Adds a tag to the email
	 *
	 * Will add up to 3 tags. Any string passed to this
	 * function will be converted to ASCII and trimmed to
	 * be 128 characters long.
	 *
	 * It is STRONGLY recommended that you enable
	 * the PHP 'intl' module if you want correct
	 * UTF-8 to ASCII conversion
	 *
	 * See https://documentation.mailgun.com/user_manual.html#tagging
	 *
	 * @param string $tag
	 */
	public function addTag($tag)
	{
		// check if transliterator_transliterate exists and translit ID is valid on current system
		$transId = 'Any-Latin; Latin-ASCII; [\u0080-\u7fff] remove';
		if (function_exists('transliterator_transliterate') and ($transliterator = \Transliterator::create($transId))) {
			// convert to ASCII
			$transString = $transliterator->transliterate($tag);
		} else {
			// basic fallback to iconv... might be unreliable but kind of works
			$tag = iconv('UTF-8', 'ASCII//TRANSLIT//IGNORE', $tag);
		}

		$tag = trim($tag);
		$tag = substr($tag, 0, 128);

		if (!empty($tag) and count($this->tags) <= 3) {
			$this->tags[] = $tag;
		} else if (count($this->tags) > 3) {
			$this->log()->save('mailgun', "Tags: Tried to use more than 3 tags. Mailgun supports a maximum of 3 at a time.");
		}
	}

	/**
	 * Gets tags, or return false if there are none
	 *
	 * @return array|false
	 */
	private function getTags()
	{
		if (isset($this->tags) and !empty($this->tags)) {
			return $this->tags;
		} else {
			return false;
		}
	}

	/**
	 * Validates a single address using Mailgun's address validation service
	 *
	 * For more information on what this method returns,
	 * visit https://documentation.mailgun.com/api-email-validation.html#email-validation
	 *
	 * return object|false Returns an array of validation data from Mailgun
	 * @param string $email
	 * @return object|false
	 */
	public function validateEmail($email)
	{
		// if public API key isn't set, log that
		if (empty($this->publicApiKey)) {
			$this->log()->save('mailgun', 'The Public API Key must be set when using the email validation feature.');
			return false;
		}

		$email = filter_var($email, FILTER_SANITIZE_STRING);
		// if it fails basic string validation, stop
		if ($email == false){
			return false;
		}
		$email = urlencode($email);

		$request = curl_init();

		$options = array(
			CURLOPT_USERPWD => "api:{$this->publicApiKey}",
			CURLOPT_URL => "{$this->apiUrl}address/validate?address={$email}",
			CURLOPT_HEADER => false,
			CURLOPT_RETURNTRANSFER => true,
			CURLOPT_SSL_VERIFYPEER => $this->sslCheck(),
		);

		curl_setopt_array($request, $options);

		$response = curl_exec($request);

		if ($response === false) {
			// If an error occurred in cURL
			$this->log()->save('mailgun', 'cURL Error: ' . curl_error($request));
			curl_close($request);
			return false;
		} else {
			$response = json_decode($response);

			$info = curl_getinfo($request);

			curl_close($request);

			return $response;
		}
	}
}