Smart Country Blocker

Description

IMPORTANT: This plugin uses external third-party services (ipwho.is and ipapi.co) to determine visitor location. Please review the “External Services” section below for details on data transmission and privacy.

Smart Country Blocker is a powerful WordPress plugin that allows you to restrict access to your website based on visitor location. Block unwanted traffic from specific countries on both frontend pages and backend admin areas.

Key Features:

• 🌍 Complete Country List – Select from 195+ countries worldwide
• 🎯 Frontend & Backend Blocking – Block both website pages and wp-admin/wp-login.php
• 📊 Comprehensive Logging – Track all blocked access attempts with IP, country, URL, and timestamp
• 📈 Statistics Dashboard – View total blocks, unique IPs, and blocked countries count
• 🔍 Advanced Filtering – Filter and sort logs by country, date, IP address
• 📄 Pagination – Manage large log datasets with 20 records per page
• ⚡ Quick Remove – Remove countries from blocked list with one click
• 🔒 Cache-Friendly – Compatible with major caching plugins (see configuration below)
• 🎨 Customizable Block Page – Edit blocked.php to customize the access denied page
• 🖥️ Easy-to-Use Interface – Checkbox selection with search functionality

Important: Cache Plugin Compatibility

CRITICAL: If you use a caching plugin (WP Rocket, W3 Total Cache, WP Super Cache, LiteSpeed Cache, etc.), cached pages may bypass country blocking. Follow these configuration steps:

WP Rocket Configuration

WP Rocket should work automatically as the plugin sets the DONOTCACHEPAGE constant. However, for best results:

1. Go to WP Rocket > Settings > Advanced Rules
2. Add this to “Never Cache URL(s)”:
   /(.*)
   (Only if you want to disable cache completely for blocked countries)
3. The plugin automatically prevents caching for blocked visitors

W3 Total Cache Configuration

1. Go to Performance > Page Cache
2. Scroll to “Never cache the following pages:”
3. Add: * (if you want complete blocking to bypass cache)
4. OR go to Performance > General Settings
5. Enable “Page Cache” > “Don’t cache pages for logged in users”

WP Super Cache Configuration

WP Super Cache should work automatically as the plugin sets no-cache headers. To verify:

1. Go to Settings > WP Super Cache
2. Make sure “Don’t cache pages with GET parameters” is enabled
3. The plugin sends proper no-cache headers for blocked visitors

LiteSpeed Cache Configuration

1. Go to LiteSpeed Cache > Cache
2. Under “Do Not Cache URIs”, you can add specific paths if needed
3. The plugin sets proper cache bypass constants

Cloudflare Configuration

If using Cloudflare:

1. Go to Cloudflare Dashboard > Rules > Page Rules
2. Add a rule: yoursite.com/*
3. Set “Cache Level” to “Bypass” (optional, only if experiencing issues)
4. Or add IP-based rules in Cloudflare’s Firewall

Testing After Configuration

Always test blocking functionality:

1. Connect to a VPN from a blocked country
2. Try to access your website
3. You should see the “Access Restricted” page
4. Check Block Logs in the plugin to confirm the block was logged
5. If you can still access, clear your cache plugin cache and test again

Usage

Blocking Countries

1. Go to Country Blocker in WordPress admin
2. Use the search box to quickly find countries
3. Check/uncheck countries to block/unblock
4. Click Save Changes
5. Use “Select All” or “Deselect All” for bulk operations

Quick Remove Blocked Countries

1. View the “Currently Blocked Countries” section at the top
2. Click the × button next to any country to remove it instantly
3. Confirm the removal in the popup

Viewing Block Logs

1. Go to Country Blocker > Block Logs
2. See statistics: Total Blocks, Unique IPs, Countries Blocked, Last 7 Days
3. Filter logs by country, sort by date/IP/country
4. View detailed information: IP address, country, access type (frontend/backend), URL, timestamp
5. Use pagination to navigate through logs

Clearing Logs

Click Clear All Logs button to remove all historical block records. This cannot be undone.

External Services

This plugin relies on third-party GeoIP services to determine visitor location based on their IP address. These services are essential for the plugin’s core functionality.

ipwho.is (Primary Service — default)

What it does: Provides IP geolocation data to identify the visitor’s country.

When data is sent: Every time a new visitor accesses your website from an IP address not cached in the last hour. The plugin sends the visitor’s IP address to ipwho.is API.

Data transmitted: Only the visitor’s IP address is sent to the API. No personal information, cookies, or user data is transmitted.

Caching: Results are cached for 1 hour per IP address to minimize API calls and improve performance.

Service provider: ipwho.is is a free IP geolocation service.

Website: https://ipwho.is/

API Documentation: https://ipwho.is/

Terms of Service: https://ipwho.is/ (see website footer for terms)

Privacy Policy: https://ipwho.is/ (see website footer for privacy policy)

findip.net (Optional Alternative Service)

What it does: An alternative IP geolocation service you can use instead of ipwho.is. Requires a free API key.

When data is sent: When configured as the primary service, the visitor’s IP address is sent to findip.net on each uncached lookup.

Data transmitted: Only the visitor’s IP address is sent to the API. No personal information, cookies, or user data is transmitted.

Service provider: findip.net is an IP geolocation service using GeoNames / MaxMind data.

API key: A free account and API token are required. Sign up at https://findip.net/ and enter the token in Country Blocker > API Settings.

Website: https://findip.net/

API Documentation: https://findip.net/

Terms of Service: https://findip.net/ (see website for current terms of service)

Privacy Policy: https://findip.net/ (see website for privacy policy information)

Note: By using findip.net, you agree to their terms of service and privacy policy as outlined on their website.

ipapi.co (Fallback Service)

What it does: Acts as a backup geolocation service if the primary service (ipwho.is or findip.net) fails or is unavailable.

When data is sent: Only when the primary service fails to respond or returns an error. The plugin automatically tries ipapi.co as a fallback.

Data transmitted: Only the visitor’s IP address is sent to the API. No personal information, cookies, or user data is transmitted.

Service provider: ipapi.co is a free IP geolocation service with rate limits (30,000 requests/month for free tier).

Terms of Service: https://ipapi.co/terms/

Privacy Policy: https://ipapi.co/privacy/

API Documentation: https://ipapi.co/api/

Data Protection & Privacy

• The plugin does NOT send any personal user data, cookies, form inputs, or browsing history to external services.
• Only IP addresses are transmitted, which are necessary for geolocation functionality.
• API requests are made server-side; visitor browsers do not directly contact these services.
• Failed API lookups are logged locally for troubleshooting purposes.
• All API requests use HTTPS (SSL) encryption.

Legal Compliance

If you operate in regions with strict privacy laws (GDPR, CCPA, etc.), please be aware:
– IP addresses may be considered personal data under some regulations.
– Consider adding a privacy notice informing users that their IP addresses may be processed for access control.
– The plugin logs blocked access attempts (IP + country + timestamp) in your WordPress database for security purposes.

Technical Details

Database Table

The plugin creates wp_country_blocker_logs table with the following structure:
– id (Primary Key)
– ip_address (VARCHAR 45)
– country_code (VARCHAR 2)
– country_name (VARCHAR 100)
– blocked_url (TEXT)
– user_agent (TEXT)
– access_type (VARCHAR 20) – ‘frontend’ or ‘backend’
– blocked_at (DATETIME)

Hooks Used

• plugins_loaded (priority -999999) – Early blocking execution
• admin_menu – Register admin pages
• admin_notices – Show cache configuration notice

Constants Defined

Important Note About Unprefixed Constants:

This plugin defines industry-standard cache bypass constants that are intentionally unprefixed and cannot be changed. These constants have been the de-facto standard in the WordPress caching ecosystem for over 15 years and are recognized by virtually all caching plugins and CDN services.

Why these constants MUST remain unprefixed:

These constants are NOT WordPress core constants. They are industry standards established by the caching plugin ecosystem. WP Rocket, LiteSpeed Cache, W3 Total Cache, WP Super Cache, and dozens of other caching/CDN plugins specifically check for these exact constant names.

Prefixing these constants (e.g., changing DONOTCACHEPAGE to WPCB_DONOTCACHEPAGE) would break compatibility with all major caching plugins, rendering the blocking functionality useless on cached sites.

Constants used for cache bypass (when blocking visitors):

• DONOTCACHEPAGE – Prevents page caching (WP Rocket, LiteSpeed Cache, W3 Total Cache, WP Super Cache)
• DONOTCACHEDB – Prevents database query caching (W3 Total Cache)
• DONOTMINIFY – Prevents JS/CSS minification (Autoptimize, WP Rocket, Fast Velocity Minify)
• DONOTCDN – Prevents CDN URL rewriting (CDN Enabler, W3 Total Cache CDN module)
• DONOTCACHEOBJECT – Prevents object caching (LiteSpeed Cache, W3 Total Cache)

These constants are set ONLY when a visitor is being blocked (403 response), not globally. They signal to caching plugins: “Do not cache this specific request.”

References:
– WP Rocket Documentation: https://docs.wp-rocket.me/article/61-disable-page-caching
– LiteSpeed Cache Documentation: https://docs.litespeedtech.com/lscache/lscwp/cache/#do-not-cache-constants

This is an accepted exception to WordPress naming conventions and is properly documented in the code with phpcs ignore comments.

Support

For support, bug reports, or feature requests, please contact the developer.

Privacy

This plugin logs IP addresses and country information for security purposes. Ensure compliance with GDPR/privacy laws in your jurisdiction. Consider adding a privacy notice to inform users that their IP addresses may be logged if they attempt to access from blocked countries.