<?php

namespace AdPresso\Infrastructure;

use AdPresso\RuntimeDebugger;

/**
 * Provides a secure, type-safe, and fluent interface for accessing superglobals.
 *
 * This class follows the "Secure by Default" principle, requiring developers
 * to choose the expected data type for every input.
 *
 *
 * @method static ParamsHandler get() Provides access to $_GET data.
 * @method static ParamsHandler post() Provides access to $_POST data.
 * @method static ParamsHandler cookie() Provides access to $_COOKIE data.
 * @method static ServerHandler server() Provides access to $_SERVER data.
 * @method static FilesHandler files() Provides access to $_FILES data.
 */
final class Params {

	/**
	 * Magic method to handle static calls like Params::get(), Params::post(), etc.
	 *
	 * @param string $name      The name of the superglobal to access ('get', 'post', 'cookie', 'server').
	 * @param array  $arguments Not used.
	 *
	 * @return ParamsHandler|ServerHandler
	 */
	public static function __callStatic( string $name, array $arguments ) {
		switch ( strtolower( $name ) ) {
			case 'post':
				return new ParamsHandler( $_POST );
			case 'get':
				return new ParamsHandler( $_GET );
			case 'cookie':
				return new ParamsHandler( $_COOKIE );
			case 'server':
				return new ServerHandler( $_SERVER );
			case 'files':
				return new FilesHandler( $_FILES );
			default:
				RuntimeDebugger::add_doing_it_wrong_entry(
					sprintf( 'Unsupported superglobal requested in Params class: %s', esc_html( $name ) )
				);
				return new ParamsHandler( [] );
		}
	}
}

/**
 * Handles the sanitization and retrieval of data from a specific superglobal array.
 */
class ParamsHandler {

	/**
	 * The superglobal array to process (e.g., $_POST).
	 * @var array
	 */
	protected array $source;

	/**
	 * Constructor.
	 *
	 * @param array $source The superglobal array.
	 */
	public function __construct( array $source ) {
		$this->source = $source;
	}

	/**
	 * Overrides a single value in the underlying source array.
	 * Used when one metabox needs to hand a merged/derived value to a
	 * later-running box that reads the same key from this same instance
	 * (e.g. a box that injects a synthesized condition into 'conditions_tree'
	 * before Conditions_Box::save() re-reads it in the same save request).
	 *
	 * @param string $key
	 * @param mixed  $value
	 *
	 * @return void
	 */
	public function override( string $key, mixed $value ): void {
		$this->source[ $key ] = $value;
	}

	/**
	 * Retrieves a value without any sanitization.
	 * Needs to be sanitized manually.
	 *
	 * @param string $key
	 * @param string $default
	 *
	 * @return string
	 */
	public function getUnsanitized( string $key, mixed $default = '' ): mixed {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		return wp_unslash( $this->source[ $key ] );
	}

	/**
	 * Retrieves a value as a sanitized plain text string.
	 * This is the safe default for any text input.
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param string $default The default value to return if the key doesn't exist.
	 *
	 * @return string The sanitized string.
	 */
	public function getString( string $key, string $default = '' ): string {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		return ! is_scalar( $value ) ? $default : sanitize_text_field( (string) $value );
	}

	/**
	 * Retrieves a value as a sanitized HTML class.
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param string $default The default value to return if the key doesn't exist.
	 *
	 * @return string The sanitized string.
	 */
	public function getHtmlClass( string $key, string $default = '' ): string {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		return ! is_scalar( $value ) ? $default : sanitize_html_class( (string) $value );
	}

	/**
	 * Retrieves a space-separated list of CSS classes, each sanitized on its own.
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param string $default The default value to return if the key doesn't exist.
	 *
	 * @return string
	 */
	public function getHtmlClasses( string $key, string $default = '' ): string {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		return ! is_scalar( $value ) ? $default : Util::sanitize_html_classes( (string) $value );
	}

	/**
	 * Retrieves a value and sanitizes it with the same rules as post content.
	 * Wrapper for wp_kses_post().
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param string $default The default value.
	 *
	 * @return string The sanitized string.
	 */
	public function getKsesPost( string $key, string $default = '' ): string {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		if ( ! is_scalar( $value ) ) {
			return $default;
		}

		return wp_kses_post( (string) $value );
	}

	/**
	 * Retrieves custom code (like <script>, <iframe>, <style>).
	 * * Security: Requires the 'unfiltered_html' capability. If the current user
	 * lacks this permission, the input is strictly sanitized using wp_kses_post()
	 * to prevent XSS and privilege escalation.
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param string $default The default value.
	 *
	 * @return string The raw code (for trusted users) or sanitized HTML (for others).
	 */
	public function getCustomCode( string $key, string $default = '' ): string {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		if ( ! is_scalar( $value ) ) {
			return $default;
		}

		return Util::sanitize_custom_code( (string) $value );
	}

	/**
	 * Retrieves a comma-separated string, sanitizes each item, and returns a clean comma-separated string.
	 * Useful for fields like tracking IDs (e.g., "G-12345, G-67890").
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param string $default The default value.
	 *
	 * @return string The sanitized comma-separated string.
	 */
	public function getCommaSeparatedString( string $key, string $default = '' ): string {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		if ( ! is_scalar( $value ) ) {
			return $default;
		}

		$items = explode( ',', (string) $value );
		$clean_items = [];

		foreach ( $items as $item ) {
			$clean_item = sanitize_text_field( trim( $item ) );

			if ( ! empty( $clean_item ) ) {
				$clean_items[] = $clean_item;
			}
		}

		return ! empty( $clean_items ) ? implode( ', ', $clean_items ) : $default;
	}

	/**
	 * Retrieves a value and sanitizes it as a safe inline CSS string.
	 * Wrapper for safecss_filter_attr().
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param string $default The default value.
	 *
	 * @return string The sanitized CSS string.
	 */
	public function getSafeCss( string $key, string $default = '' ): string {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		if ( ! is_scalar( $value ) ) {
			return $default;
		}

		return safecss_filter_attr( (string) $value );
	}

	/**
	 * Retrieves a value and sanitizes it as a CSS hex color.
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param string $default The default value.
	 *
	 * @return string The sanitized hex color string (e.g., '#aabbcc').
	 */
	public function getHexColor( string $key, string $default = '' ): string {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		if ( ! is_scalar( $value ) ) {
			return $default;
		}

		return sanitize_hex_color( (string) $value );
	}

	/**
	 * Retrieves a value as an integer.
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param int    $default The default value.
	 *
	 * @return int The sanitized integer.
	 */
	public function getInt( string $key, int $default = 0 ): int {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		return ! is_scalar( $value ) ? $default : (int) $value;
	}

	/**
	 * Retrieves a value as a positive integer.
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param int    $default The default value.
	 *
	 * @return int The sanitized positive integer.
	 */
	public function getId( string $key, int $default = 0 ): int {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		return ! is_scalar( $value ) ? $default : absint( $value );
	}

	/**
	 * Retrieves a value as a float.
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param float  $default The default value.
	 *
	 * @return float The sanitized float value.
	 */
	public function getFloat( string $key, float $default = 0.0 ): float {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		// Normalize comma to dot for float conversion.
		$value_normalized = str_replace( ',', '.', (string) $value );

		return ! is_scalar( $value ) ? $default : (float) $value_normalized;
	}

	/**
	 * Retrieves a value as a float.
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param string $default The default value.
	 *
	 * @return string The sanitized email value.
	 */
	public function getEmail( string $key, string $default = '' ): string {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		return ! is_scalar( $value ) ? $default : sanitize_email( (string) $value );
	}

	/**
	 * Retrieves a value as a key.
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param string $default The default value.
	 *
	 * @return string The sanitized key.
	 */
	public function getKey( string $key, string $default = '' ): string {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		return ! is_scalar( $value ) ? $default : sanitize_key( (string) $value );
	}

	/**
	 * Retrieves a JSON string, decodes it, and sanitizes the values of the resulting array.
	 *
	 * @param string $key     The key of the JSON string to retrieve.
	 * @param array  $default The default array to return if the key doesn't exist or JSON is invalid.
	 *
	 * @return array The decoded and sanitized data as an associative array.
	 */
	public function getJson( string $key, array $default = [] ): array {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		if ( ! is_scalar( $value ) ) {
			return $default;
		}

		$decoded_data = json_decode( (string) $value, true );

		// Check if JSON decoding was successful
		if ( json_last_error() !== JSON_ERROR_NONE ) {
			return $default;
		}

		// Sanitize every value in the decoded array recursively
		array_walk_recursive( $decoded_data, function( &$item ) {
			if ( is_string( $item ) ) {
				$item = sanitize_text_field( $item );
			}
		} );

		return $decoded_data;
	}

	/**
	 * Retrieves a JSON string and decodes it into a PHP array WITHOUT sanitizing the values.
	 * This is useful when custom, complex sanitization logic needs to be applied afterward.
	 *
	 * @param string $key     The key of the JSON string to retrieve.
	 * @param array  $default The default array if the key doesn't exist or JSON is invalid.
	 *
	 * @return array The decoded data as an associative array.
	 */
	public function getDecodedJson( string $key, array $default = [] ): array {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		if ( ! is_scalar( $value ) || trim( (string) $value ) === '' ) {
			return $default;
		}

		$decoded_data = json_decode( (string) $value, true );

		// Return the default value if JSON decoding failed.
		if ( json_last_error() !== JSON_ERROR_NONE ) {
			return $default;
		}

		return is_array( $decoded_data ) ? $decoded_data : $default;
	}

	/**
	 * Retrieves a value as a boolean.
	 * Normalizes 'true', '1', 'on', 'yes' to true.
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param bool   $default The default value.
	 *
	 * @return bool
	 */
	public function getBool( string $key, bool $default = false ): bool {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = $this->source[ $key ];

		if ( is_bool( $value ) ) {
			return $value;
		}
		if ( is_int( $value ) ) {
			return $value === 1;
		}

		$value_str = strtolower( (string) $value );
		if ( in_array( $value_str, [ 'true', '1', 'on', 'yes' ], true ) ) {
			return true;
		}
		if ( in_array( $value_str, [ 'false', '0', 'off', 'no', '' ], true ) ) {
			return false;
		}

		return $default;
	}

	/**
	 * Retrieves a value as a sanitized URL.
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param string $default The default value.
	 *
	 * @return string The sanitized URL.
	 */
	public function getUrl( string $key, string $default = '' ): string {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		return esc_url_raw( $value );
	}

	/**
	 * Retrieves a value containing HTML and sanitizes it using wp_kses.
	 *
	 * @param string     $key          The key of the value to retrieve.
	 * @param array|null $allowed_html Optional. An array defining allowed HTML tags.
	 *                                 If null, defaults to the same rules as for post content.
	 * @param string     $default      The default value.
	 *
	 * @return string The sanitized HTML string.
	 */
	public function getHtml( string $key, ?array $allowed_html = null, string $default = '' ): string {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		$value = wp_unslash( $this->source[ $key ] );

		if ( ! is_scalar( $value ) ) {
			return $default;
		}

		$allowed_html = $allowed_html ?? wp_kses_allowed_html( 'post' );

		return wp_kses( (string) $value, $allowed_html );
	}

	/**
	 * Retrieves an array and sanitizes its values recursively.
	 *
	 * @param string          $key       The key of the array to retrieve.
	 * @param callable|string $sanitizer The sanitization function to apply to each value.
	 * @param array           $default   The default array.
	 *
	 * @return array The sanitized array.
	 */
	public function getArray( string $key, callable|string $sanitizer = 'sanitize_text_field', array $default = [] ): array {
		if ( ! isset( $this->source[ $key ] ) || ! is_array( $this->source[ $key ] ) ) {
			return $default;
		}

		$array = wp_unslash( $this->source[ $key ] );

		return map_deep( $array, $sanitizer );
	}
}

/**
 * A specialized, hardened handler for $_SERVER variables.
 */
class ServerHandler extends ParamsHandler {

	/**
	 * An allowlist of $_SERVER keys that are generally considered safe
	 * as they are provided by the server environment, not the user.
	 *
	 * @var string[]
	 */
	private array $allowlist = [
		'DOCUMENT_ROOT',
		'PHP_SELF',
		'SCRIPT_FILENAME',
		'SCRIPT_NAME',
		'SERVER_ADDR',
		'SERVER_ADMIN',
		'SERVER_NAME',
		'SERVER_PORT',
		'SERVER_PROTOCOL',
		'SERVER_SOFTWARE',
		'REQUEST_TIME',
		'REQUEST_TIME_FLOAT',
	];

	/**
	 * Retrieves a value from the $_SERVER superglobal with strict validation.
	 *
	 * @param string $key     The key of the value to retrieve.
	 * @param string $default The default value.
	 *
	 * @return string The retrieved and sanitized/validated value.
	 */
	public function get( string $key, string $default = '' ): string {
		if ( ! isset( $this->source[ $key ] ) ) {
			return $default;
		}

		// Keys from the allowlist are considered safe and can be returned directly.
		if ( in_array( $key, $this->allowlist, true ) ) {
			return (string) $this->source[ $key ];
		}

		// All other keys are potentially user-manipulated and MUST be sanitized.
		// Defaulting to sanitize_text_field for safety.
		return sanitize_text_field( (string) $this->source[ $key ] );
	}
}

/**
 * A specialized handler for the $_FILES superglobal.
 * Extends ParamsHandler to inherit the 'source' property but introduces own specific methods for files.
 */
class FilesHandler extends ParamsHandler {

	/**
	 * Gets a single, uploaded file safely.
	 *
	 * @param string $key The form key of the file.
	 *
	 * @return ?array An array with the sanitized file information or null, if there is no valid upload.
	 * [ 'name' => 'sicherer-name.jpg', 'type' => 'image/jpeg', 'tmp_name' => '...', 'size' => 12345 ]
	 */
	public function getFile( string $key ): ?array {
		// Checks if the key exists and that it isn't an array upload.
		if ( ! isset( $this->source[ $key ] ) || is_array( $this->source[ $key ]['error'] ) ) {
			return null;
		}

		$file = $this->source[ $key ];

		// Check for errors.
		if ( $file['error'] !== UPLOAD_ERR_OK ) {
			return null;
		}

		// Check that the file is really an HTTP-Upload.
		if ( ! is_uploaded_file( $file['tmp_name'] ) ) {
			return null;
		}

		return [
			'name'     => sanitize_file_name( $file['name'] ),
			'type'     => sanitize_mime_type( $file['type'] ),
			'tmp_name' => $file['tmp_name'],
			'error'    => 0,
			'size'     => absint( $file['size'] ),
		];
	}

	/**
	 * Fethces multiple files (array upload, e.g. <input name="gallery[]" multiple>).
	 * Normalises the $_FILES structure in a clean array with file-arrays.
	 *
	 * @param string $key The form key.
	 *
	 * @return array An Array, that contains a sanitized file-array for every valid upload.
	 * Returns an empty array when nothing was uploaded.
	 */
	public function getFiles( string $key ): array {
		// Checks if the key exists and that it is an array upload.
		if ( ! isset( $this->source[ $key ] ) || ! is_array( $this->source[ $key ]['error'] ) ) {
			return [];
		}

		$normalized_files = [];
		$files            = $this->source[ $key ];

		foreach ( $files['error'] as $index => $error ) {
			// Prüft für jede Datei individuell auf Upload-Fehler
			if ( $error !== UPLOAD_ERR_OK ) {
				continue;
			}

			$tmp_name = $files['tmp_name'][ $index ];

			if ( ! is_uploaded_file( $tmp_name ) ) {
				continue;
			}

			$normalized_files[] = [
				'name'     => sanitize_file_name( $files['name'][ $index ] ),
				'type'     => sanitize_mime_type( $files['type'][ $index ] ),
				'tmp_name' => $tmp_name,
				'error'    => 0,
				'size'     => absint( $files['size'][ $index ] ),
			];
		}

		return $normalized_files;
	}
}

/**
 * Helper class for sanitizing special fields like type fields with own sanitizers.
 */
class ParamsHelper {

	/**
	 * Sanitize a single type field.
	 *
	 * @param array         $field
	 * @param ParamsHandler $handler
	 *
	 * @return mixed
	 */
	public static function sanitize_type_field( array $field, ParamsHandler $handler ): mixed {
		if ( empty( $field ) ) {
			return null;
		}

		$id            = $field['id'] ?? null;
		$sanitize_type = $field['sanitize_type'] ?? 'string';

		if ( ! $id ) {
			return null;
		}

		if ( str_starts_with( $sanitize_type, 'array:' ) ) {
			$array_subtype   = explode( ':', $sanitize_type )[1];
			$sanitizer       = match ( $array_subtype ) {
				'id', 'uint' => 'absint',
				'int' => 'intval',
				'key' => 'sanitize_key',
				'email' => 'sanitize_email',
				default => ( function() use ( $array_subtype ) {
					RuntimeDebugger::add_doing_it_wrong_entry( sprintf(
						'Unknown array_subtype "%s" in %s',
						$array_subtype,
						__METHOD__
					) );
					return 'sanitize_text_field';
				} )(),
			};
			if ( ( $field['type'] ?? '' ) === 'checkbox_button_group' ) {
				// The edit modal may post a flags object, the classic form posts a key list; always store the key list.
				$keys            = Util::get_checked_keys( $handler->getArray( $id, static fn( $value ) => $value ) );
				$sanitized_value = array_values( array_filter( array_map( $sanitizer, $keys ), static fn( $key ) => '' !== $key ) );
			} else {
				$sanitized_value = $handler->getArray( $id, $sanitizer );
			}
		} else {
			$sanitized_value = match ( $sanitize_type ) {
				// For UI-only compound/virtual fields whose actual sub-values are saved separately
				'none' => null,
				// Plain text; a textarea field keeps its line breaks.
				'string', 'text' => ( $field['type'] ?? '' ) === 'textarea' ? self::get_textarea( $handler, $id ) : $handler->getString( $id ),
				'textarea' => self::get_textarea( $handler, $id ),
				'id', 'uint' => $handler->getId( $id ),
				'int' => $handler->getInt( $id ),
				'bool' => $handler->getBool( $id ),
				'float' => $handler->getFloat( $id ),
				'email' => $handler->getEmail( $id ),
				'key' => $handler->getKey( $id ),
				'url' => $handler->getUrl( $id ),
				'html_class' => $handler->getHtmlClass( $id ),
				'html_classes' => $handler->getHtmlClasses( $id ),
				'kses_post' => $handler->getKsesPost( $id ),
				'custom_code' => $handler->getCustomCode( $id ),
				'comma_list'  => $handler->getCommaSeparatedString( $id ),
				'safe_css' => $handler->getSafeCss( $id ),
				'hex_color' => $handler->getHexColor( $id ),
				default =>
				( function() use ( $handler, $sanitize_type, $id ) {
					RuntimeDebugger::add_doing_it_wrong_entry( sprintf(
						'Unknown sanitize_type "%s" in %s',
						$sanitize_type,
						__METHOD__
					) );
					return $handler->getString( $id );
				} )(),
			};
		}

		return $sanitized_value;
	}

	/**
	 * Multi-line plain text (sanitize_textarea_field keeps line breaks).
	 *
	 * @param ParamsHandler $handler Request params.
	 * @param string        $id      Field ID.
	 *
	 * @return string
	 */
	private static function get_textarea( ParamsHandler $handler, string $id ): string {
		$value = $handler->getUnsanitized( $id, '' );

		return is_scalar( $value ) ? sanitize_textarea_field( (string) $value ) : '';
	}
}