Takes an email template and an obj of any DataItem class and sends email to a list of recipients after substituting merge codes for values from the obj. More...

Public Member Functions
	EmailManager ($item, $emailTemplate, $onSendComplete="")

	mergeEmail ()
	Use MergeCodeManager, which shares functionality with TextLookup. More...

	getRecipients ()

	sendEmail ()

	sendOneEmail ($recipient)

Static Public Member Functions
static	registerTransport ($mode, $class)
	Registers an email transport handler. More...

static	createTransport ($mode=null)

static	getTransportModes ()

static	registerSMTPTransport ()

static	registerSettingsFormExtension ()

static	settingsExtension ($form)

static	send ($source, $name, $onSendComplete="")
	Sends an email template, based on the supplied DataItem (or array of DataItems) More...

static	setDefaults ()

static	upgradeComponent ($version)

static	scanDebugLogs ()

static	registerSerializationHandler ()

Public Attributes
	$emailTemplate

	$item

	$recipients

	$message

	$subject

	$emailFrom

	$emailName
	The name of the email sender (optional) More...

	$emailTemplateName
	The name of the email template. More...

	$onSendComplete

	$attachments
	optional - array of files to attach to the email More...

Static Public Attributes
static	$transports = null

Detailed Description

Takes an email template and an obj of any DataItem class and sends email to a list of recipients after substituting merge codes for values from the obj.

For example: message text "Dear [first_name]" becomes Dear John Smith

@item: obj of DataItem class that has the field values to be used in the email (e.g., user, program, order).

@emailTemplate: instance of DataItem EmailTemplate. This can be an instance constructed on the fly rather than retrieved from the db. If constructed, the following fields must be set: recipients subject message class_name

@onSendComplete: optional callback function to record the email that was sent in a log.

The following var are set in function mergeEmail after the MergeCodeManager performs the substitutions:

recipients subject message

Definition at line 393 of file email_manager.inc.

Member Function Documentation

◆ createTransport()

static EmailManager::createTransport ( $mode = null )

static

Parameters

string $mode (optional) the specific email transport required. Defaults to the selected email transport.

Returns: AbstractEmailTransport

Definition at line 417 of file email_manager.inc.

      {
           if (EmailManager::$transports == null)
           {
                ComponentManager::fireEvent("RegisterEmailTransport");
           }
           
           if (!$mode)
           {
                $mode = Settings::getValue("email", "transport_mode");
           }
           
           $class = EmailManager::$transports[$mode];
           return new $class;
      }

◆ EmailManager()

EmailManager::EmailManager	(	$item,
		$emailTemplate,
		$onSendComplete = `""`
	)

Definition at line 471 of file email_manager.inc.

      {
           $this->item = clone($item);
           $this->item->filter = null;
           $this->emailTemplate = $emailTemplate;
           $this->emailTemplateName = ($this->item) ? $this->item->format($emailTemplate->name) : $emailTemplate->name;
           $this->emailFrom = ($this->item) ? $this->item->format($emailTemplate->sender_email) : $emailTemplate->sender_email;
           $this->mergeEmail();
           $this->onSendComplete = $onSendComplete;
      }

◆ getRecipients()

EmailManager::getRecipients ( )

Definition at line 520 of file email_manager.inc.

      {
           $validRecipients = array();
           
           trace("EmailManager:getRecipients {$this->recipients}", 3);
           if($this->recipients)
           {
                $recipients = explode(",", $this->recipients);
                if(count($recipients) > 0)
                {
                     foreach($recipients as $recipient)
                     {
                          if(preg_match('/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}\b/i', $recipient))
                               $validRecipients[] = $recipient;
                          else
                               trace("EmailManager:getRecipients invalid recipient $recipient", 3);                      
                     }
                }
           }
  
           return $validRecipients;
      }

◆ getTransportModes()

static EmailManager::getTransportModes ( )

static

Definition at line 433 of file email_manager.inc.

      {
           if (EmailManager::$transports == null)
           {
                ComponentManager::fireEvent("RegisterEmailTransport");
           }
           
           return array_keys(EmailManager::$transports);
      }

◆ mergeEmail()

EmailManager::mergeEmail ( )

Use MergeCodeManager, which shares functionality with TextLookup.

Definition at line 508 of file email_manager.inc.

      {
           $emailText = $this->emailTemplate->recipients . $this->emailTemplate->subject . $this->emailTemplate->message;
           $mgr = new MergeCodeManager($this->item, $emailText, $this->emailTemplate->class_name);
      
           $fields = array("recipients", "subject", "message");
           foreach($fields as $field)
                $this->$field = $mgr->searchAndReplace($this->emailTemplate->$field); 
           
           $this->message = $this->cleanupTemplateOutput($this->message);
      }    

◆ registerSerializationHandler()

static EmailManager::registerSerializationHandler ( )

static

Definition at line 702 of file email_manager.inc.

      {
           SerializationManager::registerHandler("email_templates", "Email Templates", new SimpleSerializationHandler(EmailTemplate));
           SerializationManager::registerHandler("merge_codes", "Merge Codes", new SimpleSerializationHandler(MergeCode));
           return true;        
      }

◆ registerSettingsFormExtension()

static EmailManager::registerSettingsFormExtension ( )

static

Definition at line 448 of file email_manager.inc.

      {
           SettingsManager::registerExtension("email", array(EmailManager, settingsExtension));
      }

◆ registerSMTPTransport()

static EmailManager::registerSMTPTransport ( )

static

Definition at line 443 of file email_manager.inc.

      {
           EmailManager::registerTransport("SMTP", 'SMTPEmailTransport');
      }

◆ registerTransport()

static EmailManager::registerTransport	(	$mode,
		$class
	)

static

Registers an email transport handler.

Parameters

string	$mode	identifying mode name for the transport handler
string	$class	name of the class providing the transport. This must derive from AbstractEmailTransport

Definition at line 402 of file email_manager.inc.

      {
           if (!EmailManager::$transports)
           {
                EmailManager::$transports = array();
           }
           
           EmailManager::$transports[$mode] = $class;
      }

◆ scanDebugLogs()

static EmailManager::scanDebugLogs ( )

static

Definition at line 669 of file email_manager.inc.

      {
           $path = Settings::getValue("email", "debugging_mode_output_path");
      
           $logs = array();
           
           trace("EmailManager::Scanning $path", 3);
  
           $handle = opendir($path);
           
           if(!$handle)
                return;
                
           $idx = 0;
           while(false !== ($file = readdir($handle)))
           {
                // omit "." and ".." in the directory
                if (!preg_match("/(^\.{1,2}$)/i", $file))
                {
                     $log = new EmailDebugLog();
                     $log->log_id = $idx;
                     $log->filename = $file;
                     $log->date = date("F d, Y g:ia", (filemtime($path . DIRECTORY_SEPARATOR . $file)));
                     $logs[$log->log_id] = $log;
                     $idx++;
                }
           }
               
          closedir($handle);
           
          return $logs;
      }

◆ send()

static EmailManager::send	(	$source,
		$name,
		$onSendComplete = `""`
	)

static

Sends an email template, based on the supplied DataItem (or array of DataItems)

Parameters

mixed	$source	either a single DataItem, or an array of DataItems
string	$name	the identifier of the email template
callable	$onSendComplete	callback handler to be called after all generated emails have been sent

Returns: number|boolean

Definition at line 593 of file email_manager.inc.

      {
           $emailTemplate = EmailTemplate::getEmailTemplate($name);
  
           if($emailTemplate)
           {
                if (is_array($source))
                {
                     $sendingItem = new JoinResult();
                     foreach($source as $item)
                     {
                          $cl = get_class($item);
                          $sendingItem->$cl = $item;
                     }
                }
                else
                {
                     $sendingItem = $source;
                }
                
                trace("Sending email '$name'", 3);
                $emailManager = new EmailManager($sendingItem, $emailTemplate, $onSendComplete);
                $rtn = $emailManager->sendEmail();
                trace("EmailManager:: rtn code $rtn", 3);
           }
           else
           {
                $rtn = 0;
                trace("EmailManager::no template found", 3);
           }
           return $rtn;
      }    

◆ sendEmail()

EmailManager::sendEmail ( )

Definition at line 550 of file email_manager.inc.

      {
           $recipients = $this->getRecipients();
           $rtn = false;
           
           if(count($recipients) > 0)
           {
                foreach($recipients as $recipient)
                {
                     $rtn = $this->sendOneEmail($recipient);
                }
           }
           else
           {
                trace("EmailManager:: Warning - no valid recipients", 3);
           }
           return $rtn;
      }

◆ sendOneEmail()

EmailManager::sendOneEmail ( $recipient )

Definition at line 569 of file email_manager.inc.

      {
           trace("EmailManager:: sending email to recipient $recipient", 3);
                     
           $email = new EmailHandler($recipient, $this->subject, $this->message, $this->emailFrom, $this->emailName, $this->attachments);
                
           $rtn = $email->send();
                
           if ($this->onSendComplete AND is_callable($this->onSendComplete))
           {
                call_user_func($this->onSendComplete, $this, $recipient, $rtn);
           }              
           
           EmailLog::logEmail($this, $recipient, $rtn);
           return $rtn;
      }

◆ setDefaults()

static EmailManager::setDefaults ( )

static

Definition at line 626 of file email_manager.inc.

      {
           trace("EmailManager::setDefaults", 3);
           
           global $config;
           
           Settings::setDefaultValue("email", "transport_mode", "SMTP", "String", "Specifies the mail transport for system generated emails", "Mail Transport", null, 0);
           
           Settings::setDefaultValue("email", "use_debugging_mode", false, "Boolean", "Enable local logging of generated emails (instead of sending via SMTP)", "Debugging Mode", null, 0);
           
           $defaultPath = $config['uploadbase'] . DIRECTORY_SEPARATOR . "email_debug_logs";
           
           if (!file_exists($defaultPath)) mkdir($defaultPath);
           
           Settings::setDefaultValue("email", "debugging_mode_output_path", $defaultPath, "String", "Folder that will store the logged emails in debugging mode", "Debugging Mode", null, 1);
           Settings::setDefaultValue("email", "email_from", "andy@sonjara.com", "String", "Default From address for generated emails", "Contact Details", null, 1);
           Settings::setDefaultValue("email", "email_contact", "andy@sonjara.com", "String", "Default To address for generated emails", "Contact Details", null, 2);
           Settings::setDefaultValue("email", "email_name", "Andy Green", "String", "Default Name of email contact for generated emails", "Contact Details", null, 3);
           Settings::setDefaultValue("email", "default_contact_us_recipient", "", "String", "Default email address(es) that will receive messages from the Contact Us form. These are used if no Contact Topics are defined", "Contact Details", null, 4);
           Settings::setDefaultValue("email", "use_captcha", "Never", String, "Specify when to use a Captcha to verify the user", "Contact Details", "Never\nAnonymous Only\nAlways", 5);
           Settings::setDefaultValue("email", "HTML_email_base_url", "", String, "", "Contact Details", null, 6);
           
           Settings::setDefaultValue("email", "override_PHP_settings", false, Boolean, "Use these server settings instead of the global settings in your php.ini file", "Server Settings", 0);
           Settings::setDefaultValue("email", "mail_server", "localhost", "String", "Host name or IP address of your upstream SMTP server", "Server Settings", "", 1);
           Settings::setDefaultValue("email", "mail_server_port", 25, Number, "Port to use on the upstream SMTP server", "Server Settings", "", 2);
           Settings::setDefaultValue("email", "username", "", String, "SMTP Account username (if authentication is required)", "Server Settings", "", 3);
           Settings::setDefaultValue("email", "password", "", String, "SMTP Account password (if authentication is required)", "Server Settings", "", 4);
           
           Settings::setDefaultValue("email", "log_messages", false, Boolean, "Log messages in the database after sending", "Message Logging", "", 1);
           Settings::setDefaultValue("email", "log_message_bodies", false, Boolean, "Specifies whether to store the message text when logging an email message. ".
                                                                                                      "It is recommended to leave this unchecked to conserve space in the database.", "Message Logging", "", 2);
      }    

◆ settingsExtension()

static EmailManager::settingsExtension ( $form )

static

Definition at line 453 of file email_manager.inc.

      {
           $transports = EmailManager::getTransportModes();
           $options = array_combine($transports, $transports);
           $form->dropdown("transport_mode", "Selected Transport Mode", $options);
      }

◆ upgradeComponent()

static EmailManager::upgradeComponent ( $version )

static

Definition at line 659 of file email_manager.inc.

      {
           $mgr = new EmailUpgradeManager();
           $mgr->upgrade($version);
      }    

Member Data Documentation

◆ $attachments

EmailManager::$attachments

optional - array of files to attach to the email

Definition at line 469 of file email_manager.inc.

◆ $emailFrom

EmailManager::$emailFrom

Definition at line 465 of file email_manager.inc.

◆ $emailName

EmailManager::$emailName

The name of the email sender (optional)

Definition at line 466 of file email_manager.inc.

◆ $emailTemplate

EmailManager::$emailTemplate

Definition at line 460 of file email_manager.inc.

◆ $emailTemplateName

EmailManager::$emailTemplateName

The name of the email template.

Definition at line 467 of file email_manager.inc.

◆ $item

EmailManager::$item

Definition at line 461 of file email_manager.inc.

◆ $message

EmailManager::$message

Definition at line 463 of file email_manager.inc.

◆ $onSendComplete

EmailManager::$onSendComplete

Definition at line 468 of file email_manager.inc.

◆ $recipients

EmailManager::$recipients

Definition at line 462 of file email_manager.inc.

◆ $subject

EmailManager::$subject

Definition at line 464 of file email_manager.inc.

◆ $transports

EmailManager::$transports = null

static

Definition at line 395 of file email_manager.inc.

The documentation for this class was generated from the following file:

C:/code/cms.sonjara.com/cms/components/email/email_manager.inc

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Member Function Documentation

◆ createTransport()

◆ EmailManager()

◆ getRecipients()

◆ getTransportModes()

◆ mergeEmail()

◆ registerSerializationHandler()

◆ registerSettingsFormExtension()

◆ registerSMTPTransport()

◆ registerTransport()

◆ scanDebugLogs()

◆ send()

◆ sendEmail()

◆ sendOneEmail()

◆ setDefaults()

◆ settingsExtension()

◆ upgradeComponent()

Member Data Documentation

◆ $attachments

◆ $emailFrom

◆ $emailName

◆ $emailTemplate

◆ $emailTemplateName

◆ $item

◆ $message

◆ $onSendComplete

◆ $recipients

◆ $subject

◆ $transports