HandyMail
Back to top  

Handymail

HandyMail - Main class.

The main class handles generating the form HTML, running the validation and sending the email.

package

HandyMail
author

I.G Laghidze developer@firewind.co.uk

Methods

Applies the necessary parameters when the form object is instantiated.

__construct(string $name, string $action, string $submit = "Submit") : null

Arguments

$name

string

Sets the form name.

$action

string

Sets the URL for the action attribute for the form. Can be relative/absolute.

$submit

string

Set the submit text for the submit button. "Submit" by default.

Response

null

Creates a new field object via the Handymail_Formfield class and appends it together with its parameters to the $fields array.

add_field( $field_id, string $field_type, string $label = "", array $params = array()) : null

Arguments

$field_id

$field_type

string

A field type from "text", "password", "email", "date", "select", "textarea", "radio", "checkbox".

$label

string

The field label. Optional.

$params

array

Optional field parameters within an associative array. The following keys are parsed:

  • placeholder [str]
  • reply_to [bool]
  • options [array] Options for checkbox and radio elements.
  • rows [int] Number of rows for textarea elements.
  • fieldset [int] Fieldset id.
  • class [str] Unique class added to the element.
  • filters [str] Filters to apply to the input, a string with each filter delimited by |. Available options include "strip_html|escape_html|trim|hash|nl2br". All options work recursively and hence are compatible with arrays.
  • rules [array] Validation rule array. If the value evaluates true, the validation applies. Parsed elements include "required", "limit", "numeric", "alphanumeric", "valid_email", "match" - where the value is the id of the element to match to.

Response

null

Check whether field names defined in the $fields array correspond to those submitted.

authenticate_fields(array &$array) : array

This is protection against field injection, and to make sure no field names within the form have been altered. The same number of inputs must be submitted as the number of defined fields.

access

private

Arguments

$array

array

Reference array (usually post) of all received inputs.

Response

array

Returns an array of errors. If they are empty, the validation has passed.

Prints the form response in JSON format for AJAX.

encode_response(array $errors) : null

Arguments

$errors

array

  • Any encountered errors to be sent back.

Response

null

Performs a forbidden keyword check against those defined in the $forbidden_keywords property.

forbidden_keyword_check(array &$array) : array
access

private

Arguments

$array

array

Reference array (usually post) of all received inputs.

Response

array

Returns an array of errors. If they are empty, the validation has passed.

Generates HTML for the form and returns it. Utilizes the $fields and $fieldsets properties to create the corresponding inputs.

generate(boolean $html_display = false) : string

Arguments

$html_display

boolean

If true, this returns the HTML code of the form in 

 tags for further customization.

Response

string

The form HTML code, wrapped in 

 tags if $html_display is set to boolean true.

Parses and returns the validation scripts.

get_scripts(boolean $html_display = false) : string

Arguments

$html_display

boolean

If true, this returns the code in 

 tags for further customization.

Response

string

The Javascript / jQuery code.

Prepares the email by assigning input email properties to the $email_params array. Must be run before send_mail().

prepare_mail(array|\str $recipient, string $from, string $subject = "", string $template = "") : null

Generates the body content in both HTML (via the template) and plain-text form.

Arguments

$recipient

array|\str

The email recipient(s). Can be an array of recipients or a single string with a recipient email address.

$from

string

The email name for the from field. Will have the server name automatically appended [name]@server.tld.

$subject

string

The subject field.

$template

string

Filename of the template to use. This template must exist within the templates directory. Defaults to "default.php".

Response

null

Runs all the validation and filter methods defined in the Handymail main class and the Handymail_Secure class.

run_validation(boolean $semantic = false) : array

This is the only method you should run to validate inputs. Automatically checks the global $_POST array for the submitted form. If form validation passes, the method applies filters and appends the filtered values to their corresponding field ids defined within the $fieldsets property. If applicable, additionally populates $email_params["reply_to"] with email fields having an active "reply_to" parameter.g

Arguments

$semantic

boolean

If true, returns an array of fieldsets containing the field submissions. If false this returns a simple array containing [$field_id] => $value.

Response

array

An array tuple containing ($boolean, $data). If $boolean is false, $data is an array of encountered errors. If $boolean is true, $data returns the validated and filtered submissions in a format dependent on $semantic.

If the email has been successfully prepared, attempts to send the email.

send_mail() : array

Response

array

Returns an array of errors. If they are empty, the email has been successfully sent.

Assign new classes to the $alert_class array.

set_alert_classes(array $params) : null

Arguments

$params

array

Parseable keys: "success", "waiting", "error".

Response

null

Assign new main classes to the $main_class array.

set_classes(array $params) : null

Arguments

$params

array

Parseable keys: "form", "helper", "fieldset", "fieldset_sub", "fieldset_label", "fieldbox", "field", "submit", "checkbox", "radio".

Response

null

Assign new classes to the $error_class property. Merges with the default array.

set_error_classes(array $params) : null

Arguments

$params

array

Parseable keys: "fieldbox", "field_label", "field_feedback".

Response

null

Sets the label for a fieldset group.

set_fieldset_label(integer $gr_id, string $name) : null

Arguments

$gr_id

integer

ID of the revelant fieldset group - must be previously defined through add_field.

$name

string

Label for the fieldset.

Response

null

Setter method for the input filters property.

set_filters( $filters) : null

The full list of available filters is as follows: "strip_html|escape_html|trim|hash|nl2br" These are all applied recursively regardless of whether the input is an array or not.

Arguments

$filters

Response

null

Setter method for the forbidden keywords property.

set_forbidden_keywords(string $words) : null

Forbidden keywords need to be delimited with ",".

Arguments

$words

string

String of delimited forbidden words which will be appended to the current blacklist array.

Response

null

Sets the prefix that will be appended to the name and id attributes of each field element.

set_input_prefix(string $input) : null

This is used to prevent clashes from ambiguities arising from matching IDs.

Arguments

$input

string

The input prefix.

Response

null

Setter method for the validation rules property.

set_rules( $rule_array) : null

The full list of available rules is as follows: "required|numeric|alphanumeric|limit{x}|valid_email|match{x}|forbidden{x,y,z}" These are all applied recursively regardless of whether the input is an array or not.

Arguments

$rule_array

Response

null

Allows to quickly set predefined class profiles

set_style_profile(string $name = "default") : null

Arguments

$name

string

The style profile name. Default by default.

Response

null

Configure google captcha for the send_mail method. This overrides the default honeypot security protocol.

use_captcha(string $secret, string $sitekey) : null

Arguments

$secret

string

The secret code for Google ReCaptcha

$sitekey

string

The assigned sitekey from Google ReCaptcha.

Response

null

Configures the use of a separate mail server (SMTP) for sending emails.

use_smtp(array $parameters) : null

Arguments

$parameters

array

These are the SMTP parameters which are merged with the $smtp property. The following array elements are parsed:

  • Host [str] Hostname
  • Port [int] Port
  • Username [str] Username
  • Password [str] Password
  • SMTPDebug [int] default 0
  • SMTPSecure [str] default "tls"

Response

null

Prevent crawlers by checking whether captcha or honeypot validation passes/fails.

valid_signature(array &$array) : array

Also removes captcha/honeypot input from the array to prevent being included in the processed results.

access

private

Arguments

$array

array

Reference array (usually post) of all received inputs.

Response

array

Returns an array of errors. If they are empty, the validation has passed.

Changes the value of static property $xss to true.

xss_rescue() : null
static

Response

null

Constants

Plugin version

version
var

Properties

HandyMail form name. Mandatory, as it is used as the title in the email template.

name : string
var

Type(s)

string

Input prefix property.

input_prefix : string
static

Prevents clashes of ID, name and classes by applying the prefix to all form elements.

var

Type(s)

string

Form action attribute value.

form_action : string
var
access

private

Type(s)

string

Form submit value

submit_value : string
var
access

private

Type(s)

string

Default field parameters. Merged with any parameters that are input.

default_params : array
access

private
var

Type(s)

array

Variable to check whether to run trim/strip_html/htmlspecialchars on all fields automatically.

xss : boolean
static
var

Type(s)

boolean

Honeypot field name. Predefined input prefix will be appended.

honeypot_name : string
var
access

private

Type(s)

string

Array of forbidden keywords which form inputs are checked against during validation.

forbidden_keywords : array
var
access

private

Type(s)

array

Main classes for the form are predefined here. Can be reset with the set_classes() method.

main_class : array
var
access

private

Type(s)

array

Error classes that are applied to form elements are predefined here. Can be overwritten with set_error_classes()

error_class : array
var
access

private

Type(s)

array

Alert classes that are applied to the form message block are set here. Overwritten with set_alert_classes()

alert_class : array
var
access

private

Type(s)

array

The email parameters array. These are completed with prepare_mail and utilized by send_mail.

email_params : array
var
access

private

Type(s)

array

Used to check whether an email has been successfully prepared for sending or not. prepare_mail() sets to true.

mail_prepare : boolean
var
access

private

Type(s)

boolean

Imports the PHPMailer SMTP library to send mail via an SMTP server if true.

use_smtp : boolean
var
access

private

Type(s)

boolean

SMTP properties array. Set with use_smtp()

smtp : array
var
access

private

Type(s)

array