## Filter: wpd_ai_is_valid_reporting_utm_key_value_pair

Filter whether a UTM key-value pair is valid for reporting purposes. This allows custom validation logic for UTM parameters.

### Description

Alpha Insights validates UTM parameters before using them in reports. This filter allows you to add custom validation logic to determine if a specific UTM key-value combination should be included in reporting data.

#### Location

File: `includes/functions/wpd-report-functions.php`

Function: `wpd_is_valid_reporting_utm_key_value_pair()`

Line: ~93

### Parameters

Parameter | Type | Description
--- | --- | ---
$valid | bool | Whether the key-value pair is valid (default: true if both key and value pass validation)
$key | string | The UTM key (e.g., 'utm_source', 'utm_campaign')
$value | string | The UTM value

#### Return

Type: bool

Description: True if valid, false to exclude from reporting

### Example Usage

### Exclude Internal Testing Campaigns

    add_filter( 'wpd_ai_is_valid_reporting_utm_key_value_pair', 'exclude_test_campaigns', 10, 3 );
    function exclude_test_campaigns( $valid, $key, $value ) {
        // Exclude test campaigns from reporting
        if ( $key === 'utm_campaign' && stripos( $value, 'test' ) !== false ) {
            return false;
        }
        return $valid;
    }

### Exclude Specific UTM Sources

    add_filter( 'wpd_ai_is_valid_reporting_utm_key_value_pair', 'exclude_specific_sources', 10, 3 );
    function exclude_specific_sources( $valid, $key, $value ) {
        // Exclude internal or development sources
        if ( $key === 'utm_source' ) {
            $excluded_sources = array( 'internal', 'dev', 'staging', 'localhost' );
            if ( in_array( strtolower( $value ), $excluded_sources ) ) {
                return false;
            }
        }
        return $valid;
    }

### Require Minimum Value Length

    add_filter( 'wpd_ai_is_valid_reporting_utm_key_value_pair', 'require_minimum_length', 10, 3 );
    function require_minimum_length( $valid, $key, $value ) {
        // Require campaign names to be at least 5 characters
        if ( $key === 'utm_campaign' && strlen( $value ) < 5 ) {
            return false;
        }
        return $valid;
    }

### Validate Against Allowed Values List

    add_filter( 'wpd_ai_is_valid_reporting_utm_key_value_pair', 'validate_against_whitelist', 10, 3 );
    function validate_against_whitelist( $valid, $key, $value ) {
        // Define allowed campaign values
        $allowed_campaigns = array( 'summer_sale', 'winter_sale', 'new_product_launch' );

        if ( $key === 'utm_campaign' && ! in_array( $value, $allowed_campaigns ) ) {
            return false;
        }
        return $valid;
    }

### Block Spam or Invalid Characters

    add_filter( 'wpd_ai_is_valid_reporting_utm_key_value_pair', 'block_spam_characters', 10, 3 );
    function block_spam_characters( $valid, $key, $value ) {
        // Block values with suspicious characters
        if ( preg_match( '/[<>"\']/', $value ) ) {
            return false;
        }
        return $valid;
    }

### Best Practices

- Return the original $valid value if your logic doesn't apply
- Use specific key checks rather than blanket validation
- Keep validation logic simple and fast
- Log excluded values for debugging if needed
- Consider performance impact on high-traffic sites

### Important Notes

- This filter runs for every UTM parameter check
- Returning false excludes the key-value pair from reporting
- Default validation (key and value validity) runs before this filter
- This is the final validation step before data is stored
- Invalid pairs are silently excluded (not logged by default)

### Related Filters

- wpd_ai_is_valid_reporting_utm_key - Validate UTM keys
- wpd_ai_is_valid_reporting_utm_value - Validate UTM values
- wpd_ai_valid_reporting_utm_keys - Filter valid UTM keys list

### Related Functions

- `wpd_is_valid_reporting_utm_key_value_pair()` - Check if key-value pair is valid
- `wpd_is_valid_reporting_utm_key()` - Check if UTM key is valid
- `wpd_is_valid_reporting_utm_value()` - Check if UTM value is valid

### Debugging

    add_filter( 'wpd_ai_is_valid_reporting_utm_key_value_pair', 'debug_utm_validation', 999, 3 );
    function debug_utm_validation( $valid, $key, $value ) {
        if ( ! $valid ) {
            error_log( sprintf(
                'Alpha Insights: Excluded UTM pair - Key: %s, Value: %s',
                $key,
                $value
            ) );
        }
        return $valid;
    }