# Validation Filter Hooks WooNooW provides extensible validation filter hooks that allow addons to integrate external validation services for emails and phone numbers. ## Email Validation ### Filter: `woonoow/validate_email` Validates email addresses with support for external API integration. **Parameters:** - `$is_valid` (bool|WP_Error): Initial validation state (default: true) - `$email` (string): The email address to validate - `$context` (string): Context of validation (e.g., 'newsletter_subscribe', 'checkout', 'registration') **Returns:** `true` if valid, `WP_Error` if invalid **Built-in Validation:** 1. WordPress `is_email()` check 2. Regex pattern validation: `xxxx@xxxx.xx` format 3. Extensible via filter hook ### Example: QuickEmailVerification.com Integration ```php add_filter('woonoow/validate_email', function($is_valid, $email, $context) { // Only validate for newsletter subscriptions if ($context !== 'newsletter_subscribe') { return $is_valid; } $api_key = get_option('my_addon_quickemail_api_key'); if (!$api_key) { return $is_valid; // Skip if no API key configured } // Call QuickEmailVerification API $response = wp_remote_get( "https://api.quickemailverification.com/v1/verify?email={$email}&apikey={$api_key}", ['timeout' => 5] ); if (is_wp_error($response)) { // Fallback to basic validation on API error return $is_valid; } $data = json_decode(wp_remote_retrieve_body($response), true); // Check validation result if (isset($data['result']) && $data['result'] !== 'valid') { return new WP_Error( 'email_verification_failed', sprintf('Email verification failed: %s', $data['reason'] ?? 'Unknown'), ['status' => 400] ); } return true; }, 10, 3); ``` ### Example: Hunter.io Email Verification ```php add_filter('woonoow/validate_email', function($is_valid, $email, $context) { $api_key = get_option('my_addon_hunter_api_key'); if (!$api_key) return $is_valid; $response = wp_remote_get( "https://api.hunter.io/v2/email-verifier?email={$email}&api_key={$api_key}" ); if (is_wp_error($response)) return $is_valid; $data = json_decode(wp_remote_retrieve_body($response), true); if ($data['data']['status'] !== 'valid') { return new WP_Error('email_invalid', 'Email address is not deliverable'); } return true; }, 10, 3); ``` --- ## Phone Validation ### Filter: `woonoow/validate_phone` Validates phone numbers with support for external API integration and WhatsApp verification. **Parameters:** - `$is_valid` (bool|WP_Error): Initial validation state (default: true) - `$phone` (string): The phone number to validate (cleaned, no formatting) - `$context` (string): Context of validation (e.g., 'checkout', 'registration', 'shipping') - `$country_code` (string): Country code if available (e.g., 'ID', 'US') **Returns:** `true` if valid, `WP_Error` if invalid **Built-in Validation:** 1. Format check: 8-15 digits, optional `+` prefix 2. Removes common formatting characters 3. Extensible via filter hook ### Example: WhatsApp Number Verification ```php add_filter('woonoow/validate_phone', function($is_valid, $phone, $context, $country_code) { // Only validate for checkout if ($context !== 'checkout') { return $is_valid; } $api_token = get_option('my_addon_whatsapp_api_token'); if (!$api_token) return $is_valid; // Check if number is registered on WhatsApp $response = wp_remote_post('https://api.whatsapp.com/v1/contacts', [ 'headers' => [ 'Authorization' => 'Bearer ' . $api_token, 'Content-Type' => 'application/json', ], 'body' => json_encode([ 'blocking' => 'wait', 'contacts' => [$phone], ]), 'timeout' => 10, ]); if (is_wp_error($response)) { return $is_valid; // Fallback on API error } $data = json_decode(wp_remote_retrieve_body($response), true); // Check if WhatsApp ID exists if (!isset($data['contacts'][0]['wa_id'])) { return new WP_Error( 'phone_not_whatsapp', 'Phone number must be registered on WhatsApp for order notifications', ['status' => 400] ); } return true; }, 10, 4); ``` ### Example: Numverify Phone Validation ```php add_filter('woonoow/validate_phone', function($is_valid, $phone, $context, $country_code) { $api_key = get_option('my_addon_numverify_api_key'); if (!$api_key) return $is_valid; $url = sprintf( 'http://apilayer.net/api/validate?access_key=%s&number=%s&country_code=%s', $api_key, urlencode($phone), urlencode($country_code) ); $response = wp_remote_get($url, ['timeout' => 5]); if (is_wp_error($response)) return $is_valid; $data = json_decode(wp_remote_retrieve_body($response), true); if (!$data['valid']) { return new WP_Error( 'phone_invalid', sprintf('Invalid phone number: %s', $data['error'] ?? 'Unknown error') ); } // Store carrier info for later use update_post_meta(get_current_user_id(), '_phone_carrier', $data['carrier'] ?? ''); return true; }, 10, 4); ``` ### Filter: `woonoow/validate_phone_whatsapp` Convenience filter specifically for WhatsApp registration checks. **Parameters:** - `$is_registered` (bool|WP_Error): Initial state (default: true) - `$phone` (string): The phone number (cleaned) - `$context` (string): Context of validation - `$country_code` (string): Country code if available **Returns:** `true` if registered on WhatsApp, `WP_Error` if not --- ## Usage in Code ### Email Validation ```php use WooNooW\Core\Validation; // Validate email for newsletter $result = Validation::validate_email('user@example.com', 'newsletter_subscribe'); if (is_wp_error($result)) { // Handle error echo $result->get_error_message(); } else { // Email is valid // Proceed with subscription } ``` ### Phone Validation ```php use WooNooW\Core\Validation; // Validate phone for checkout $result = Validation::validate_phone('+628123456789', 'checkout', 'ID'); if (is_wp_error($result)) { // Handle error echo $result->get_error_message(); } else { // Phone is valid // Proceed with order } ``` ### Phone + WhatsApp Validation ```php use WooNooW\Core\Validation; // Validate phone and check WhatsApp registration $result = Validation::validate_phone_whatsapp('+628123456789', 'checkout', 'ID'); if (is_wp_error($result)) { // Phone invalid or not registered on WhatsApp echo $result->get_error_message(); } else { // Phone is valid and registered on WhatsApp // Proceed with order } ``` --- ## Validation Contexts Common contexts used throughout WooNooW: - `newsletter_subscribe` - Newsletter subscription form - `checkout` - Checkout process - `registration` - User registration - `shipping` - Shipping address validation - `billing` - Billing address validation - `general` - General validation (default) Addons can filter based on context to apply different validation rules for different scenarios. --- ## Best Practices 1. **Always fallback gracefully** - If external API fails, return `$is_valid` to use basic validation 2. **Use timeouts** - Set reasonable timeouts (5-10 seconds) for API calls 3. **Cache results** - Cache validation results to avoid repeated API calls 4. **Provide clear error messages** - Return descriptive WP_Error messages 5. **Check context** - Only apply validation where needed to avoid unnecessary API calls 6. **Handle API keys securely** - Store API keys in options, never hardcode 7. **Log errors** - Log API errors for debugging without blocking users --- ## Error Codes ### Email Validation Errors - `invalid_email` - Basic format validation failed - `invalid_email_format` - Regex pattern validation failed - `email_verification_failed` - External API verification failed - `email_validation_failed` - Generic validation failure ### Phone Validation Errors - `invalid_phone` - Basic format validation failed - `phone_not_whatsapp` - Phone not registered on WhatsApp - `phone_invalid` - External API validation failed - `phone_validation_failed` - Generic validation failure