File: /home/icsla/public_html/wp-content/plugins/popup-maker/includes/namespaced/utils.php
<?php
/**
* Utility functions.
*
* @since 1.21.0
*
* @package PopupMaker
* @copyright Copyright (c) 2024, Code Atlantic LLC
*/
namespace PopupMaker;
defined( 'ABSPATH' ) || exit;
/**
* Change camelCase to snake_case.
*
* @param string $str String to convert.
*
* @return string Converted string.
*
* @since 1.21.0
*/
function camel_case_to_snake_case( $str ) {
return strtolower( preg_replace( '/(?<!^)[A-Z]/', '_$0', $str ) );
}
/**
* Change snake_case to camelCase.
*
* @param string $str String to convert.
*
* @return string Converted string.
*
* @since 1.21.0
*/
function snake_case_to_camel_case( $str ) {
return lcfirst( str_replace( '_', '', ucwords( $str, '_' ) ) );
}
/**
* Get array values using dot.notation.
*
* @param string $key Key to fetch.
* @param array<string,mixed> $data Array to fetch from.
* @param string|null $key_case Case to use for key (snake_case|camelCase).
*
* @return mixed|null
*
* @since 1.21.0
*/
function fetch_key_from_array( $key, $data, $key_case = null ) {
// If key is .notation, then we need to traverse the array.
$dotted_keys = explode( '.', $key );
foreach ( $dotted_keys as $key ) {
if ( $key_case ) {
switch ( $key_case ) {
case 'snake_case':
// Check if key is camelCase & convert to snake_case.
$key = camel_case_to_snake_case( $key );
break;
case 'camelCase':
// Check if key is snake_case & convert to camelCase.
$key = snake_case_to_camel_case( $key );
break;
}
}
if ( ! isset( $data[ $key ] ) ) {
return null;
}
$data = $data[ $key ];
}
return $data ? $data : null;
}
/**
* Generate a short unique ID.
* This generates a unique ID that is URL-safe by combining timestamp and random elements.
*
* @param string $prefix Optional prefix for the UUID.
* @param int $random_length Length of random suffix (default 4).
* @return string
*/
function generate_uuid( $prefix = '', $random_length = 4 ) {
// Get microtime as base36 - this gives us a 6-7 character time component
$time = base_convert( str_replace( '.', '', microtime( true ) ), 10, 36 );
// Add random suffix
$chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
$random = '';
for ( $i = 0; $i < $random_length; $i++ ) {
$random .= $chars[ random_int( 0, strlen( $chars ) - 1 ) ];
}
return $prefix . $time . $random;
}
/**
* Safely redirect to URL, allowing external domains when appropriate.
*
* This function provides a wrapper around wp_safe_redirect() that allows
* external redirects with proper security controls via filters.
*
* @param string $url URL to redirect to.
* @param int $status HTTP status code (default 302).
*
* @return void
*/
function safe_redirect( $url, $status = 302 ) {
/**
* Filter to determine if external redirects should be allowed.
*
* @param bool $allow_external Whether to allow external redirects.
* @param string $url The URL being redirected to.
*/
$allow_external = apply_filters( 'popup_maker/allow_external_redirect', true, $url );
if ( $allow_external ) {
// Parse the URL to check if it's external
$parsed_url = wp_parse_url( $url );
$site_url = wp_parse_url( home_url() );
// If it's an external URL, temporarily add the host to allowed hosts
if ( isset( $parsed_url['host'] ) &&
isset( $site_url['host'] ) &&
$parsed_url['host'] !== $site_url['host']
) {
add_filter(
'allowed_redirect_hosts',
function ( $hosts ) use ( $parsed_url ) {
if ( ! in_array( $parsed_url['host'], $hosts, true ) ) {
$hosts[] = $parsed_url['host'];
}
return $hosts;
},
20
);
}
}
wp_safe_redirect( sanitize_url( $url ), $status );
exit;
}
/**
* Render a progress bar.
*
* @param float|int $percentage The percentage to display.
* @param array{size:string,title:string,class:string} $args The arguments for the progress bar.
* @return void
*/
function progress_bar( $percentage, $args = [] ) {
$args = wp_parse_args(
$args,
[
'size' => null,
'title' => '',
'class' => '',
'show_percentage' => true,
]
);
$classes = [
'pum-progress-bar',
];
if ( $args['size'] ) {
$classes[] = 'pum-progress-bar--' . esc_attr( $args['size'] );
}
if ( $args['class'] ) {
$classes[] = esc_attr( $args['class'] );
}
echo '<div class="' . esc_attr( implode( ' ', $classes ) ) . '" title="' . esc_html( $args['title'] ) . '">';
echo '<div class="pum-progress-bar__inner">';
echo '<div class="pum-progress-fill" style="width: ' . esc_attr( min( $percentage, 100 ) ) . '%;"></div>';
echo '</div>';
if ( $args['show_percentage'] ) {
echo '<strong>' . esc_html( round( $percentage, 1 ) ) . '%</strong>';
}
echo '</div>';
}
/**
* Get a filterable query parameter name.
*
* Used for URL tracking parameters like 'pid' which can conflict
* with other plugins. Site admins can filter to change the param name.
*
* @since 1.22.0
*
* @param string $key Parameter key (e.g., 'popup_id').
*
* @return string The parameter name.
*/
function get_param_name( $key ) {
static $cache = [];
if ( ! isset( $cache[ $key ] ) ) {
$defaults = [ 'popup_id' => 'pid' ];
$cache[ $key ] = sanitize_key(
apply_filters(
"popup_maker/param_name/{$key}",
$defaults[ $key ] ?? $key
)
);
}
return $cache[ $key ];
}
/**
* Get all filterable query parameter names.
*
* @since 1.22.0
*
* @return array<string,string> Parameter names keyed by their identifier.
*/
function get_param_names() {
return [
'popup_id' => get_param_name( 'popup_id' ),
'cta' => get_param_name( 'cta' ),
'notrack' => get_param_name( 'notrack' ),
];
}
/**
* Get a query parameter value with type safety and filtering support.
*
* Uses the filterable parameter name system via get_param_name().
* Returns fallback if parameter is not set OR is an empty string.
* Note: Allows "0" as a valid value (unlike empty() check).
*
* @since 1.22.0
*
* @param string $key Parameter key (e.g., 'popup_id', 'cta').
* @param mixed $fallback Fallback value if parameter not set or empty.
* @param string $type Type to cast value to: 'string', 'int', 'bool', 'key', 'email', 'url', 'array'.
* Defaults to 'string'.
*
* @return mixed The sanitized parameter value, or fallback if not set/empty.
*/
function get_param_value( $key, $fallback = null, $type = 'string' ) {
$param_name = get_param_name( $key );
// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Parameter reading, not state-changing operation.
if ( ! isset( $_GET[ $param_name ] ) || '' === $_GET[ $param_name ] ) {
return $fallback;
}
// phpcs:ignore WordPress.Security.NonceVerification.Recommended, WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- Sanitization handled by sanitize_param_by_type().
$value = wp_unslash( $_GET[ $param_name ] );
return sanitize_param_by_type( $value, $type );
}
/**
* Get a POST parameter value with type safety.
*
* Separate function for POST to enforce deliberate intent.
* Note: POST parameters do not use the filterable name system.
*
* @since 1.22.0
*
* @param string $key Parameter key (e.g., 'action', 'nonce').
* @param mixed $fallback Fallback value if parameter not set or empty.
* @param string $type Type to cast value to: 'string', 'int', 'bool', 'key', 'email', 'url', 'array'.
* Defaults to 'string'.
*
* @return mixed The sanitized parameter value, or fallback if not set/empty.
*/
function get_post_param_value( $key, $fallback = null, $type = 'string' ) {
// phpcs:ignore WordPress.Security.NonceVerification.Missing -- Parameter reading, not state-changing operation.
if ( ! isset( $_POST[ $key ] ) || '' === $_POST[ $key ] ) {
return $fallback;
}
// phpcs:ignore WordPress.Security.NonceVerification.Missing, WordPress.Security.ValidatedSanitizedInput.InputNotSanitized -- Sanitization handled by sanitize_param_by_type().
$value = wp_unslash( $_POST[ $key ] );
return sanitize_param_by_type( $value, $type );
}
/**
* Sanitize a parameter value based on type specification.
*
* Reusable helper for type-safe sanitization of request data.
*
* @since 1.22.0
*
* @param mixed $value Raw parameter value.
* @param string $type Type to sanitize for: 'string', 'int', 'bool', 'key', 'email', 'url', 'array'.
*
* @return mixed Sanitized value.
*/
function sanitize_param_by_type( $value, $type ) {
// Handle array values passed when expecting scalar types.
if ( is_array( $value ) && 'array' !== $type ) {
if ( ! empty( $value ) ) {
$value = reset( $value );
} else {
return 'bool' === $type ? false : ( 'int' === $type ? 0 : '' );
}
}
switch ( $type ) {
case 'int':
return absint( $value );
case 'bool':
return filter_var( $value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE ) ?? false;
case 'key':
return sanitize_key( $value );
case 'email':
return sanitize_email( $value );
case 'url':
return esc_url_raw( $value );
case 'array':
if ( ! is_array( $value ) ) {
return [];
}
// Safely handle nested arrays by only sanitizing scalar values.
return array_map(
function ( $v ) {
return is_scalar( $v ) ? sanitize_text_field( (string) $v ) : '';
},
$value
);
case 'string':
default:
return sanitize_text_field( $value );
}
}