Basic Enterprise Application Realm

Basic Enterprise Application Realm Documentation
  • 1 PHP Reference
    • 1.1 Introduction
    • 1.2 shared_lib.php
    • 1.3 ac_tables.php
    • 1.4 ac_email.php
  • 2 Javascript Reference
    • 2.1 Introduction
    • 2.2 ac_ajax
    • 2.3 ac_event
    • 2.4 ac_filter
    • 2.5 ac_menu
    • 2.6 ac_panel
    • 2.7 ac_select
    • 2.8 ac_toc
  • 3 Forms
    • 3.1 Introduction
    • 3.2 How It Works
    • 3.3 AJAX
    • 3.4 form_processor_v2
    • 3.5 form_processor

1.4 ac_email.php

January 22nd, 2026

Contents

1.4.1 Introduction

This class is not compatible with Microsoft Windows. It must be used with the AC Hosting Environment version of BEAR.

ac_email provides an object interface for managing the sending of email. It automatically takes care of the fine details of multilingual header and body encoding to suite each language's most common practices (which are generally not UTF-8, which has limited support for email in many clients). In addition, it supports attachments, HTML email, email templates, and message priority. Each instance of the object acts as a living message state where any variable of the message can be altered. This makes it a powerful tool for handling bulk commercial email as it allows a message to be setup and then repeatedly called with different recipients or with minor substitutions to the template.

You will need to ensure that your firewall allows outbound email from a mail server as well as acquiring a non-domestic static IP address. Failure to satisfy these will generally result in email being blocked locally (firewall) or rejected by recipients who's mail servers use the Spamhaus blacklist (which does not allow dynamic or domestic IP addresses).

To use ac_email it must be instantiated as an object in your PHP code:

$email=new ac_email('configuration_path','language_code');

For example, to create an instance of the class which supports Japanese, you might create the object like this:

$email=new ac_email('/bear/web_applications/email','ja');

1.4.2 Prerequisites

ac_email is not a standalone class. It requires that BEAR be running on the Asia Comtek Hosting Environment and also requires access to a dedicated configuration directory structure which should contain configuration files for each language that ac_email will be supporting.

The location of the configuration directory structure is not hard-coded. This is something that is passed as an argument when instantiating an ac_email object. However, the structure itself and the files it contains are strictly defined and ac_email will die with a fatal error if expected resources are not found. The basic rules for the directory structure are:

  • It should contain subdirectories that use 2 character language codes corresponding to BEAR package language codes (such as "en" for English or "de" for German).
  • Each language subdirectory must contain the language settings file config.ini .
  • Each language subdirectory shall be the implicit location for all email template files which must be saved as .xml files

in the previous code example, when the object was created with the following code:

$email=new ac_email('/bear/web_applications/email','ja');

It will cause ac_email to search for a file at /bear/web_applications/email/ja/config.ini .

The config.ini file

The locale specific configuration is defined in an INI file using the following parameters:

Group Key Purpose
header_encoding Defines the character encoding used for strings in the message header (such as the subject).
header_lpad Defines the opening prefix string for headers if applicable to the locale.
header_rpad Defines the trailing suffix string for headers if applicable to the locale.
header_base64 Indicates "yes" or "no" to whether headers need additional Base 64 encoding.
attachment_encoding Defines the character encoding used for attachment file names.
attachment_lpad Defines the opening prefix string for attachment file names if applicable to the locale.
attachment_rpad Defines the trailing suffix string for attachment file names if applicable to the locale.
attachment_base64 Indicates "yes" or "no" to whether attachment file names need additional Base 64 encoding.
attachment_quoted-printable Indicates "yes" or "no" to whether attachments encoding is "quoted-printable".
filename_encoding Defines the character encoding used for linked file names.
filename_lpad Defines the opening prefix string for linked file names if applicable to the locale.
filename_rpad Defines the trailing suffix string for linked file names if applicable to the locale.
filename_base64 Indicates "yes" or "no" to whether linked file names need additional Base 64 encoding.
filename_quoted-printable Indicates "yes" or "no" to whether linked file encoding is "quoted-printable".
text body_content-type For messages in plain text mode, this defines the content body type.
text body_content-transfer-encoding For messages in plain text mode, this defines the content transfer encoding.
text body_encoding For messages in plain text mode, this defines the character encoding.
html body_content-type For messages in HTML mode, this defines the content body type.
html body_content-transfer-encoding For messages in HTML mode, this defines the content transfer encoding.
html body_encoding For messages in HTML mode, this defines the character encoding.

Example

The following is the actual file for English in the en directory:

header_encoding="ISO-8859-1" header_lpad="" header_rpad="" header_base64="no" attachment_encoding="ISO-8859-1" attachment_lpad="" attachment_rpad="" attachment_base64="no" attachment_quoted-printable="no" filename_encoding="ISO-8859-1" filename_lpad="" filename_rpad="" filename_base64="no" filename_quoted-printable="no" [text] body_content-type="text/plain; charset=iso-8859-1" body_content-transfer-encoding="7bit" body_encoding="ISO-8859-1" [html] body_content-type="text/html; charset=iso-8859-1" body_content-transfer-encoding="7bit" body_encoding="ISO-8859-1"

The template .xml files

Using email templates is by far the easiest way to handle common pro-forma emails. These are defined as XML files with a set structure with no schema validation.

Tag Repetition Attributes Content
email 1 The root element.
from 0,1 Defines the From header.
address 1 The email address where this email should originate From in the header.
text 0,1 replacement indicates "yes" or "no" whether text substitutions are required. The text of the From address such as a person or company name.
reply 0,1 Defines the Reply-To header.
address 1 The email address where this email should appear to come from in the Reply-To header.
text 0,1 replacement indicates "yes" or "no" whether text substitutions are required. The text of the Reply-To address such as a person or company name.
subject 0,1 Defines the Subject header.
text 1 replacement indicates "yes" or "no" whether text substitutions are required. The text of the email's subject line.
body 0,1 type indicates the format as "html" or "text" Defines the message body content.
text 1 replacement indicates "yes" or "no" whether text substitutions are required. Defines the payload of the email body.
replacements 0,1 Defines the list of strings which are valid text substitution markers in the email.
item 1,n... Defines a single string as a text substitution marker.
attachment 0,n... source indicates whether the file will come from a "link" on the local system or as embedded "data" in the template file. truename contains the path of a file in the ac_email config path to be attached to the email. Defines a file attachment. If source is "link" then the truename attribute is expected.
filename 1 Defines the file name that you want to appear in the email irrespective of the source file.
data 0,1 If the attachment[source] is defined as "data" then this is mandatory. This contains the Base 64 encoded string of the binary file being attached.
image 0,n... Valid only for emails where body[type] is set to "html". Contains the data for an embedded image.
filename 1 Defines the file name that you want to appear for the embedded image.
data 1 Contains the Base 64 encoded image file.
priority 0-1 Defines the Priority header as a number between 1 and 5 (3 is default)

Example

The following example shows a template for a text mode message including a file attachment.

<?xml version="1.0" encoding="utf8"?> <email> <from> <address>noreply@nodomain.com</address> <text replacement="no"><![CDATA[MyApp registrations]]></text> </from> <reply> <address>support@nodomain.com</address> <text replacement="no">MyApp Support Centre</text> </reply> <subject> <text replacement="yes"><![CDATA[Welcome to MyApp #USER#]]></text> </subject> <body type="text"> <text replacement="yes"><![CDATA[Dear #FIRSNAME# #LASTNAME#, Welcome to MyApp! Your registration is complete. Sincerely, The MyApp registration team. ]]></text> </body> <replacements> <item>#USER#</item> <item>#FIRSTNAME#</item> <item>#LASTNAME#</item> </replacements> <attachment source="link" truename="files/users_guide_1.2.3.pdf"> <filename>MyApp_user_guide.pdf</filename> </attachment> <priority>3</priority> </email>

1.4.3 Public Properties

None.

1.4.4 Methods

Ver. Static Arguments Returns Purpose
__construct 1 N config path (string), locale code (string) object reference to ac_email instance The class constructor. This is implicitly called when the object is created. Once created, the config path and locale of the object cannot be changed.
select_template 1 N template name (string) (void) Causes the object to setup an email state based on a template file. This is often the first method called after creating the object. The template overrides any state that may have been set by other methods or previous templates.
set_subject 1 N subject (string) (void) Sets or replaces the subject with user-defined text.
set_reply 1 N address (string)[, name (string)] (void) Sets or replaces the Reply-To header.
set_from 1 N address (string)[, name (string)] (void) Sets or replaces the From header.
set_attachment 1 N file path (string), new filename (string) (void) Attaches a file to the email referenced from the file path and presented to the receiver with the new filename. Can be called multiple times to attach multiple files.
set_body 1 N body text (string) (void) Sets or replaces the message body.
set_recipients 1 N address (string)[, name (string), to (string)] (void) Adds a single recipient to the email. If the to argument is used, recipients can be specified as CC or BCC recipients. Possible values for to are: to = the default; cc = puts a recipient in the CC list; bcc = puts a recipient in the BCC list
set_priority 1 N priority (mixed) (void) Sets or replaces the email priority. This is represented as an integer or a string. The following values are supported: 1 / highest = Highest priority; 2 / high = High priority; 3 / normal = Default email priority; 4 / low = Low priority (rare); 5 / lowest = Lowest priority (rare)
clear_recipients 1 N (void) (void) Clears the list of recipients.
customise 1 N substitutions (array) (void) If the email is defined by a template which has text substitution markers, this array contains strings to replace those markers. The contents must be in the same order the <item> elements appear in the template's XML.
send_mail 1 N (void) string of a unique message ID Sends the email to the list of recipients. There must be recipients defined otherwise ac_email will die with a fatal error.
set_mode 1 N mode (string) (void) Sets the mode which allows the correct encoding configuration to be used. Possible values are: text = email is plain text; html = email is HTML
simulate_headers 1 N (void) string of the header block from the outgoing message ac_email will attempt to simulate a set of likely headers for the outgoing email and provide them as a string. Actual headers will change in transit and upon delivery. Therefore, this is called a simulation.

1.4.5 Usage Example

To send a message using the example template shown above, the following PHP might be used:

$replace=array( 'some_username', 'John', 'Doe' ); $message=new ac_email('/bear/web_applications/email','en'); $message->set_template('new_user'); $message->customise($replace); $message->set_recipients('j.doe@somedomain.com'); $message->send_mail();

previous: ac_tables.php next: Introduction