<?php
/**
 * Sanitization utility functions for Envira Gallery.
 *
 * @since 1.13.2
 *
 * @package Envira_Gallery
 * @author  Envira Gallery Team <[email protected]>
 */

namespace Envira\Utils;

/**
 * Sanitize_Utils class for common sanitization operations.
 *
 * @since 1.13.2
 */
class Sanitize_Utils {

	/**
	 * Sanitizes a value against an allowlist of valid values.
	 *
	 * This is a generic sanitization helper that validates input against a list of allowed values.
	 * It's designed to prevent XSS attacks by ensuring only known-safe values are returned.
	 *
	 * Security Note: When the allowlist is generated via apply_filters, third-party code extending
	 * those filters must ensure added values are properly sanitized to maintain security.
	 *
	 * @since 1.13.2
	 *
	 * @param mixed    $value              The value to sanitize (will be converted to string).
	 * @param array    $valid_values       Array of valid values to check against.
	 * @param string   $default_value      Default value to return if validation fails.
	 * @param callable $sanitize_callback  Optional. Callback function to sanitize the value before validation.
	 *                                     Defaults to sanitize_text_field.
	 * @return string Sanitized value from the allowlist, or default if invalid.
	 */
	public static function sanitize_against_allowlist( $value, $valid_values, $default_value, $sanitize_callback = null ) {
		// Type validation: ensure value can be converted to string
		// Arrays, objects, resources cannot be safely converted and should fail validation
		if ( is_array( $value ) || is_object( $value ) || is_resource( $value ) ) {
			return $default_value;
		}

		// Handle null values
		if ( null === $value ) {
			return $default_value;
		}

		// Convert to string (handles int, float, bool safely)
		$value = (string) $value;

		// Ensure the sanitize callback is callable; fall back to sanitize_text_field if not.
		if ( ! is_callable( $sanitize_callback ) ) {
			$sanitize_callback = 'sanitize_text_field';
		}

		// Sanitize the input - remove any HTML tags and trim whitespace
		$sanitized_value = call_user_func( $sanitize_callback, trim( $value ) );

		// Check if value is in the list of valid values (strict comparison for security)
		if ( in_array( $sanitized_value, $valid_values, true ) ) {
			return $sanitized_value;
		}

		// Return default value if validation fails
		return $default_value;
	}

	/**
	 * Extracts 'value' field from an array of arrays using wp_list_pluck.
	 *
	 * @since 1.13.2
	 *
	 * @param array $items Array of arrays containing 'value' keys.
	 * @return array Array of extracted values.
	 */
	public static function extract_values( $items ) {
		return wp_list_pluck( $items, 'value' );
	}
}