feat(wpforms): add single/double opt-in setting to WPForms integration

[faisalahammad]

🎯 Summary

Adds a per-field "Double opt-in?" setting to the WPForms Mailchimp field, allowing administrators to toggle between single and double opt-in on a per-form basis — matching the existing Gravity Forms integration pattern.

📋 Issue Reference

Fixes #710

🔍 Problem Description

Current Behavior

The WPForms integration always uses double opt-in when subscribing users to Mailchimp. There is no way for site administrators to switch to single opt-in, forcing all subscribers to go through the confirmation email flow regardless of the use case.

Expected Behavior

Administrators should be able to choose between single opt-in and double opt-in on a per-form (per-field) basis, similar to how the Gravity Forms and Ninja Forms integrations already work.

Root Cause

The WPForms integration's subscribe_from_wpforms() method directly calls $this->subscribe() without ever modifying $this->options['double_optin'], which defaults to 1 (enabled) in the base MC4WP_Integration class. Additionally, the WPForms field builder UI (MC4WP_WPForms_Field) does not expose any setting for double opt-in, so the value is never stored in the form data.

✨ Solution Overview

Approach Taken

Per-field setting in the WPForms builder — following the same pattern as the existing Gravity Forms integration:

1. Add a "Double opt-in?" Yes/No <select> dropdown to the WPForms Mailchimp field's builder options
2. Read the per-field mailchimp_double_optin value during form submission
3. Apply it to $this->options['double_optin'] before calling subscribe()
4. Restore original options afterward to prevent side effects

Why This Approach

• Consistency: Matches the Gravity Forms integration pattern (see integrations/gravity-forms/class-gravity-forms.php), so the codebase stays uniform
• Per-field control: Since WPForms can have multiple Mailchimp fields (one per form), the setting is stored at the field level — not globally in the integration settings page
• Backward compatible: Defaults to '1' (double opt-in enabled), so existing forms continue working identically without any migration
• Minimal changes: Only 2 files modified, ~50 lines of new production code

Alternatives Considered

1. Global setting on the integration admin page: Would require adding 'double_optin' to get_ui_elements(). Rejected because WPForms stores list selection per-field (not globally), so double opt-in should follow the same pattern for consistency. A global setting also wouldn't support different opt-in modes across different forms.
2. Filter-based approach: Adding a mc4wp_integration_wpforms_double_optin filter hook. Rejected because it requires custom code from the user — the whole point of issue WP Forms integration single / double opt in setting #710 is providing a UI setting that non-developers can use.

🔧 Changes Made

Files Modified

File	Changes
integrations/wpforms/class-field.php	Added "Double opt-in?" select dropdown in the WPForms field builder
integrations/wpforms/class-wpforms.php	Read per-field mailchimp_double_optin setting and apply before subscribing
tests/WPFormsDoubleOptinTest.php	[NEW] 5 unit tests for the feature

Detailed Changes

1. WPForms Field Builder UI — class-field.php

Added a new field_option_double_optin() method and wired it into the field options panel:

// Called in field_options() between list selector and checkbox choices
$this->field_option_double_optin($field);

/**
 * Renders the "Double opt-in?" select field option in the form builder.
 *
 * @since 4.9
 * @param array $field Field data.
 */
private function field_option_double_optin($field)
{
    $tooltip      = __('Select "yes" if you want people to confirm their email address before being subscribed (recommended).', 'mailchimp-for-wp');
    $option_label = $this->field_element(
        'label',
        $field,
        [
            'slug'    => 'mailchimp-double-optin',
            'value'   => __('Double opt-in?', 'mailchimp-for-wp'),
            'tooltip' => $tooltip,
        ],
        false
    );

    $current_value = isset($field['mailchimp_double_optin']) ? $field['mailchimp_double_optin'] : '1';
    $option_select = sprintf('<select name="fields[%s][mailchimp_double_optin]" ...>', $field['id'], ...);
    $option_select .= sprintf('<option value="1" %s>%s</option>', selected('1', $current_value, false), __('Yes', 'mailchimp-for-wp'));
    $option_select .= sprintf('<option value="0" %s>%s</option>', selected('0', $current_value, false), __('No', 'mailchimp-for-wp'));
    $option_select .= '</select>';

    $output = $this->field_element('row', $field, [
        'slug'    => 'mailchimp-double-optin',
        'content' => $option_label . $option_select,
    ]);
}

Why This Works:

• Uses the same field_element() API as the existing list selector and checkbox options, ensuring consistent rendering
• Stores the value in $field['mailchimp_double_optin'] which is saved as part of the WPForms form data
• Defaults to '1' (Yes) so existing forms are unaffected

---

2. Integration Logic — class-wpforms.php

Before:

public function subscribe_from_wpforms($checkbox_field_id, $fields, $form_data)
{
    // ... find email ...
    $mailchimp_list_id      = $form_data['fields'][ $checkbox_field_id ]['mailchimp_list'];
    $this->options['lists'] = [ $mailchimp_list_id ];
    // ❌ double_optin is never set — always defaults to 1

    if (! empty($email_address)) {
        return $this->subscribe([ 'EMAIL' => $email_address ], $form_data['id']);
    }
    // ❌ options are never restored
}

After:

public function subscribe_from_wpforms($checkbox_field_id, $fields, $form_data)
{
    // ... find email ...
    $field_config      = $form_data['fields'][ $checkbox_field_id ];
    $mailchimp_list_id = $field_config['mailchimp_list'];
    $double_optin      = isset($field_config['mailchimp_double_optin']) ? $field_config['mailchimp_double_optin'] : '1';

    // ✅ Override integration settings with per-field options
    $orig_options                  = $this->options;
    $this->options['lists']        = [ $mailchimp_list_id ];
    $this->options['double_optin'] = $double_optin;

    $result = false;
    if (! empty($email_address)) {
        $result = $this->subscribe([ 'EMAIL' => $email_address ], $form_data['id']);
    }

    // ✅ Restore original options to avoid side effects
    $this->options = $orig_options;
    return $result;
}

Why This Works:

• The base MC4WP_Integration::subscribe() reads $this->options['double_optin'] to determine subscriber status ('pending' vs 'subscribed'). By setting this value before calling subscribe(), we control the opt-in behavior.
• Restoring $this->options afterward prevents the per-field override from leaking into subsequent form processing — this is the same defensive pattern used by the Gravity Forms integration.
• Defaults to '1' when mailchimp_double_optin is not set, ensuring backward compatibility with existing forms.

Impact:

• ✅ Administrators can now choose single or double opt-in per WPForms form
• ✅ Existing forms continue to use double opt-in (no behavior change)
• ✅ Follows established patterns from the Gravity Forms integration

🧪 Testing Performed

Automated Testing

$ vendor/bin/phpunit
Welcome to the Mailchimp for WordPress Test Suite
PHPUnit 9.6.34 by Sebastian Bergmann and contributors.

...........................................................       59 / 59 (100%)

Time: 00:00.024, Memory: 6.00 MB

OK (59 tests, 185 assertions)

New Tests Created — tests/WPFormsDoubleOptinTest.php (5 tests, 10 assertions):

Test	Description	Result
test_default_double_optin	Verifies double opt-in defaults to '1' when not set	✅ Pass
test_single_optin	Verifies double_optin is set to '0' when configured	✅ Pass
test_options_restored_after_subscribe	Verifies original options are restored after call	✅ Pass
test_listen_to_wpforms_triggers_subscription	Verifies subscription triggers for checked checkbox	✅ Pass
test_listen_to_wpforms_skips_unchecked	Verifies no subscription for unchecked checkbox	✅ Pass

Regression Testing

• ✅ All 59 existing tests pass (185 assertions)
• ✅ No existing test was modified

📊 Performance Impact

✅ Negligible — The only addition is reading one extra field from the already-loaded $form_data array and one extra variable assignment. No additional database queries, API calls, or file I/O.

🔒 Security Considerations

• ✅ Input handling: The mailchimp_double_optin value is read from $form_data['fields'] which is already sanitized by WPForms during form save. It's used as a truthy/falsy value in the base class (? 'pending' : 'subscribed'), not interpolated into SQL or HTML.
• ✅ Output escaping: The <select> dropdown in the builder uses selected() (WordPress core function) for safe attribute output.
• ✅ No new user input surfaces: The setting is only configurable by form editors (administrators), not front-end users.

🌍 Internationalization

• ✅ All new strings wrapped in __() with text domain mailchimp-for-wp
• ✅ Strings: "Double opt-in?", "Yes", "No", and tooltip text
• ✅ Consistent with existing translation patterns in the codebase

⚠️ Breaking Changes

✅ No breaking changes — Fully backward compatible. The mailchimp_double_optin field defaults to '1' when not present, maintaining identical behavior for all existing WPForms forms.

Screenshot / Screen recording

https://cln.sh/ylJ1Lk35

✅ PR Checklist

• Code follows WordPress Coding Standards
• All functions have proper PHPDoc blocks
• Input handled safely
• Output escaped where applicable
• Strings are translatable with correct text domain
• No PHP warnings/errors
• Backward compatible — defaults preserve existing behavior
• All 59 tests pass successfully (185 assertions)
• Self-reviewed for quality
• Follows existing codebase patterns (Gravity Forms reference)

🤝 Additional Context

• The Gravity Forms integration (integrations/gravity-forms/) was used as the primary reference for this implementation, as it already supports per-field double opt-in in the same way.
• The Ninja Forms integration takes a slightly different approach (through its action-based architecture), but the end result is the same — per-form opt-in control.
• This addresses a feature request that has been open since October 2020, with multiple community members requesting the same capability.

[dannyvankooten]

Hi @faisalahammad. Not related to this PR per se, but can you instruct your AI to be more concise? This is a lot of text and a lot of it is unnecessary verbose.

I really only care about the goal of the PR, special considerations and potential breaking changes. The code will speak for itself. Workflow ensures that tests pass and code style is consistent, no need for the AI to repeat that.

[dannyvankooten]

Merged with a few tiny modifications! Thanks @faisalahammad. We'll be including all of these changes in the next plugin update, due next week.

We'd like to give credits to you in the changelog, would you like us to link somewhere specific?

[faisalahammad]

If possible, please feel free to give credit to my personal portfolio website: https://faisalahammad.com. It would also be wonderful if you could include my WordPress.org username (faisalahammad) in the plugin contributor list, but no pressure at all, only if it’s convenient for you.

I’ve really enjoyed working on your plugin and am glad to contribute through those PRs to help users. When I was at Ninja Forms last year, I noticed many of our users relied on your plugin. Since the default MailChimp checkbox wasn’t working well, we recommended using Conditional Logic as a solution.

Thanks so much for creating such a great plugin! @dannyvankooten