Rodolfo Martinez 00e60ec1b7 added additional plugins

2025-12-12 19:05:48 -05:00

11 KiB

Raw Blame History

WPForms to Mailjet Automation Plugin - Complete Summary

📋 Overview

This production-ready WordPress plugin creates automated workflows between WPForms submissions and Mailjet contact lists. Users can map form field answers to Mailjet lists through an intuitive React-based wizard interface.

🎯 Core Features

User Interface

6-Step Wizard: Beautiful React interface using @wordpress/components
Dashboard: Manage all automations with status indicators and error counts
Actions: Pause, activate, edit, and delete automations
Real-time Validation: Form validation at each step

Automation Logic

Field Mapping: Email (required), firstname, lastname (optional)
Trigger Fields: Support for checkbox, radio, dropdown, multi-select
Multiple Lists: Single submission can add contact to multiple lists
Smart Mapping: Each Mailjet list can only be used once per automation

Reliability

Retry Logic: 3 automatic retry attempts with exponential backoff
Error Logging: Custom database table tracks all failures
Admin Notifications: Email alerts when all retries fail
Auto Cleanup: Old error logs automatically deleted after 90 days

Security

Encrypted Storage: AES-256-CBC encryption for API credentials
Nonce Protection: All AJAX requests verified
Capability Checks: manage_options required for all operations
SQL Safety: Prepared statements throughout
Input Sanitization: All user input sanitized and validated

Performance

Set and Forget: No polling or excessive AJAX calls
Efficient Queries: Proper database indexing
Minimal Overhead: Form submission processing is lightweight
Optimized Assets: React bundle minified in production

Compatibility

WooCommerce: HPOS compatibility declared
WPForms: Works with Lite and Pro versions
LearnDash: No conflicts
Wordfence: No conflicts
PHP 7.4+: Modern PHP features with backward compatibility
WordPress 5.8+: Uses latest WordPress standards

📁 All Files Created

Root Level (5 files)

wpforms-mailjet-automation.php - Main plugin file
uninstall.php - Cleanup on plugin deletion
index.php - Security file
BUILD-INSTRUCTIONS.md - Build and deployment guide
package.json - To be created from template

Includes Directory (10 files)

class-wpfmj-core.php - Main orchestrator
class-wpfmj-loader.php - Hook registration
class-wpfmj-activator.php - Activation logic
class-wpfmj-deactivator.php - Deactivation logic
class-wpfmj-cpt.php - Custom post type
class-wpfmj-encryption.php - Encryption utilities
class-wpfmj-mailjet-api.php - API wrapper
class-wpfmj-form-handler.php - Form submission processor
class-wpfmj-error-logger.php - Error management
index.php - Security file

Admin Directory (3 files)

class-wpfmj-admin.php - Admin functionality and AJAX
class-wpfmj-dashboard.php - Dashboard renderer
index.php - Security file

Admin CSS (2 files)

wpfmj-admin.css - All styling
index.php - Security file

Admin JS (3 files)

wpfmj-wizard.asset.php - Dependency manifest
wpfmj-wizard.js - Generated by build process
index.php - Security file

React Source Files (11 files)

App.jsx - Main wizard component
StepOne.jsx - Choose form
StepTwo.jsx - Map fields
StepThree.jsx - Select trigger
StepFour.jsx - Connect API
StepFive.jsx - Map lists
StepSix.jsx - Review and save
api.js - AJAX utilities
index.php × 4 - Security files

Documentation (2 files)

DIRECTORY-STRUCTURE.txt - Complete file listing
PLUGIN-SUMMARY.md - This file

TOTAL: 36 source files + 1 generated file

🔧 Implementation Steps

1. Create Directory Structure

mkdir -p wpforms-mailjet-automation/{includes,admin/{css,js},assets/src/wizard/{components,utils}}

2. Place All PHP Files

Copy each PHP file artifact into its correct location according to DIRECTORY-STRUCTURE.txt

3. Place React Files

Copy all .jsx files to assets/src/wizard/ and subdirectories

4. Place CSS and JS

wpfmj-admin.css → admin/css/
api.js → assets/src/wizard/utils/
wpfmj-wizard.asset.php → admin/js/

5. Add Security Files

Copy the "Silence is golden" index.php to all 9 required directories

6. Create package.json

{
  "name": "wpforms-mailjet-automation",
  "version": "1.0.0",
  "scripts": {
    "build": "wp-scripts build assets/src/wizard/App.jsx --output-path=admin/js",
    "start": "wp-scripts start assets/src/wizard/App.jsx --output-path=admin/js"
  },
  "devDependencies": {
    "@wordpress/scripts": "^26.0.0"
  },
  "dependencies": {
    "@wordpress/element": "^5.0.0",
    "@wordpress/components": "^25.0.0",
    "@wordpress/i18n": "^4.0.0"
  }
}

7. Build React Bundle

cd wpforms-mailjet-automation
npm install
npm run build

8. Deploy

# Upload to WordPress
cp -r wpforms-mailjet-automation /path/to/wordpress/wp-content/plugins/

# Or create a zip
zip -r wpforms-mailjet-automation.zip wpforms-mailjet-automation

9. Activate

Go to WordPress Admin → Plugins → Activate "WPForms to Mailjet Automation"

🔑 Key Classes Explained

WPFMJ_Core

The main plugin orchestrator. Loads all dependencies, registers hooks, and initializes components.

WPFMJ_Loader

Manages WordPress hooks (actions and filters). Provides a centralized registration system.

WPFMJ_Encryption

Handles AES-256-CBC encryption/decryption for API credentials. Generates and stores unique encryption key.

WPFMJ_Mailjet_API

Wrapper around Mailjet REST API. Handles authentication, requests, and error handling.

WPFMJ_Form_Handler

Processes WPForms submissions. Contains retry logic, error handling, and contact management.

WPFMJ_Error_Logger

Manages error logging database table. Provides methods for logging, retrieving, and cleaning errors.

WPFMJ_Admin

Handles all admin AJAX endpoints. Manages form data, API connections, and automation CRUD.

WPFMJ_Dashboard

Renders admin dashboard page with automation list and management controls.

🎨 Wizard Flow

Step 1: Choose Form
  ↓ User selects WPForm and names automation
Step 2: Map Contact Fields
  ↓ User maps email, firstname, lastname fields
Step 3: Choose Trigger Field
  ↓ User selects which field determines list assignment
Step 4: Connect Mailjet
  ↓ User enters and tests API credentials
Step 5: Map Answers to Lists
  ↓ User maps each answer to a Mailjet list
Step 6: Review & Save
  ↓ User reviews and saves (draft or active)
Dashboard: Manage Automations

🔄 Automation Execution Flow

1. User submits WPForm
   ↓
2. wpforms_process_complete hook fires
   ↓
3. WPFMJ_Form_Handler receives submission
   ↓
4. Handler finds active automations for form
   ↓
5. Extract email, firstname, lastname from form data
   ↓
6. Extract trigger field value(s)
   ↓
7. Determine which Mailjet lists to add contact to
   ↓
8. Attempt to add contact via Mailjet API
   ↓
9. Success? → Done
   ↓ Failure?
10. Retry (up to 3 times with backoff)
    ↓
11. All retries failed? → Log error + Email admin

📊 Database Schema

wp_wpfmj_error_log Table

CREATE TABLE wp_wpfmj_error_log (
  id BIGINT(20) UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  automation_id BIGINT(20) UNSIGNED NOT NULL,
  form_entry_id BIGINT(20) UNSIGNED NOT NULL,
  error_type VARCHAR(50) NOT NULL,
  error_message TEXT NOT NULL,
  retry_count INT(11) NOT NULL DEFAULT 0,
  resolved TINYINT(1) NOT NULL DEFAULT 0,
  created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  INDEX automation_id (automation_id),
  INDEX created_at (created_at),
  INDEX resolved (resolved)
);

wpfmj_automation Custom Post Type

Post Title: Automation name
Post Status: 'publish' (active) or 'draft' (paused)
Post Meta:
- _wpfmj_config: Full configuration JSON
- _wpfmj_form_id: WPForm ID for quick queries

🧪 Testing Checklist

Functionality Tests

Install plugin successfully
WPForms dependency check works
Create new automation through wizard
All 6 wizard steps work correctly
API credentials test successfully
Save automation as draft
Save and activate automation
Edit existing automation
Pause automation
Activate paused automation
Delete automation
Form submission triggers automation
Contact added to correct Mailjet list(s)
Multiple checkbox selections work
Single selection (radio/dropdown) works
Error logging works on API failure
Retry logic executes properly
Admin email sent on persistent failure
Dashboard loads correctly
Error counts display accurately

Compatibility Tests

Works with WPForms Lite
Works with WPForms Pro
No conflicts with WooCommerce
No conflicts with HPOS enabled
No conflicts with LearnDash
No conflicts with Wordfence
Works on PHP 7.4
Works on PHP 8.0+
Works on WordPress 5.8
Works on latest WordPress

Security Tests

Non-admin users cannot access features
Nonce verification prevents CSRF
SQL injection attempts blocked
XSS attempts blocked
API credentials encrypted in database
Encrypted credentials decrypt correctly

Performance Tests

No excessive database queries
No memory leaks
No infinite loops
Form submission completes quickly
Dashboard loads without lag
No background AJAX polling

Cleanup Tests

Deactivation clears cron jobs
Uninstall removes all data
Uninstall drops custom table
Uninstall removes all options
Uninstall deletes all posts

🐛 Troubleshooting

Problem: Wizard doesn't load

Solution: Run npm run build to generate React bundle

Problem: API connection fails

Solution: Verify credentials at mailjet.com → Account Settings → REST API

Problem: Automation doesn't trigger

Solution: Check automation status is "Active" not "Paused"

Problem: Wrong list assignment

Solution: Review list mappings in Step 5, ensure correct field selected

Problem: No forms showing

Solution: Create at least one form in WPForms first

📝 Future Enhancement Ideas

Multi-language support (i18n)
Conditional logic (if/then rules)
Custom field mapping beyond firstname/lastname
Webhook integration
Analytics dashboard
Bulk import/export automations
Test mode (dry run without API calls)
Advanced error recovery options
Integration with other email providers
Custom email notification templates

📜 License

GPL-2.0+

👤 Credits

Created for connecting WPForms to Mailjet with enterprise-grade reliability and user experience.

Plugin Version: 1.0.0
WordPress Required: 5.8+
PHP Required: 7.4+
Last Updated: 2025

11 KiB Raw Blame History Unescape Escape