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

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;
}