This guide is for developers wanting to integrate Fullworks Anti Spam to protect custom forms. Fullworks Anti Spam integrates automatically to many forms – see the current list here, so if you use one of those form you do not need to use this guide. Additionally we will always consider integrating to any common forms plugins.
The Fullworks Anti-Spam API provides two primary methods for integrating spam protection into your WordPress forms: using WordPress filters or an Object-Oriented (OO) approach in PHP. This guide explains both methods in detail, including how to register your forms and check for spam.
WordPress Filter Method
Registering Forms
Before checking for spam, you need to register your form with the FullWorks Anti-Spam system using the fwas_registered_forms filter. This filter expects an array of forms, each with its own attributes.
Usage Example:
add_filter('fwas_registered_forms', 'register_my_forms');
function register_my_forms($forms) {
$forms[] = array(
'myform', // Unique form system identifier
array(
'name' => 'My Form Name',
'selectors' => '.my-form-class',
'protection_level' => 3,
'email_log' => 'content', // Optional, default is false
'email_mail_header' => 'X-My-Form-Sender', // Only required if email_log = 'registration' the form system doesn't already apply a unique identifier
'email_mail_header_filter' => 'myform/email_template_header', // Only required if email_log = 'registration' the form system doesn't already apply a unique identifier
'unstoppable' => true, // Optional, default is false
'spam_admin_url' => 'admin.php?page=my-spam-log-settings&view=spam', // Optional, only needed if 'email_log' is not false
'spam_purge_cb' => array(
'\MyPlugin\Core\Purge',
'purge_myform_spam',
), // Optional, only needed if 'email_log' is not false
'spam_count_cb' => array(
'\MyPlugin\Core\Email_Reports',
'get_myform_spam_count',
), // Optional, only needed if 'email_log' is not false
)
);
return $forms;
}Form Array Attributes:
- name: (string) Human-readable name of the form system.
- selectors: (string) CSS selectors to identify the form in the DOM.
- protection_level: (int) The level of spam protection applied (higher numbers indicate stronger protection).
- email_log: (string|bool) Optional. Determines how emails are logged:
- ‘registration’: Logs the form’s first admin auto-response message.
- ‘content’: Logs the text content used to detect spam.
- false: Disables email logging, so the forms system is expected to log their entries, and if available provide an admin link to spam lists, provide a call back to purge spam entries if needed and provide a callback to count spam entries for reports and alerts (default).
- email_mail_header: (string) Optional. The header used to identify the email sender.
- email_mail_header_filter: (string) Optional. The filter applied to the email header. This is only required if the form system doesn’t already apply a unique identifier as specified in email_mail_header.
- unstoppable: (bool) Optional. If true, indicates that the form cannot prevent an autoresponse when spam is detected. This alters the subject line to warn of potential spam and may use an alternate email address if configured in anti-spam settings. Default is false.
- spam_admin_url: (string) Optional. URL to the spam log settings in the WordPress admin panel.
- spam_purge_cb: (array) Optional. Callback function for custom spam purging, defined as an array with the class name and method. This is only needed if email_log is not false.
- spam_count_cb: (array) Optional. Callback function to count spam, defined as an array with the class name and method. This is only needed if email_log is not false.
Checking for Spam
After registering your forms, you can check for spam using the fwas_is_spam filter. This filter evaluates the form submission and returns a result indicating whether the submission is spam.
Usage Example:
$is_spam = apply_filters(
'fwas_is_spam',
false, // Default is false unless pre-checks indicate otherwise
$form_system, // Unique form system identifier (e.g., 'myform')
$email, // The primary email collected by your form
$message // Combined text areas of your form, concatenated with spaces
);Return Values:
The filter returns one of the following values:
- false: Submission is not considered spam.
- BOT: Detected as a bot submission.
- DENY: Matches an entry on the deny list in the plugin settings.
- IP_BLK_LST: IP address is on an industry block list.
- SNGL_WRD: Submission contains only one word, often indicative of spam (based on settings).
- HUMAN: Likely spam based on machine learning and AI content analysis.
Object-Oriented (OO) PHP Method
The OO method provides a more flexible and programmatic way to interact with the FullWorks Anti-Spam API. This approach is recommended for developers who prefer a code-driven integration.
Important Reminders:
- Ensure Initialization: Call the OO methods after the plugins_loaded hook to ensure that all plugins are fully loaded.
- Class Check: Verify that the \Fullworks_Anti_Spam\Anti_Spam_Api class exists before attempting to create an instance.
Registering Forms
To register a form, create an instance of the \Fullworks_Anti_Spam\Anti_Spam_Api class and use the update_registered_form method to register your form with a unique system identifier and its attributes.
Usage Example:
add_action('plugins_loaded', function() {
if (class_exists('\Fullworks_Anti_Spam\Anti_Spam_Api')) {
$anti_spam = new \Fullworks_Anti_Spam\Anti_Spam_Api();
$anti_spam->update_registered_form('myform', array(
'name' => 'My Form Name',
'selectors' => '.my-form-class',
'protection_level' => 3,
'email_log' => 'content', // Optional, default is false
'email_mail_header' => 'X-My-Form-Sender', // Only required if email_log = 'registration' the form system doesn't already apply a unique identifier
'email_mail_header_filter' => 'myform/email_template_header', // Only required if email_log = 'registration' the form system doesn't already apply a unique identifier
'unstoppable' => true, // Optional, default is false
'spam_admin_url' => 'admin.php?page=my-spam-log-settings&view=spam', // Optional, only needed if 'email_log' is not false
'spam_purge_cb' => array(
'\MyPlugin\Core\Purge',
'purge_myform_spam',
), // Optional, only needed if 'email_log' is not false
'spam_count_cb' => array(
'\MyPlugin\Core\Email_Reports',
'get_myform_spam_count',
), // Optional, only needed if 'email_log' is not false
));
}
});- $form_system: (string) A unique identifier for your form system.
- array: The array of attributes for the form, following the same structure as the filter method.
Checking for Spam
To check if a form submission is spam, use the is_spam method of the Anti_Spam_Api class.
Usage Example:
$is_spam=false;
if (class_exists('\Fullworks_Anti_Spam\Anti_Spam_Api')) {
$anti_spam = new \Fullworks_Anti_Spam\Anti_Spam_Api();
$is_spam = $anti_spam->is_spam($is_spam, $form_system, $email, $message);
}
// do what you need to do e.g. check status and send registration email
The is_spam method returns the same values as the fwas_is_spam filter:
- false
- BOT
- DENY
- IP_BLK_LST
- SNGL_WRD
- HUMAN
