Form GeoGuard

A WordPress plugin that filters form submissions based on IP geolocation with a focus on GDPR compliance. This plugin helps businesses prevent data collection from regions they don't serve, implementing privacy-by-design principles.

Features

🌍 Geolocation Protection

• Allow-list and block-list functionality for flexible country filtering
• Real-time location checking without page refreshes
• Enhanced cloud provider detection - Supports 7 major cloud providers (AWS, GCP, Azure, DigitalOcean, Linode, Vultr, Oracle Cloud)
• Advanced email pattern filtering - Block submissions based on email regex patterns

🔒 GDPR Compliant

• Privacy-by-design - IP addresses are checked and immediately discarded
• No data logging by default (optional analytics with country codes only)
• Automatic privacy policy integration
• Data export/erasure tool support

🔌 Form Builder Integrations

• Contact Form 7 - Native integration with custom form tags
• Gravity Forms - Complete integration with custom fields and form settings
• WPForms - Silent filtering with entry deletion and notification blocking
• Ninja Forms - Complete silent filtering with action filtering
• Forminator - Pre-submission checking with email blocking and entry deletion
• Extensible architecture for additional form builder support

⚙️ Easy Management

• Comprehensive admin interface with tabbed settings (General, Database, Integrations, Country Settings, Advanced Filters)
• Country selector with all 249 countries/territories and search functionality
• Automatic database updates from ip-location-db (weekly)
• Enhanced cloud provider data from community GitHub sources (lord-alfred/ipranges)
• Manual database controls with bundled data import
• Activity logging with CSV export and GDPR compliance

Installation

From WordPress Admin

1. Go to Plugins > Add New
2. Search for "Form GeoGuard"
3. Install and activate the plugin
4. Go to Settings > Form GeoGuard to configure

Manual Installation

1. Download the plugin zip file
2. Upload to /wp-content/plugins/ directory
3. Activate the plugin through the WordPress 'Plugins' menu
4. Configure settings at Settings > Form GeoGuard

From GitHub

cd /path/to/wordpress/wp-content/plugins/
git clone https://github.com/supersoju/form-geoguard.git

Quick Start

1. Configure Countries

1. Go to Settings > Form GeoGuard
2. Choose Allow List (only selected countries) or Block List (block selected countries)
3. Select your target countries

2. Enable Form Protection

Contact Form 7

Option A: Automatic (Recommended)

• Enable "Contact Form 7" in plugin settings to protect all CF7 forms

Option B: Manual

• Add [geoguard geoguard-field] to specific Contact Form 7 forms

Gravity Forms

Option A: Form Settings

• Edit any Gravity Form → Form Settings
• Enable "GeoGuard Protection"

Option B: Field Method

• Add "GeoGuard" field from Advanced Fields section

Option C: Global

• Enable "Gravity Forms" in plugin settings for automatic protection

WPForms

• Enable "WPForms" in plugin settings for automatic protection of all forms
• Silent filtering with automatic entry deletion for blocked submissions

Ninja Forms

• Enable "Ninja Forms" in plugin settings for automatic protection of all forms
• Complete silent filtering with action filtering and success message illusion

Forminator

• Enable "Forminator" in plugin settings for automatic protection of all forms
• Pre-submission geolocation checking with email blocking and entry deletion

3. Update IP Database

• The plugin automatically updates the IP database weekly
• Manual update available in Settings > Form GeoGuard > Database

Configuration Options

General Settings

• Filter Mode: Allow List or Block List
• Analytics: Optional logging of blocked attempts (country codes only)

Country Settings

• Allow List: Only permit submissions from selected countries
• Block List: Block submissions from selected countries
• Select/Deselect All buttons for easy management

Database Management

• Automatic Updates: Weekly updates from ip-location-db
• Manual Controls: Update or clear database on demand
• Statistics: View database status and country coverage

Integrations

• Contact Form 7: Enable/disable CF7 integration
• Gravity Forms: Enable/disable GF integration
• WPForms: Enable/disable WPForms integration
• Ninja Forms: Enable/disable Ninja Forms integration
• Forminator: Enable/disable Forminator integration
• Status Indicators: See which form builders are active

Technical Details

Requirements

• WordPress: 5.8 or higher
• PHP: 7.4 or higher
• Form Builders: Contact Form 7, Gravity Forms, WPForms, Ninja Forms, Forminator (all optional)

IP Database Sources

• Geolocation: ip-location-db (free, GitHub-based)
• Cloud Providers: lord-alfred/ipranges (community-maintained)
• Coverage: 1,240+ cloud provider IP ranges across 7 major providers
• Supports both IPv4 and IPv6 addresses
• No API keys or external services required

Performance

• Database optimization: Indexed IP range queries
• Minimal overhead: AJAX requests only when needed
• Cache compatibility: Works with all major caching plugins

Privacy & Security

• No IP logging: IP addresses are never stored
• GDPR compliant: Privacy-by-design implementation
• Security headers: Proper nonce verification
• Input validation: All user inputs sanitized

Development

File Structure

form-geoguard/
├── form-geoguard.php                          # Main plugin file
├── includes/
│   ├── class-form-geoguard.php                # Core plugin class
│   ├── class-geo-detector.php                 # IP geolocation detection
│   ├── class-admin-interface.php              # Admin interface
│   ├── class-logger.php                       # GDPR-compliant activity logging
│   ├── class-utils.php                        # Shared utilities
│   ├── class-database-importer.php            # Database import handler
│   ├── class-email-filter.php                 # Email pattern filtering
│   └── integrations/
│       ├── class-cf7-integration.php          # Contact Form 7 integration
│       ├── class-gravityforms-integration.php # Gravity Forms integration
│       ├── class-wpforms-integration.php      # WPForms integration
│       ├── class-ninjaforms-integration.php   # Ninja Forms integration
│       └── class-forminator-integration.php   # Forminator integration
├── data/                                      # Bundled IP databases (in releases)
│   ├── geo-ipv4.csv                          # IPv4 geolocation data
│   ├── geo-ipv6.csv                          # IPv6 geolocation data
│   ├── aws-ranges.json                       # AWS IP ranges
│   ├── gcp-ranges.json                       # Google Cloud IP ranges
│   ├── enhanced-cloud-ranges.json            # Additional cloud providers (DigitalOcean, Linode, etc.)
│   └── database-info.txt                     # Metadata (download time, source)
├── scripts/
│   ├── download-enhanced-cloud-data.php      # Enhanced cloud provider data downloader
│   ├── download-standalone.php               # Standalone database downloader
│   ├── download-bundled-data.php             # WordPress-integrated downloader
│   └── download-data.sh                      # Shell wrapper script
├── assets/
│   ├── js/
│   │   ├── frontend.js                        # Main frontend JavaScript
│   │   ├── cf7-integration.js                 # CF7-specific JavaScript
│   │   └── gravityforms-integration.js        # GF-specific JavaScript
│   └── css/
│       └── admin.css                          # Admin interface styles
└── languages/                                 # Translation files

Hooks & Filters

Actions

• form_geoguard_ip_checked - Fired after IP geolocation check
• form_geoguard_cf7_blocked - Contact Form 7 submission blocked
• form_geoguard_gf_blocked - Gravity Forms submission blocked
• form_geoguard_wpforms_blocked - WPForms submission blocked
• form_geoguard_ninjaforms_blocked - Ninja Forms submission blocked
• form_geoguard_forminator_blocked - Forminator submission blocked

Filters

• form_geoguard_cf7_always_check - Force checking for all CF7 forms
• form_geoguard_gf_always_check - Force checking for all GF forms
• form_geoguard_wpforms_always_check - Force checking for all WPForms
• form_geoguard_ninjaforms_always_check - Force checking for all Ninja Forms
• form_geoguard_forminator_always_check - Force checking for all Forminator forms
• form_geoguard_log_retention_days - Modify log retention period

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

Documentation

• Installation Guide
• Configuration Guide
• Developer Documentation

Issues

• Bug Reports
• Feature Requests

License

This project is licensed under the GPL v2 or later - see the LICENSE file for details.

Acknowledgments

• ip-location-db for providing free IP geolocation data
• WordPress community for excellent plugin development resources
• Contact Form 7, Gravity Forms, WPForms, Ninja Forms, and Forminator teams for extensible form builders

Form GeoGuard - Protect your forms with geolocation filtering while respecting user privacy.