monorepo/native/wordpress/wpforms-mailjet-automations/config_docs.md

WPForms to Mailjet Automation - Configuration Guide

Overview

This plugin supports extensive customization through WordPress filters. You can modify settings without touching core plugin files, ensuring your customizations survive plugin updates.

Quick Start

1. Copy the sample configuration file:

   cp wpfmj-config-sample.php wpfmj-config.php
   

2. Edit wpfmj-config.php with your preferred settings

3. Save and upload - Settings take effect immediately

The wpfmj-config.php file is automatically loaded by the plugin and is excluded from version control.

---

Available Configuration Options

1. Error Log Retention Period

Filter: wpfmj_error_log_retention_days
Default: 90 days
Range: 7-365 days
Type: Integer

Controls how long resolved error logs are kept before automatic deletion.

add_filter('wpfmj_error_log_retention_days', function($days) {
    return 180; // Keep for 6 months
});

Considerations:

• Shorter periods (7-30 days): Saves database space, good for high-volume sites
• Longer periods (90-365 days): Better for audit trails and trend analysis
• Optimal: 90 days balances storage and historical data

---

2. API Rate Limit

Filter: wpfmj_api_rate_limit
Default: 60 requests/minute
Range: 10-300 requests/minute
Type: Integer

Sets the maximum Mailjet API requests per minute per API key.

add_filter('wpfmj_api_rate_limit', function($limit) {
    return 120; // Double the default
});

Considerations:

• Lower limits (10-30): More conservative, prevents rate limit errors
• Default (60): Balanced for most sites
• Higher limits (120-300): For high-traffic sites, but monitor closely
• Mailjet limit: 300 requests/minute maximum

⚠️ Warning: Setting too high may cause Mailjet to reject requests.

---

3. Maximum Retry Attempts

Filter: wpfmj_max_retry_attempts
Default: 3 attempts
Range: 1-5 attempts
Type: Integer

Number of retry attempts for failed API calls.

add_filter('wpfmj_max_retry_attempts', function($attempts) {
    return 5; // Maximum persistence
});

Retry Timing:

• Attempt 1: Immediate
• Attempt 2: After 1 second
• Attempt 3: After 2 seconds
• Attempt 4: After 4 seconds
• Attempt 5: After 8 seconds

Considerations:

• 1 attempt: Fast failure, good for testing
• 3 attempts (default): Balanced approach
• 5 attempts: Maximum reliability, but slower failure detection

---

4. Email Notification Recipients

Filter: wpfmj_failure_notification_emails
Default: WordPress admin email
Type: Array of email addresses

Customize who receives failure notifications.

add_filter('wpfmj_failure_notification_emails', function($emails) {
    return array(
        get_option('admin_email'),
        'developer@example.com',
        'support@example.com',
        'monitoring@example.com'
    );
});

Use Cases:

• Development team: Add developer emails
• Support team: Add support desk email
• Monitoring: Integrate with ticketing systems
• Multiple admins: Ensure redundancy

---

5. Disable Email Notifications

Filter: wpfmj_disable_failure_notifications
Default: false (notifications enabled)
Type: Boolean

Completely disable email notifications.

add_filter('wpfmj_disable_failure_notifications', function($disabled) {
    return true; // Disable all emails
});

When to disable:

• Using external monitoring tools
• High-volume sites with frequent transient errors
• During development/testing

⚠️ Note: Errors are still logged in the database even when notifications are disabled.

---

6. Encryption Method

Filter: wpfmj_encryption_method
Default: AES-256-CBC
Type: String

Change the encryption algorithm for API credentials.

add_filter('wpfmj_encryption_method', function($method) {
    return 'AES-256-GCM'; // More modern algorithm
});

Available Methods:

• AES-256-CBC (default, widely compatible)
• AES-256-GCM (modern, authenticated encryption)
• AES-192-CBC
• See openssl_get_cipher_methods() for full list

⚠️ CRITICAL WARNING:

• Only change BEFORE storing any credentials
• Changing after credentials are stored will make them unreadable
• Requires re-entering all API keys if changed later
• Test thoroughly after changing

---

7. Debug Mode

Filter: wpfmj_debug_mode
Default: false
Type: Boolean

Enable verbose logging for troubleshooting.

add_filter('wpfmj_debug_mode', function($debug) {
    return true; // Enable debug logging
});

What gets logged:

• API request details
• Retry attempts with timestamps
• Decryption operations
• Rate limit hits
• Form processing steps

Important:

• Only enable when troubleshooting
• Logs may contain sensitive information
• Disable in production unless necessary
• Check wp-content/debug.log

---

8. Cleanup Cron Schedule

Filter: wpfmj_cleanup_schedule
Default: weekly
Type: String

Change how often error log cleanup runs.

add_filter('wpfmj_cleanup_schedule', function($schedule) {
    return 'daily'; // Clean up more frequently
});

Available Schedules:

• hourly - Every hour
• twicedaily - Twice per day
• daily - Once per day
• weekly - Once per week (default)

Considerations:

• High-volume sites: Use daily or twicedaily
• Low-volume sites: weekly is sufficient
• More frequent = less database bloat

---

Advanced Configuration Examples

Example 1: High-Traffic Site

<?php
// wpfmj-config.php for high-traffic e-commerce site

// Aggressive cleanup to manage database size
add_filter('wpfmj_error_log_retention_days', function($days) {
    return 30; // Only 30 days
});

// Higher rate limit for busy periods
add_filter('wpfmj_api_rate_limit', function($limit) {
    return 120;
});

// More frequent cleanup
add_filter('wpfmj_cleanup_schedule', function($schedule) {
    return 'daily';
});

// Multiple notification recipients
add_filter('wpfmj_failure_notification_emails', function($emails) {
    return array(
        'dev-team@example.com',
        'ops@example.com'
    );
});

Example 2: Development Environment

<?php
// wpfmj-config.php for staging/dev environment

// Disable email spam during testing
add_filter('wpfmj_disable_failure_notifications', function($disabled) {
    return true;
});

// Enable debug mode
add_filter('wpfmj_debug_mode', function($debug) {
    return true;
});

// Lower retry attempts for faster testing
add_filter('wpfmj_max_retry_attempts', function($attempts) {
    return 1; // Fail fast
});

Example 3: Enterprise Setup

<?php
// wpfmj-config.php for enterprise with compliance requirements

// Extended retention for audit compliance
add_filter('wpfmj_error_log_retention_days', function($days) {
    return 365; // 1 year
});

// Maximum reliability
add_filter('wpfmj_max_retry_attempts', function($attempts) {
    return 5;
});

// Security team notifications
add_filter('wpfmj_failure_notification_emails', function($emails) {
    return array(
        'security@example.com',
        'compliance@example.com',
        'it-ops@example.com'
    );
});

// Use modern encryption
add_filter('wpfmj_encryption_method', function($method) {
    return 'AES-256-GCM';
});

Example 4: Minimal Configuration

<?php
// wpfmj-config.php for simple site

// Just increase error retention slightly
add_filter('wpfmj_error_log_retention_days', function($days) {
    return 120; // 4 months
});

---

Environment-Specific Configuration

You can use environment variables or constants for different environments:

<?php
// wpfmj-config.php with environment detection

// Detect environment
$is_dev = (defined('WP_DEBUG') && WP_DEBUG === true);
$is_staging = (strpos($_SERVER['HTTP_HOST'], 'staging') !== false);

if ($is_dev) {
    // Development settings
    add_filter('wpfmj_disable_failure_notifications', '__return_true');
    add_filter('wpfmj_debug_mode', '__return_true');
    add_filter('wpfmj_max_retry_attempts', function() { return 1; });
    
} elseif ($is_staging) {
    // Staging settings
    add_filter('wpfmj_error_log_retention_days', function() { return 30; });
    add_filter('wpfmj_failure_notification_emails', function() {
        return array('staging-alerts@example.com');
    });
    
} else {
    // Production settings
    add_filter('wpfmj_error_log_retention_days', function() { return 90; });
    add_filter('wpfmj_api_rate_limit', function() { return 120; });
    add_filter('wpfmj_failure_notification_emails', function() {
        return array(
            'ops@example.com',
            'monitoring@example.com'
        );
    });
}

---

Monitoring Your Configuration

Check Current Settings

Add this to a test plugin or theme's functions.php temporarily:

add_action('admin_init', function() {
    if (current_user_can('manage_options') && isset($_GET['wpfmj_check_config'])) {
        echo '<pre>';
        echo 'Error Retention: ' . apply_filters('wpfmj_error_log_retention_days', 90) . " days\n";
        echo 'API Rate Limit: ' . apply_filters('wpfmj_api_rate_limit', 60) . " req/min\n";
        echo 'Max Retries: ' . apply_filters('wpfmj_max_retry_attempts', 3) . " attempts\n";
        echo 'Debug Mode: ' . (apply_filters('wpfmj_debug_mode', false) ? 'ON' : 'OFF') . "\n";
        echo 'Notifications: ' . (apply_filters('wpfmj_disable_failure_notifications', false) ? 'DISABLED' : 'ENABLED') . "\n";
        echo '</pre>';
        exit;
    }
});

Visit: yoursite.com/wp-admin/?wpfmj_check_config

---

Troubleshooting Configuration

Configuration Not Loading

1. Check file name: Must be exactly wpfmj-config.php
2. Check file location: Must be in plugin root directory
3. Check syntax: Use PHP linter to verify no errors
4. Check filters: Ensure using add_filter() not add_action()

Values Not Changing

1. Clear caches: Object cache, opcache, page cache
2. Check filter priority: Default priority is 10
3. Verify filter name: Must match exactly (case-sensitive)
4. Test with simple value: Try returning a hardcoded value first

Debug Logging Not Working

1. Enable WordPress debug logging:

   // In wp-config.php
   define('WP_DEBUG', true);
   define('WP_DEBUG_LOG', true);
   define('WP_DEBUG_DISPLAY', false);
   

2. Check debug.log location: wp-content/debug.log

3. Verify debug mode filter is applied

---

Best Practices

DO:

✅ Use wpfmj-config.php for customizations
✅ Keep configuration in version control (except sensitive data)
✅ Document your customizations
✅ Test configuration changes in staging first
✅ Use environment detection for different setups
✅ Monitor logs after configuration changes

DON'T:

❌ Modify core plugin files directly
❌ Store sensitive data in configuration file
❌ Use extremely high rate limits without testing
❌ Disable notifications without alternative monitoring
❌ Change encryption method after storing credentials
❌ Enable debug mode in production long-term

---

Performance Considerations

Setting	Impact	Recommendation
Error Retention (Low)	Less DB storage	Good for high-volume
Error Retention (High)	More DB storage	Good for compliance
API Rate Limit (Low)	Slower processing	More reliable
API Rate Limit (High)	Faster processing	Monitor closely
Max Retries (Low)	Fast failure	Development
Max Retries (High)	Slow failure	Production
Cleanup (Frequent)	More CPU usage	High-volume sites
Cleanup (Infrequent)	Less CPU usage	Low-volume sites

---

Security Considerations

1. Never commit sensitive data: Use environment variables for secrets
2. File permissions: Set wpfmj-config.php to 644 or 600
3. Encryption changes: Only change before first use
4. Debug mode: Never leave enabled with sensitive operations
5. Email recipients: Ensure all recipients are trusted

---

Getting Help

If you need assistance with configuration:

1. Check debug logs: Enable debug mode temporarily
2. Test with defaults: Remove config file to use defaults
3. Verify syntax: Use PHP linter on config file
4. Review examples: See examples in this guide
5. Contact support: Include configuration (without sensitive data)

---

Version History

1.0.1

• Added configurable error retention period
• Added configurable API rate limiting
• Added configurable retry attempts
• Added configurable email notifications
• Added configurable encryption method
• Added debug mode
• Added cleanup schedule customization

---

Last Updated: October 16, 2025
Plugin Version: 1.0.1+
Compatibility: WordPress 5.8+, PHP 7.4+