Postal Check for WooCommerce

A lightweight WooCommerce plugin that adds postal code validation on the cart page before allowing users to proceed to checkout. Similar to Shopify, it prevents users from proceeding to checkout until they enter a valid postal code from your predefined delivery areas.

✨ Features

• 🎯 Simple Setup: Easy-to-use admin panel for managing postal codes
• 🚀 AJAX Powered: Real-time validation without page reloads
• 🔒 Secure: Backend validation prevents frontend bypass
• 📱 Responsive: Works with all WooCommerce-compatible themes
• 🎨 Clean Interface: Minimal, professional design
• 📦 Bulk Operations: Import/export postal codes in bulk
• 🔄 Backward Compatible: Migrates existing hardcoded codes seamlessly

📸 Screenshots

Cart Page Validation

[Cart Items]
┌─────────────────────────────────────┐
│ Check Delivery Area                  │
│ Enter your postal code to check     │
│ if we deliver to your area:         │
│                                     │
│ [Enter postal code] [Check]         │
│                                     │
│ ✅ Congratulations! You can proceed │
│    to checkout                       │
└─────────────────────────────────────┘
[Cart Totals]
[Proceed to Checkout] ← Enabled after validation

Admin Panel

WooCommerce → Postal Check
┌─────────────────────────────────────┐
│ Add Postal Code                     │
│ [Enter postal code] [Add]          │
├─────────────────────────────────────┤
│ Import Multiple Postal Codes        │
│ [10001, 10002, 10003]             │
│ [Import Postal Codes]              │
├─────────────────────────────────────┤
│ Current Postal Codes (15)           │
│ [10001] [Remove]  [10002] [Remove] │
│ [10003] [Remove]  [10004] [Remove] │
├─────────────────────────────────────┤
│ Export Postal Codes                 │
│ [10001, 10002, 10003...]           │
│ [Copy to Clipboard]                │
└─────────────────────────────────────┘

🚀 Installation

Method 1: WordPress Admin (Recommended)

1. Download the latest release from the GitHub repository
2. Go to WordPress Admin → Plugins → Add New
3. Click Upload Plugin and select the downloaded ZIP file
4. Activate the plugin
5. Go to WooCommerce → Postal Check to configure your postal codes

Method 2: Manual Installation

1. Clone or download this repository
2. Upload the postal-check folder to /wp-content/plugins/
3. Go to WordPress Admin → Plugins
4. Find "Postal Check for WooCommerce" and Activate
5. Configure your postal codes in WooCommerce → Postal Check

Method 3: Composer

composer require yourusername/postal-check-for-woocommerce

⚙️ Configuration

Adding Postal Codes

1. Go to WooCommerce → Postal Check
2. Single Code: Enter a postal code and click "Add Postal Code"
3. Bulk Import: Paste multiple codes (comma or newline separated) and click "Import Postal Codes"
4. Export: Copy all codes using the "Copy to Clipboard" button

Supported Formats

• Single Code: 10001
• Multiple Codes: 10001, 10002, 10003
• Newline Separated:

  10001
  10002
  10003

🛠️ Development

Local Development Setup

# Clone the repository
git clone https://github.com/yourusername/postal-check-for-woocommerce.git
cd postal-check-for-woocommerce

# Install development dependencies (if using npm)
npm install

# Start development server (if applicable)
npm run dev

Plugin Structure

postal-check/
├── postal-check.php          # Main plugin file
├── assets/
│   ├── postal-check.js       # Frontend JavaScript
│   └── admin.js              # Admin panel JavaScript
├── README.md                 # This file
├── readme.txt                # WordPress readme
├── LICENSE                   # GPL v2 license
├── .gitignore               # Git ignore file
├── CONTRIBUTING.md           # Contribution guidelines
└── installation-instructions.md # Installation guide

Hooks and Filters

The plugin provides several hooks for customization:

// Add custom postal codes programmatically
add_filter('postal_check_allowed_codes', function($codes) {
    $codes[] = 'CUSTOM_CODE';
    return $codes;
});

// Modify validation logic
add_filter('postal_check_validate_code', function($is_valid, $postal_code) {
    // Custom validation logic
    return $is_valid;
}, 10, 2);

🔧 Customization

Custom Styling

Add custom CSS to your theme's style.css:

/* Postal check container */
.postal-check-container {
    border: 2px solid #0073aa;
    border-radius: 8px;
}

/* Success message */
.postal-check-container .success-message {
    background-color: #d4edda;
    color: #155724;
}

/* Error message */
.postal-check-container .error-message {
    background-color: #f8d7da;
    color: #721c24;
}

Custom Messages

Use WordPress filters to modify messages:

add_filter('postal_check_messages', function($messages) {
    $messages['valid'] = 'Great! We deliver to your area!';
    $messages['invalid'] = 'Sorry, we don\'t deliver to your area yet.';
    return $messages;
});

🧪 Testing

Unit Tests

# Run tests (if using PHPUnit)
./vendor/bin/phpunit

Manual Testing Checklist

• [ ] Plugin activates without errors
• [ ] Admin panel loads correctly
• [ ] Can add/remove postal codes
• [ ] Bulk import/export works
• [ ] Cart page validation works
• [ ] Checkout protection works
• [ ] Works with different themes
• [ ] Works with WooCommerce variations

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Steps

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

📋 Requirements

• WordPress: 5.0 or higher
• WooCommerce: 3.0 or higher
• PHP: 7.4 or higher (recommended 8.0+)
• Memory: 64MB or higher

🔒 Security

This plugin follows WordPress security best practices:

• ✅ All user input is sanitized
• ✅ Nonce verification for AJAX requests
• ✅ Capability checks for admin functions
• ✅ SQL injection prevention
• ✅ XSS protection

📝 Changelog

[1.1.0] - 2024-04-14

Added

• 🎯 Admin panel for postal code management
• 📦 Bulk import/export functionality
• 🔄 AJAX-powered real-time updates
• 📊 Postal code count display
• 🎨 Enhanced admin interface

Changed

• 🔧 Updated validation to use database storage
• 📱 Improved mobile responsiveness
• 🛡️ Enhanced security measures

[1.0.0] - 2024-04-14

Added

• 🎉 Initial release
• ✅ Basic postal code validation
• 🛒 Cart page integration
• 🔒 Checkout protection
• 📝 Session storage

🐛 Bug Reports

Found a bug? Please open an issue with:

• WordPress version
• WooCommerce version
• PHP version
• Theme being used
• Steps to reproduce
• Expected vs actual behavior

📞 Support

• GitHub Issues: Create an issue
• WordPress.org: Support forum
• Documentation: Wiki

🙏 Credits

• Built with ❤️ for the WooCommerce community
• Follows WordPress Coding Standards
• Uses WooCommerce best practices

📄 License

This plugin is licensed under the GPL v2 License.

🌟 Star History

---

Made with ❤️ for the WooCommerce community