<?php
/**
 * Field-level sanitisers shared by Settings and REST schemas.
 *
 * Keeping the field-level rules in one place means the option write
 * path (`Settings::sanitize()`) and the REST schema callbacks
 * (`register_setting()` / `register_rest_route()`) never disagree.
 *
 * Every method takes a raw value and returns a clean value of the
 * expected type. None of them throw — failure modes return the
 * documented fallback so callers don't need try/catch blocks.
 *
 * @package AIOSEO\FourNotFour
 */

namespace AIOSEO\FourNotFour\Utils;

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Class Sanitizer
 *
 * @since   4.0.0
 * @package AIOSEO\FourNotFour\Utils
 */
class Sanitizer {

	/**
	 * Coerce any value to a boolean.
	 *
	 * Accepts `'true'`, `'1'`, `1`, `true` as truthy; everything else
	 * is treated as false.
	 *
	 * @since 4.0.0
	 *
	 * @param mixed $value Raw value.
	 *
	 * @return bool
	 */
	public static function boolean( $value ): bool {
		if ( is_string( $value ) ) {
			$value = strtolower( trim( $value ) );

			return in_array( $value, [ '1', 'true', 'yes', 'on' ], true );
		}

		return (bool) $value;
	}

	/**
	 * Coerce any value to a non-negative integer.
	 *
	 * @since 4.0.0
	 *
	 * @param mixed $value Raw value.
	 * @param int   $min   Minimum allowed value (default 0).
	 * @param int   $max   Maximum allowed value (default PHP_INT_MAX).
	 *
	 * @return int
	 */
	public static function integer( $value, int $min = 0, int $max = PHP_INT_MAX ): int {
		$int = (int) $value;

		if ( $int < $min ) {
			$int = $min;
		}

		if ( $int > $max ) {
			$int = $max;
		}

		return $int;
	}

	/**
	 * Sanitise a free-form string field.
	 *
	 * @since 4.0.0
	 *
	 * @param mixed $value Raw value.
	 *
	 * @return string
	 */
	public static function text( $value ): string {
		return sanitize_text_field( (string) $value );
	}

	/**
	 * Sanitise a URL field.
	 *
	 * Returns an empty string when the value is not a valid URL.
	 *
	 * @since 4.0.0
	 *
	 * @param mixed $value Raw value.
	 *
	 * @return string
	 */
	public static function url( $value ): string {
		$url = esc_url_raw( (string) $value );

		return is_string( $url ) ? $url : '';
	}

	/**
	 * Sanitise an email field.
	 *
	 * Returns an empty string when the value is not a valid email.
	 *
	 * @since 4.0.0
	 *
	 * @param mixed $value Raw value.
	 *
	 * @return string
	 */
	public static function email( $value ): string {
		$email = sanitize_email( (string) $value );

		return is_email( $email ) ? $email : '';
	}

	/**
	 * Sanitise a value against a fixed set of allowed values.
	 *
	 * @since 4.0.0
	 *
	 * @param mixed  $value    Raw value.
	 * @param array  $allowed  Whitelist of acceptable values.
	 * @param string $fallback Default returned when the value is not in the whitelist.
	 *
	 * @return string
	 */
	public static function enum( $value, array $allowed, string $fallback = '' ): string {
		$value = (string) $value;

		return in_array( $value, $allowed, true ) ? $value : $fallback;
	}

	/**
	 * Sanitise a list of email addresses (array, comma-separated, or
	 * newline-separated).
	 *
	 * Each candidate is run through {@see sanitize_email()} and then
	 * validated with {@see is_email()}; only valid addresses survive.
	 * Order is preserved, duplicates are dropped.
	 *
	 * @since 4.0.0
	 *
	 * @param mixed $value Raw value.
	 *
	 * @return string[]
	 */
	public static function emailList( $value ): array {
		$candidates = self::stringList( $value );
		$clean      = [];

		foreach ( $candidates as $candidate ) {
			$email = sanitize_email( $candidate );
			if ( '' === $email || ! is_email( $email ) ) {
				continue;
			}
			$clean[] = $email;
		}

		return array_values( array_unique( $clean ) );
	}

	/**
	 * Sanitise a list of strings (one per line / comma-separated / array).
	 *
	 * Accepts either an array or a string containing newline- or
	 * comma-separated values. Returns a clean, de-duplicated list of
	 * trimmed non-empty strings.
	 *
	 * @since 4.0.0
	 *
	 * @param mixed $value Raw value.
	 *
	 * @return string[]
	 */
	public static function stringList( $value ): array {
		if ( is_string( $value ) ) {
			$split = preg_split( '/[\r\n,]+/', $value );
			$value = false === $split ? [] : $split;
		}

		if ( ! is_array( $value ) ) {
			return [];
		}

		$clean = [];

		foreach ( $value as $item ) {
			$item = trim( sanitize_text_field( (string) $item ) );

			if ( '' !== $item ) {
				$clean[] = $item;
			}
		}

		return array_values( array_unique( $clean ) );
	}

	/**
	 * Neutralise a value that a spreadsheet would evaluate as a formula.
	 *
	 * Referrers and user agents land in exported CSVs verbatim and are set by the visitor, so an
	 * unauthenticated request can plant `=HYPERLINK(...)` in a file an admin later opens in Excel.
	 * Prefixing a single quote makes the cell text; numbers are left alone so a negative value isn't
	 * turned into a string.
	 *
	 * @since 4.0.4
	 *
	 * @param  mixed $value Raw cell value.
	 * @return mixed        The value, quoted when a spreadsheet would treat it as a formula.
	 */
	public static function csvCell( $value ) {
		if ( ! is_string( $value ) || '' === $value ) {
			return $value;
		}

		if ( is_numeric( $value ) ) {
			return $value;
		}

		return in_array( $value[0], [ '=', '+', '-', '@', "\t", "\r" ], true ) ? "'" . $value : $value;
	}

	/**
	 * Apply {@see self::csvCell()} across a whole row.
	 *
	 * @since 4.0.4
	 *
	 * @param  array $row Cell values.
	 * @return array      The row with formula-looking cells quoted.
	 */
	public static function csvRow( array $row ): array {
		return array_map( [ self::class, 'csvCell' ], $row );
	}
}