WooNooW/VALIDATION_HOOKS.md

# 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