WC Conditional International Blocker

A production-ready WordPress plugin that blocks checkout for restricted products when a customer's country is not US or is Canada. Fully HPOS-compatible and follows WordPress coding standards.

📋 Overview

This plugin prevents customers from completing checkout when their cart contains "restricted items" and they are from blocked countries. Perfect for businesses that have products with:

• Geographic licensing restrictions
• Export compliance requirements
• Service fulfillment limitations
• Regional business rules

✨ Features

Core Features

• Smart Country Detection: Shipping address → Billing address → Geolocation → Store base
• Flexible Product Targeting: Restrict by category slug or SKU
• Configurable Rules: Block all except US (default), always block Canada, plus custom country list
• Clear UX: Contextual notices on Product, Cart, Checkout, and Mini-cart pages
• Performance Optimized: Cached lookups, minimal database queries
• HPOS Compatible: Full support for WooCommerce High-Performance Order Storage
• Translation Ready: All strings translatable, .pot file included
• Developer Friendly: Dozens of filters and actions for customization

Compatibility & Integration 🆕

• 🛒 WooCommerce Blocks: Automatic Cart & Checkout block validation
• 🔌 Store API: Full validation hooks for headless checkout
• 🌐 REST API: Public endpoint (/wp-json/wc-intl-blocker/v1/evaluate) for headless themes
• ⚡ Mini-Cart Fragments: Real-time AJAX updates with accessibility (ARIA labels)
• 🎯 Headless Ready: Works with Next.js, Gatsby, Vue, React Native, and more
• 🪝 Developer Hooks: Extensible actions and filters for custom integrations

🚀 Quick Start

Installation

1. Clone or download this repository
2. Upload to /wp-content/plugins/wc-conditional-intl-blocker/
3. Activate via WordPress admin
4. Go to WooCommerce → Intl. Blocker (or click "Settings" on the plugin list)
5. Configure your blocking rules (defaults work for most cases)

Requirements

• WordPress 5.8+
• WooCommerce 8.0+
• PHP 7.4+

📁 File Structure

wc-conditional-intl-blocker/
├── wc-conditional-intl-blocker.php    # Main plugin file
├── readme.txt                          # WordPress.org readme
├── uninstall.php                       # Cleanup on uninstall
├── composer.json                       # Dev dependencies
├── phpcs.xml                           # Code standards config
├── .gitignore                          # Git ignore rules
├── TECHNICAL-SPEC.md                   # Full technical specification
├── README.md                           # This file
│
├── includes/                           # Core plugin classes
│   ├── class-plugin.php               # Bootstrap & loader
│   ├── class-settings.php             # Admin settings + validation
│   ├── class-rules.php                # Country detection & blocking
│   ├── class-targets.php              # Product restriction checks
│   ├── class-checker.php              # Cart validation engine
│   ├── class-notices.php              # Frontend notices
│   ├── class-compat.php               # HPOS, Blocks, REST API
│   ├── helpers.php                    # Utility functions
│   └── blocks/
│       └── class-blocks-integration.php  # WC Blocks support
│
├── assets/                             # Styles
│   ├── admin.css                      # Admin panel styles
│   └── frontend.css                   # User-facing styles
│
└── languages/                          # Translations
    └── wc-conditional-intl-blocker.pot # Translation template

⚙️ Configuration

Default Behavior

Out of the box:

• ✅ Blocks all countries except US
• ✅ Always blocks Canada (even if trying to enable it)
• ✅ Restricts products in categories: service, epus
• ✅ Shows warning notices to affected customers

Admin Settings

Navigate to WooCommerce → Intl. Blocker:

Blocking Rules:

• ☑️ Block all countries except US (checkbox, default: checked)
• ☑️ Always block Canada (checkbox, default: checked)
• 🌍 Additional blocked countries (multiselect with search)

Targets:

• 🏷️ Target categories (tag-like input, accepts slugs or names)
  • Default: service, epus
  • Shows resolved term IDs below field
  • Auto-trims and de-dupes entries
• 📦 Target SKUs (textarea, CSV format)
  • Automatically trimmed, uppercased, and de-duplicated on save

Behavior:

• 🔘 Mixed cart handling (radio buttons):
  • Block entire order - Customer must remove restricted items (default)
  • Require removal - Force removal on checkout attempt

Messages:

• 📝 Product notice (textarea) - Shown on product pages
• 📝 Cart banner (textarea) - Shown at top of cart
• 📝 Checkout error (textarea) - Blocks checkout completion
• 🔗 Contact link URL (text input) - Used in [contact_link] shortcode
  • Default: /contact
  • Supports relative paths or full URLs (including mailto:)

Reset to Defaults:

• 🔄 Button with confirmation prompt (restores all default values)

🔧 Developer Guide

Architecture

The plugin uses a modular, namespaced architecture:

WCIntlBlocker\
├── Plugin        # Main coordinator
├── Settings      # Settings management
├── Rules         # Country logic
├── Targets       # Product targeting
├── Checker       # Decision engine
├── Notices       # User feedback
└── Compat        # Compatibility layer

Key Classes

Rules - Country detection and blocking:

$rules = Plugin::instance()->rules;
$country = $rules->get_customer_country();
$blocked = $rules->is_country_blocked( $country );

Targets - Product restriction checks:

$targets = Plugin::instance()->targets;
$is_restricted = $targets->is_product_restricted( $product_id );

Checker - Cart validation:

$checker = Plugin::instance()->checker;
$validation = $checker->get_cart_validation_result();
// Returns: ['blocked' => bool, 'restricted_items' => array, 'country' => string]

Available Filters

Override country detection:

add_filter( 'wc_cib_detected_country', function( $country, $method ) {
    // Force US for testing
    return 'US';
}, 10, 2 );

Modify blocked countries:

add_filter( 'wc_cib_blocked_countries', function( $countries ) {
    $countries[] = 'GB'; // Add UK to blocked list
    return $countries;
} );

Override product restriction:

add_filter( 'wc_cib_is_product_restricted', function( $is_restricted, $product_id ) {
    if ( 123 === $product_id ) {
        return false; // Always allow product 123
    }
    return $is_restricted;
}, 10, 2 );

Customize notice messages:

add_filter( 'wc_cib_notice_message', function( $message, $context, $product_id ) {
    if ( 'product' === $context ) {
        return 'Custom product restriction message';
    }
    return $message;
}, 10, 3 );

Available Actions

Log restriction events:

add_action( 'wc_cib_restriction_triggered', function( $country, $cart_items, $context ) {
    // Send email alert, log to analytics, etc.
    error_log( sprintf( 'Restriction: %s blocked with %d items', $country, count( $cart_items ) ) );
}, 10, 3 );

React to settings changes:

add_action( 'wc_cib_settings_saved', function( $old_settings, $new_settings ) {
    // Clear external caches, update integrations, etc.
}, 10, 2 );

Helper Functions

All helper functions are in the WCIntlBlocker namespace:

use function WCIntlBlocker\wc_cib_parse_csv;
use function WCIntlBlocker\wc_cib_clear_all_caches;
use function WCIntlBlocker\wc_cib_log;

// Parse CSV setting
$categories = wc_cib_parse_csv( 'service,epus,custom' );

// Clear all caches
wc_cib_clear_all_caches();

// Debug logging
wc_cib_log( 'Custom validation check', 'info' );

🧪 Testing

Manual Testing Checklist

1. Basic Restriction - Add restricted product, enter CA address, verify blocked
2. Allowed Country - Same product, enter US address, verify allowed
3. SKU Targeting - Add SKU to list, verify blocked correctly
4. Mixed Cart - Restricted + unrestricted items, verify behavior mode
5. Virtual Products - Digital item uses billing country correctly
6. Country Change - Change mid-checkout, verify cache clears
7. Product Notice - View restricted product page, see warning
8. Mini-Cart - Add restricted item, check mini-cart notice
9. Settings Save - Update settings, verify persistence
10. Cache Clear - Remove restricted item, verify checkout unblocked

Code Quality

Run PHP CodeSniffer:

composer install
composer phpcs

Auto-fix issues:

composer phpcbf

📝 To-Do / Roadmap

Completed ✅

• [x] Unit tests (PHPUnit) - 59 tests
• [x] Integration tests - Manual testing guide with 37 scenarios
• [x] WooCommerce Blocks support - Cart & Checkout blocks
• [x] REST API endpoint for headless themes
• [x] Store API validation hooks

Planned

• [ ] WP-CLI commands (e.g., wp wc-intl-blocker check-product <id>)
• [ ] Email notifications to admin when checkout blocked
• [ ] Analytics dashboard (show blocked checkout statistics)
• [ ] Bulk product tools (apply/remove restrictions in bulk)
• [ ] Export/import settings (JSON format)
• [ ] GraphQL endpoint (WPGraphQL integration)
• [ ] Webhook support (notify external systems on block)

🤝 Contributing

Contributions are welcome! Please:

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

📄 License

GPL v3 or later. See LICENSE file.

🆘 Support & Documentation

📚 Complete Documentation Index

See docs/README.md for full documentation index with quick links

User Guides 📖

• 🎯 Admin Guide: See docs/admin-guide.md - Step-by-step setup (50+ pages, 17 screenshots)
• ❓ FAQ: See docs/faq.md - 30+ questions answered (geolocation, virtual products, Canada blocking)
• 📝 Changelog: See docs/changelog.md - Version history and release notes

Developer Guides 🔧

• 📖 Technical Specification: See TECHNICAL-SPEC.md for detailed technical docs
• 🌐 Compatibility Layer Guide: See COMPAT-LAYER-GUIDE.md for REST API, Store API, and headless integration (850+ lines)
• 🚀 Quick Start: See COMPAT-QUICKSTART.md for 5-minute integration guide
• ⚙️ Settings Guide: See SETTINGS-GUIDE.md for admin configuration

Testing & Quality 🧪

• ✅ Testing Guide: See docs/testing.md for 37 manual test scenarios
• 🧪 PHPUnit Setup: See TESTING-QUICKSTART.md for test suite setup
• 📋 Test Suite: See tests/README.md for comprehensive testing documentation

Release Management 🚀

• 📋 Release Checklist: See RELEASE-CHECKLIST.md - 130+ item checklist for releases
• 🔨 Build System: Run composer build to create distributable ZIP

Support Channels

• Issues: GitHub Issues
• Discussions: GitHub Discussions

🎯 Use Cases

Example 1: Service-Based Products

You offer consulting services that require US-based delivery. Set target categories to service and customers from other countries will see clear notices and be unable to checkout.

Example 2: Compliance Requirements

You have products with export restrictions. Add restricted product SKUs, and the plugin handles the blocking automatically while allowing unrestricted products to ship anywhere.

Example 3: Mixed Catalog

Your store has both international and US-only products. The plugin intelligently allows international customers to buy unrestricted items while blocking restricted ones.

🔒 Security

• All input sanitized and validated
• Output properly escaped
• Nonces on all forms
• Capability checks on admin functions
• No SQL injection vulnerabilities
• CSRF protection

🌍 Translation

The plugin is translation-ready. To translate:

1. Use the .pot file in /languages/
2. Create .po and .mo files for your language
3. Place in /wp-content/languages/plugins/

📊 Performance

• Country detection: < 50ms (cached)
• Product check: < 20ms (cached)
• Cart validation (10 items): < 200ms
• Database queries: 3-5 per checkout flow
• Transient caching: 60min (country), 24h (products)

⚡ Compatibility

• ✅ WooCommerce 8.0 - 9.0+
• ✅ High-Performance Order Storage (HPOS)
• ✅ WooCommerce Blocks (Cart & Checkout)
• ✅ WooCommerce Subscriptions
• ✅ WooCommerce Product Bundles
• ✅ Multisite
• ✅ REST API
• ✅ Popular cache plugins
• ✅ PHP 7.4 - 8.2+

---

Made with ❤️ for WooCommerce developers

For questions or support, please open an issue on GitHub.