## Filter: wpd_ai_is_valid_reporting_utm_value

Filter whether a UTM value is valid for reporting purposes. This allows custom validation logic for UTM parameter values.

### Description

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

#### Location

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

Function: `wpd_is_valid_reporting_utm_value()`

Line: ~129

### Parameters

Parameter | Type | Description
--- | --- | ---
$valid | bool | Whether the value is valid (default: true if value passes basic validation)
$value | string | The UTM value to validate

#### Return

Type: bool

Description: True if valid, false to exclude from reporting

### Default Validation

Before this filter runs, Alpha Insights checks:

- Value is a string
- Value is not empty
- Value length is between 2 and 255 characters

### Example Usage

### Exclude Test Values

    add_filter( 'wpd_ai_is_valid_reporting_utm_value', 'exclude_test_values', 10, 2 );
    function exclude_test_values( $valid, $value ) {
        // Exclude values containing 'test' or 'debug'
        if ( stripos( $value, 'test' ) !== false || stripos( $value, 'debug' ) !== false ) {
            return false;
        }
        return $valid;
    }

### Require Alphanumeric Only

    add_filter( 'wpd_ai_is_valid_reporting_utm_value', 'require_alphanumeric', 10, 2 );
    function require_alphanumeric( $valid, $value ) {
        // Only allow alphanumeric characters, hyphens, and underscores
        if ( ! preg_match( '/^[a-zA-Z0-9_-]+$/', $value ) ) {
            return false;
        }
        return $valid;
    }

### Block Suspicious Characters

    add_filter( 'wpd_ai_is_valid_reporting_utm_value', 'block_suspicious_chars', 10, 2 );
    function block_suspicious_chars( $valid, $value ) {
        // Block HTML/script injection attempts
        if ( preg_match( '/[<>"\']/', $value ) ) {
            return false;
        }
        // Block SQL injection patterns
        if ( stripos( $value, 'union' ) !== false || stripos( $value, 'select' ) !== false ) {
            return false;
        }
        return $valid;
    }

### Validate Against Whitelist

    add_filter( 'wpd_ai_is_valid_reporting_utm_value', 'validate_whitelist', 10, 2 );
    function validate_whitelist( $valid, $value ) {
        // Define allowed values (e.g., for utm_source)
        $allowed_sources = array( 'google', 'facebook', 'email', 'direct', 'organic' );

        // Only validate if we're checking a source value
        // Note: This filter doesn't know the key, so use with caution
        if ( ! in_array( strtolower( $value ), $allowed_sources ) ) {
            // For this example, we'll be lenient and only block obvious invalid values
            // In practice, you'd want to use wpd_ai_is_valid_reporting_utm_key_value_pair instead
            return $valid;
        }
        return $valid;
    }

### Enforce Minimum Length

    add_filter( 'wpd_ai_is_valid_reporting_utm_value', 'enforce_minimum_length', 10, 2 );
    function enforce_minimum_length( $valid, $value ) {
        // Require values to be at least 3 characters (default is 2)
        if ( strlen( $value ) < 3 ) {
            return false;
        }
        return $valid;
    }

### Best Practices

- Return the original $valid value if your logic doesn't apply
- Keep validation logic simple and performant
- Use specific patterns rather than complex regex
- Consider using wpd_ai_is_valid_reporting_utm_key_value_pair for key-specific validation
- Log excluded values for debugging if needed

### Important Notes

- This filter runs for every UTM value check
- Returning false excludes the value from reporting
- Default validation (length, type) runs before this filter
- This filter doesn't know which UTM key the value belongs to
- For key-specific validation, use wpd_ai_is_valid_reporting_utm_key_value_pair instead
- Invalid values 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_key_value_pair - Validate key-value pairs (recommended for key-specific validation)
- wpd_ai_valid_reporting_utm_keys - Filter valid UTM keys list

### Related Functions

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

### Debugging

    add_filter( 'wpd_ai_is_valid_reporting_utm_value', 'debug_utm_value_validation', 999, 2 );
    function debug_utm_value_validation( $valid, $value ) {
        if ( ! $valid ) {
            error_log( sprintf(
                'Alpha Insights: Excluded UTM value: %s',
                $value
            ) );
        }
        return $valid;
    }