WooCommerce Code Reference

WC_Email extends WC_Settings_API

Email Class

WooCommerce Email Class which is extended by specific email template classes to add emails to WooCommerce

Tags
class

WC_Email

version
2.5.0
extends

WC_Settings_API

Table of Contents

$description  : string
Description for the email.
$email_type  : string
E-mail type: plain, html or multipart.
$enabled  : string
'yes' if the method is enabled.
$errors  : array<string|int, mixed>
Validation errors.
$find  : array<string|int, mixed>
Strings to find in subjects/headings.
$form_fields  : array<string|int, mixed>
Form option fields.
$heading  : string
Default heading.
$id  : string
Email method ID.
$mime_boundary  : string
Mime boundary (for multipart emails).
$mime_boundary_header  : string
Mime boundary header (for multipart emails).
$object  : object|bool
Object this email is for, for example a customer, product, or email.
$plain_replace  : mixed
List of pattern replacements corresponding to patterns searched.
$plain_search  : array<string|int, mixed>
List of preg* regular expression patterns to search for, used in conjunction with $plain_replace.
$plugin_id  : string
The plugin ID. Used for option names.
$recipient  : string
Recipients for the email.
$replace  : array<string|int, mixed>
Strings to replace in subjects/headings.
$sending  : bool
True when email is being sent.
$settings  : array<string|int, mixed>
Setting values.
$subject  : string
Default subject.
$template_base  : string
Template path.
$template_html  : string
HTML template path.
$template_plain  : string
Plain text template path.
$title  : string
Email method title.
$customer_email  : bool
True when the email notification is sent to customers.
$data  : array<string|int, mixed>
The posted settings data. When empty, $_POST data will be used.
$manual  : bool
True when the email notification is sent manually only.
$placeholders  : array<string|int, mixed>
Strings to find/replace in subjects/headings.
__construct()  : mixed
Constructor.
add_error()  : mixed
Add an error message for display in admin on save.
admin_options()  : mixed
Admin Options.
display_errors()  : mixed
Display admin error messages.
format_settings()  : array<string|int, mixed>
Format settings if needed.
format_string()  : string
Format email string.
generate_checkbox_html()  : string
Generate Checkbox HTML.
generate_color_html()  : string
Generate Color Picker Input HTML.
generate_decimal_html()  : string
Generate Decimal Input HTML.
generate_multiselect_html()  : string
Generate Multiselect HTML.
generate_password_html()  : string
Generate Password Input HTML.
generate_price_html()  : string
Generate Price Input HTML.
generate_safe_text_html()  : string
Generates HTML for the 'safe_text' input type (mostly used for gateway-related settings).
generate_select_html()  : string
Generate Select HTML.
generate_settings_html()  : string
Generate Settings HTML.
generate_text_html()  : string
Generate Text Input HTML.
generate_textarea_html()  : string
Generate Textarea HTML.
generate_title_html()  : string
Generate Title HTML.
get_additional_content()  : string
Return content from the additional_content field.
get_attachments()  : array<string|int, mixed>
Get email attachments.
get_blogname()  : string
Get WordPress blog name.
get_content()  : string
Get email content.
get_content_html()  : string
Get the email content in HTML format.
get_content_plain()  : string
Get the email content in plain text format.
get_content_type()  : string
Get email content type.
get_custom_attribute_html()  : string
Get custom attributes.
get_default_additional_content()  : string
Default content to show below main email content.
get_default_heading()  : string
Get email heading.
get_default_subject()  : string
Get email subject.
get_description()  : string
Return the email's description
get_description_html()  : string
Get HTML for descriptions.
get_email_type()  : string
Return email type.
get_email_type_options()  : array<string|int, mixed>
Email type options.
get_errors()  : mixed
Get admin error messages.
get_field_default()  : string
Get a fields default value. Defaults to "" if not set.
get_field_key()  : string
Prefix key for settings.
get_field_type()  : string
Get a fields type. Defaults to "text" if not set.
get_field_value()  : string
Get a field's posted and validated value.
get_form_fields()  : array<string|int, mixed>
Get the form fields after they are initialized.
get_from_address()  : string
Get the from address for outgoing emails.
get_from_name()  : string
Get the from name for outgoing emails.
get_headers()  : string
Get email headers.
get_heading()  : string
Get email heading.
get_option()  : string
Proxy to parent's get_option and attempt to localize the result using gettext.
get_option_key()  : string
Return the name of the option in the WP DB.
get_post_data()  : array<string|int, mixed>
Returns the POSTed data, to be used to save the settings.
get_recipient()  : string
Get valid recipients.
get_subject()  : string
Get email subject.
get_template()  : string
Get template.
get_theme_template_file()  : string
Get the template file in the current theme.
get_title()  : string
Return the email's title
get_tooltip_html()  : string
Get HTML for tooltips.
handle_multipart()  : PHPMailer
Handle multipart mail.
init_form_fields()  : mixed
Initialise Settings Form Fields - these are generic email options most will use.
init_settings()  : mixed
Initialise Settings.
is_customer_email()  : bool
Checks if this email is customer focussed.
is_enabled()  : bool
Checks if this email is enabled and will be sent.
is_manual()  : bool
Checks if this email is manually sent
process_admin_options()  : bool
Admin Panel Options Processing.
restore_locale()  : mixed
Restore the locale to the default locale. Use after finished with setup_locale.
send()  : bool
Send an email.
set_post_data()  : mixed
Sets the POSTed data. This method can be used to set specific data, instead of taking it from the $_POST array.
setup_locale()  : mixed
Set the locale to the store locale for customer emails to make sure emails are in the store language.
style_inline()  : string
Apply inline styles to dynamic content.
update_option()  : bool
Update a single option.
validate_checkbox_field()  : string
Validate Checkbox Field.
validate_decimal_field()  : string
Validate Decimal Field.
validate_multiselect_field()  : string|array<string|int, mixed>
Validate Multiselect Field.
validate_password_field()  : string
Validate Password Field. No input sanitization is used to avoid corrupting passwords.
validate_price_field()  : string
Validate Price Field.
validate_safe_text_field()  : string
Sanitize 'Safe Text' fields.
validate_select_field()  : string
Validate Select Field.
validate_settings_fields()  : mixed
Validate the data on the "Settings" form.
validate_text_field()  : string
Validate Text Field.
validate_textarea_field()  : string
Validate Textarea Field.
admin_actions()  : mixed
Admin actions.
delete_template_action()  : mixed
Delete template action.
get_must_use_css_styles()  : string
Returns CSS styles that should be included with all HTML e-mails, regardless of theme specific customizations.
move_template_action()  : mixed
Move template action.
save_template()  : mixed
Save the email templates.
set_defaults()  : array<string|int, mixed>
Set default required properties for each field.
supports_emogrifier()  : bool
Return if emogrifier library is supported.
clear_alt_body_field()  : void
Clears the PhpMailer AltBody field, to prevent that content from leaking across emails.

Properties

$find

Strings to find in subjects/headings.

public array<string|int, mixed> $find = array()
Tags
deprecated
3.2.0

in favour of placeholders

$heading

Default heading.

public string $heading = ''

Supported for backwards compatibility but we recommend overloading the get_default_x methods instead so localization can be done when needed.

$plain_replace

List of pattern replacements corresponding to patterns searched.

public mixed $plain_replace = array( '', // Non-legal carriage return. ' ', // Non-breaking space. '"', // Double quotes. "'", // Single quotes. '>', // Greater-than. '<', // Less-than. '&', // Ampersand. '&', // Ampersand. '(c)', // Copyright. '(tm)', // Trademark. '(R)', // Registered. '--', // mdash. '-', // ndash. '*', // Bullet. '£', // Pound sign. 'EUR', // Euro sign. € ?. '$', // Dollar sign. '', // Unknown/unhandled entities. ' ', )

@var array $plain_replace

Tags
see

$plain_search

List of preg* regular expression patterns to search for, used in conjunction with $plain_replace.

public array<string|int, mixed> $plain_search = array( "/ /", // Non-legal carriage return. '/&(nbsp|#0*160);/i', // Non-breaking space. '/&(quot|rdquo|ldquo|#0*8220|#0*8221|#0*147|#0*148);/i', // Double quotes. '/&(apos|rsquo|lsquo|#0*8216|#0*8217);/i', // Single quotes. '/&gt;/i', // Greater-than. '/&lt;/i', // Less-than. '/&#0*38;/i', // Ampersand. '/&amp;/i', // Ampersand. '/&(copy|#0*169);/i', // Copyright. '/&(trade|#0*8482|#0*153);/i', // Trademark. '/&(reg|#0*174);/i', // Registered. '/&(mdash|#0*151|#0*8212);/i', // mdash. '/&(ndash|minus|#0*8211|#0*8722);/i', // ndash. '/&(bull|#0*149|#0*8226);/i', // Bullet. '/&(pound|#0*163);/i', // Pound sign. '/&(euro|#0*8364);/i', // Euro sign. '/&(dollar|#0*36);/i', // Dollar sign. '/&[^&\s;]+;/i', // Unknown/unhandled entities. '/[ ]{2,}/', )

https://raw.github.com/ushahidi/wp-silcc/master/class.html2text.inc

$replace

Strings to replace in subjects/headings.

public array<string|int, mixed> $replace = array()
Tags
deprecated
3.2.0

in favour of placeholders

$subject

Default subject.

public string $subject = ''

Supported for backwards compatibility but we recommend overloading the get_default_x methods instead so localization can be done when needed.

Methods

admin_options()

Admin Options.

public admin_options() : mixed

Setup the email settings screen. Override this in your email.

Tags
since
1.0.0
Return values
mixed

format_settings()

Format settings if needed.

public format_settings(array<string|int, mixed> $value) : array<string|int, mixed>
Parameters
$value : array<string|int, mixed>

Value to format.

Tags
deprecated
2.6.0

Unused.

Return values
array<string|int, mixed>

format_string()

Format email string.

public format_string(mixed $string) : string
Parameters
$string : mixed

Text to replace placeholders in.

Return values
string

generate_checkbox_html()

Generate Checkbox HTML.

public generate_checkbox_html(string $key, array<string|int, mixed> $data) : string
Parameters
$key : string

Field key.

$data : array<string|int, mixed>

Field data.

Tags
since
1.0.0
Return values
string

generate_color_html()

Generate Color Picker Input HTML.

public generate_color_html(string $key, array<string|int, mixed> $data) : string
Parameters
$key : string

Field key.

$data : array<string|int, mixed>

Field data.

Tags
since
1.0.0
Return values
string

generate_decimal_html()

Generate Decimal Input HTML.

public generate_decimal_html(string $key, array<string|int, mixed> $data) : string
Parameters
$key : string

Field key.

$data : array<string|int, mixed>

Field data.

Tags
since
1.0.0
Return values
string

generate_multiselect_html()

Generate Multiselect HTML.

public generate_multiselect_html(string $key, array<string|int, mixed> $data) : string
Parameters
$key : string

Field key.

$data : array<string|int, mixed>

Field data.

Tags
since
1.0.0
Return values
string

generate_password_html()

Generate Password Input HTML.

public generate_password_html(string $key, array<string|int, mixed> $data) : string
Parameters
$key : string

Field key.

$data : array<string|int, mixed>

Field data.

Tags
since
1.0.0
Return values
string

generate_price_html()

Generate Price Input HTML.

public generate_price_html(string $key, array<string|int, mixed> $data) : string
Parameters
$key : string

Field key.

$data : array<string|int, mixed>

Field data.

Tags
since
1.0.0
Return values
string

generate_safe_text_html()

Generates HTML for the 'safe_text' input type (mostly used for gateway-related settings).

public generate_safe_text_html(string $key, array<string|int, mixed> $data) : string
Parameters
$key : string

Field key.

$data : array<string|int, mixed>

Field data.

Tags
since
7.6.0
Return values
string

generate_select_html()

Generate Select HTML.

public generate_select_html(string $key, array<string|int, mixed> $data) : string
Parameters
$key : string

Field key.

$data : array<string|int, mixed>

Field data.

Tags
since
1.0.0
Return values
string

generate_settings_html()

Generate Settings HTML.

public generate_settings_html([array<string|int, mixed> $form_fields = array() ][, bool $echo = true ]) : string

Generate the HTML for the fields on the "settings" screen.

Parameters
$form_fields : array<string|int, mixed> = array()

(default: array()) Array of form fields.

$echo : bool = true

Echo or return.

Tags
since
1.0.0
uses
method_exists()
Return values
stringthe html for the settings

generate_text_html()

Generate Text Input HTML.

public generate_text_html(string $key, array<string|int, mixed> $data) : string
Parameters
$key : string

Field key.

$data : array<string|int, mixed>

Field data.

Tags
since
1.0.0
Return values
string

generate_textarea_html()

Generate Textarea HTML.

public generate_textarea_html(string $key, array<string|int, mixed> $data) : string
Parameters
$key : string

Field key.

$data : array<string|int, mixed>

Field data.

Tags
since
1.0.0
Return values
string

generate_title_html()

Generate Title HTML.

public generate_title_html(string $key, array<string|int, mixed> $data) : string
Parameters
$key : string

Field key.

$data : array<string|int, mixed>

Field data.

Tags
since
1.0.0
Return values
string

get_additional_content()

Return content from the additional_content field.

public get_additional_content() : string

Displayed above the footer.

Tags
since
3.7.0
Return values
string

get_attachments()

Get email attachments.

public get_attachments() : array<string|int, mixed>
Return values
array<string|int, mixed>

get_content_type()

Get email content type.

public get_content_type([string $default_content_type = '' ]) : string
Parameters
$default_content_type : string = ''

Default wp_mail() content type.

Return values
string

get_custom_attribute_html()

Get custom attributes.

public get_custom_attribute_html(array<string|int, mixed> $data) : string
Parameters
$data : array<string|int, mixed>

Field data.

Return values
string

get_default_additional_content()

Default content to show below main email content.

public get_default_additional_content() : string
Tags
since
3.7.0
Return values
string

get_description_html()

Get HTML for descriptions.

public get_description_html(array<string|int, mixed> $data) : string
Parameters
$data : array<string|int, mixed>

Data for the description.

Return values
string

get_email_type_options()

Email type options.

public get_email_type_options() : array<string|int, mixed>
Return values
array<string|int, mixed>

get_field_default()

Get a fields default value. Defaults to "" if not set.

public get_field_default(array<string|int, mixed> $field) : string
Parameters
$field : array<string|int, mixed>

Field key.

Return values
string

get_field_type()

Get a fields type. Defaults to "text" if not set.

public get_field_type(array<string|int, mixed> $field) : string
Parameters
$field : array<string|int, mixed>

Field key.

Return values
string

get_field_value()

Get a field's posted and validated value.

public get_field_value(string $key, array<string|int, mixed> $field[, array<string|int, mixed> $post_data = array() ]) : string
Parameters
$key : string

Field key.

$field : array<string|int, mixed>

Field array.

$post_data : array<string|int, mixed> = array()

Posted data.

Return values
string

get_from_address()

Get the from address for outgoing emails.

public get_from_address([string $from_email = '' ]) : string
Parameters
$from_email : string = ''

Default wp_mail() email address to send from.

Return values
string

get_from_name()

Get the from name for outgoing emails.

public get_from_name([string $from_name = '' ]) : string
Parameters
$from_name : string = ''

Default wp_mail() name associated with the "from" email address.

Return values
string

get_option()

Proxy to parent's get_option and attempt to localize the result using gettext.

public get_option(string $key[, mixed $empty_value = null ]) : string
Parameters
$key : string

Option key.

$empty_value : mixed = null

Value to use when option is empty.

Return values
string

get_template()

Get template.

public get_template(string $type) : string
Parameters
$type : string

Template type. Can be either 'template_html' or 'template_plain'.

Return values
string

get_theme_template_file()

Get the template file in the current theme.

public get_theme_template_file(string $template) : string
Parameters
$template : string

Template name.

Return values
string

get_tooltip_html()

Get HTML for tooltips.

public get_tooltip_html(array<string|int, mixed> $data) : string
Parameters
$data : array<string|int, mixed>

Data for the tooltip.

Return values
string

handle_multipart()

Handle multipart mail.

public handle_multipart(PHPMailer $mailer) : PHPMailer
Parameters
$mailer : PHPMailer

PHPMailer object.

Return values
PHPMailer

init_form_fields()

Initialise Settings Form Fields - these are generic email options most will use.

public init_form_fields() : mixed
Return values
mixed

init_settings()

Initialise Settings.

public init_settings() : mixed

Store all settings in a single database entry and make sure the $settings array is either the default or the settings stored in the database.

Tags
since
1.0.0
uses

get_option(), add_option()

Return values
mixed

process_admin_options()

Admin Panel Options Processing.

public process_admin_options() : bool
Return values
boolwas anything saved?

restore_locale()

Restore the locale to the default locale. Use after finished with setup_locale.

public restore_locale() : mixed
Return values
mixed

send()

Send an email.

public send(string $to, string $subject, string $message, string $headers, array<string|int, mixed> $attachments) : bool
Parameters
$to : string

Email to.

$subject : string

Email subject.

$message : string

Email message.

$headers : string

Email headers.

$attachments : array<string|int, mixed>

Email attachments.

Return values
boolsuccess

set_post_data()

Sets the POSTed data. This method can be used to set specific data, instead of taking it from the $_POST array.

public set_post_data([array<string|int, mixed> $data = array() ]) : mixed
Parameters
$data : array<string|int, mixed> = array()

Posted data.

Return values
mixed

setup_locale()

Set the locale to the store locale for customer emails to make sure emails are in the store language.

public setup_locale() : mixed
Return values
mixed

style_inline()

Apply inline styles to dynamic content.

public style_inline(string|null $content) : string

We only inline CSS for html emails, and to do so we use Emogrifier library (if supported).

Parameters
$content : string|null

Content that will receive inline styles.

Tags
version
4.0.0
Return values
string

update_option()

Update a single option.

public update_option(string $key[, mixed $value = '' ]) : bool
Parameters
$key : string

Option key.

$value : mixed = ''

Value to set.

Tags
since
3.4.0
Return values
boolwas anything saved?

validate_checkbox_field()

Validate Checkbox Field.

public validate_checkbox_field(string $key, string $value) : string

If not set, return "no", otherwise return "yes".

Parameters
$key : string

Field key.

$value : string

Posted Value.

Return values
string

validate_decimal_field()

Validate Decimal Field.

public validate_decimal_field(string $key, string $value) : string

Make sure the data is escaped correctly, etc.

Parameters
$key : string

Field key.

$value : string

Posted Value.

Return values
string

validate_multiselect_field()

Validate Multiselect Field.

public validate_multiselect_field(string $key, string $value) : string|array<string|int, mixed>
Parameters
$key : string

Field key.

$value : string

Posted Value.

Return values
string|array<string|int, mixed>

validate_password_field()

Validate Password Field. No input sanitization is used to avoid corrupting passwords.

public validate_password_field(string $key, string $value) : string
Parameters
$key : string

Field key.

$value : string

Posted Value.

Return values
string

validate_price_field()

Validate Price Field.

public validate_price_field(string $key, string $value) : string

Make sure the data is escaped correctly, etc.

Parameters
$key : string

Field key.

$value : string

Posted Value.

Return values
string

validate_safe_text_field()

Sanitize 'Safe Text' fields.

public validate_safe_text_field(string $key, string $value) : string

These fields are similar to regular text fields, but a much smaller set of HTML tags are allowed. By default, this means <br>, <img>, <p> and <span> tags.

Note: this is a sanitization method, rather than a validation method (the name is due to some historic naming choices).

Parameters
$key : string

Field key (currently unused).

$value : string

Posted Value.

Return values
string

validate_select_field()

Validate Select Field.

public validate_select_field(string $key, string $value) : string
Parameters
$key : string

Field key.

$value : string

Posted Value.

Return values
string

validate_settings_fields()

Validate the data on the "Settings" form.

public validate_settings_fields([array<string|int, mixed> $form_fields = array() ]) : mixed
Parameters
$form_fields : array<string|int, mixed> = array()

Array of fields.

Tags
deprecated
2.6.0

No longer used.

Return values
mixed

validate_text_field()

Validate Text Field.

public validate_text_field(string $key, string $value) : string

Make sure the data is escaped correctly, etc.

Parameters
$key : string

Field key.

$value : string

Posted Value.

Return values
string

validate_textarea_field()

Validate Textarea Field.

public validate_textarea_field(string $key, string $value) : string
Parameters
$key : string

Field key.

$value : string

Posted Value.

Tags
since
9.0.0

No longer allows storing IFRAME, which was allowed for "ShareThis" integration no longer found in core.

Return values
string

delete_template_action()

Delete template action.

protected delete_template_action(string $template_type) : mixed
Parameters
$template_type : string

Template type.

Return values
mixed

get_must_use_css_styles()

Returns CSS styles that should be included with all HTML e-mails, regardless of theme specific customizations.

protected get_must_use_css_styles() : string
Tags
since
9.1.0
Return values
string

move_template_action()

Move template action.

protected move_template_action(string $template_type) : mixed
Parameters
$template_type : string

Template type.

Return values
mixed

save_template()

Save the email templates.

protected save_template(string $template_code, string $template_path) : mixed
Parameters
$template_code : string

Template code.

$template_path : string

Template path.

Tags
since
2.4.0
Return values
mixed

set_defaults()

Set default required properties for each field.

protected set_defaults(array<string|int, mixed> $field) : array<string|int, mixed>
Parameters
$field : array<string|int, mixed>

Setting field array.

Return values
array<string|int, mixed>

supports_emogrifier()

Return if emogrifier library is supported.

protected supports_emogrifier() : bool
Tags
version
4.0.0
since
3.5.0
Return values
bool

clear_alt_body_field()

Clears the PhpMailer AltBody field, to prevent that content from leaking across emails.

private clear_alt_body_field() : void
Return values
void