<?php
/**
 * WordPress Coding Standard.
 *
 * @package WPCS\WordPressCodingStandards
 * @link    https://github.com/WordPress/WordPress-Coding-Standards
 * @license https://opensource.org/licenses/MIT MIT
 */

namespace WordPressCS\WordPress\Helpers;

use PHP_CodeSniffer\Files\File;
use PHP_CodeSniffer\Util\Tokens;
use PHPCSUtils\Tokens\Collections;
use PHPCSUtils\Utils\Conditions;
use PHPCSUtils\Utils\Context;
use PHPCSUtils\Utils\PassedParameters;
use PHPCSUtils\Utils\TextStrings;
use WordPressCS\WordPress\Helpers\ContextHelper;
use WordPressCS\WordPress\Helpers\VariableHelper;

/**
 * Helper function for checking whether a token is validated.
 *
 * @since 3.0.0 The method in this class was previously contained in the
 *              `WordPressCS\WordPress\Sniff` class and has been moved here.
 */
final class ValidationHelper {

	/**
	 * The tokens the function looks for to determine whether a token is validated.
	 *
	 * @since 3.0.0
	 *
	 * @var array<int|string, string>
	 */
	private static $targets = array(
		\T_ISSET          => 'construct',
		\T_EMPTY          => 'construct',
		\T_STRING         => 'function_call',
		\T_COALESCE       => 'coalesce',
		\T_COALESCE_EQUAL => 'coalesce',
	);

	/**
	 * List of PHP native functions to check if an array index exists.
	 *
	 * @since 3.0.0
	 *
	 * @var array<string, bool>
	 */
	private static $key_exists_functions = array(
		'array_key_exists' => true,
		'key_exists'       => true, // Alias.
	);

	/**
	 * Check if the existence of a variable is validated with isset(), empty(), array_key_exists()
	 * or key_exists().
	 *
	 * When $in_condition_only is `false`, (which is the default), this is considered
	 * valid:
	 *
	 * ```php
	 * if ( isset( $var ) ) {
	 *     // Do stuff, like maybe return or exit (but could be anything)
	 * }
	 *
	 * foo( $var );
	 * ```
	 *
	 * When it is `true`, that would be invalid; the use of the variable must be within
	 * the scope of the validating condition, like this:
	 *
	 * ```php
	 * if ( isset( $var ) ) {
	 *     foo( $var );
	 * }
	 * ```
	 *
	 * @since 0.5.0
	 * @since 2.1.0 Now recognizes array_key_exists() and key_exists() as validation functions.
	 * @since 2.1.0 Stricter check on whether the correct variable and the correct
	 *              array keys are being validated.
	 * @since 3.0.0 - Moved from the Sniff class to this class.
	 *              - The method visibility was changed from `protected` to `public static`.
	 *              - The `$phpcsFile` parameter was added.
	 *
	 * @param \PHP_CodeSniffer\Files\File $phpcsFile         The file being scanned.
	 * @param int                         $stackPtr          The index of this token in the stack.
	 * @param array|string                $array_keys        An array key to check for ("bar" in $foo['bar'])
	 *                                                       or an array of keys for multi-level array access.
	 * @param bool                        $in_condition_only Whether to require that this use of the
	 *                                                       variable occurs within the scope of the
	 *                                                       validating condition, or just in the same
	 *                                                       scope (default).
	 *
	 * @return bool Whether the var is validated.
	 */
	public static function is_validated( File $phpcsFile, $stackPtr, $array_keys = array(), $in_condition_only = false ) {
		$tokens = $phpcsFile->getTokens();
		if ( isset( $tokens[ $stackPtr ] ) === false ) {
			return false;
		}

		if ( $in_condition_only ) {
			/*
			 * This is a stricter check, requiring the variable to be used only
			 * within the validation condition.
			 */
			$conditionPtr = Conditions::getLastCondition( $phpcsFile, $stackPtr );
			if ( false === $conditionPtr ) {
				// If there are no conditions, there's no validation.
				return false;
			}

			$condition = $tokens[ $conditionPtr ];
			if ( ! isset( $condition['parenthesis_opener'] ) ) {
				// Live coding or parse error.
				return false;
			}

			$scope_start = $condition['parenthesis_opener'];
			$scope_end   = $condition['parenthesis_closer'];

		} else {
			/*
			 * We are more loose, requiring only that the variable be validated
			 * in the same function/file scope as it is used.
			 */
			$scope_start = 0;

			/*
			 * Check if we are in a function.
			 *
			 * Note: PHP 7.4+ arrow functions are not taken into account as those are not
			 * included in the "conditions" array. Additionally, arrow functions have
			 * access to variables outside their direct scope.
			 */
			$function = Conditions::getLastCondition( $phpcsFile, $stackPtr, array( \T_FUNCTION, \T_CLOSURE ) );

			// If so, we check only within the function, otherwise the whole file.
			if ( false !== $function ) {
				$scope_start = $tokens[ $function ]['scope_opener'];
			}

			$scope_end = $stackPtr;
		}

		if ( ! empty( $array_keys ) && ! is_array( $array_keys ) ) {
			$array_keys = (array) $array_keys;
		}

		$bare_array_keys = self::strip_quotes_from_array_values( $array_keys );

		// phpcs:ignore Generic.CodeAnalysis.JumbledIncrementer.Found -- On purpose, see below.
		for ( $i = ( $scope_start + 1 ); $i < $scope_end; $i++ ) {

			if ( isset( Collections::closedScopes()[ $tokens[ $i ]['code'] ] )
				&& isset( $tokens[ $i ]['scope_closer'] )
			) {
				// Jump over nested closed scopes as validation done within those does not apply.
				$i = $tokens[ $i ]['scope_closer'];
				continue;
			}

			if ( \T_FN === $tokens[ $i ]['code']
				&& isset( $tokens[ $i ]['scope_closer'] )
				&& $tokens[ $i ]['scope_closer'] < $scope_end
			) {
				// Jump over nested arrow functions as long as the current variable isn't *in* the arrow function.
				$i = $tokens[ $i ]['scope_closer'];
				continue;
			}

			if ( isset( self::$targets[ $tokens[ $i ]['code'] ] ) === false ) {
				continue;
			}

			switch ( self::$targets[ $tokens[ $i ]['code'] ] ) {
				case 'construct':
					$issetOpener = $phpcsFile->findNext( Tokens::$emptyTokens, ( $i + 1 ), null, true );
					if ( false === $issetOpener
						|| \T_OPEN_PARENTHESIS !== $tokens[ $issetOpener ]['code']
						|| isset( $tokens[ $issetOpener ]['parenthesis_closer'] ) === false
					) {
						// Parse error or live coding.
						continue 2;
					}

					$issetCloser = $tokens[ $issetOpener ]['parenthesis_closer'];

					// Look for this variable. We purposely stomp $i from the parent loop.
					for ( $i = ( $issetOpener + 1 ); $i < $issetCloser; $i++ ) {

						if ( \T_VARIABLE !== $tokens[ $i ]['code'] ) {
							continue;
						}

						if ( $tokens[ $stackPtr ]['content'] !== $tokens[ $i ]['content'] ) {
							continue;
						}

						// If we're checking for specific array keys (ex: 'hello' in
						// $_POST['hello']), that must match too. Quote-style, however, doesn't matter.
						if ( ! empty( $bare_array_keys ) ) {
							$found_keys = VariableHelper::get_array_access_keys( $phpcsFile, $i );
							$found_keys = self::strip_quotes_from_array_values( $found_keys );
							$diff       = array_diff_assoc( $bare_array_keys, $found_keys );
							if ( ! empty( $diff ) ) {
								continue;
							}
						}

						return true;
					}

					break;

				case 'function_call':
					// Only check calls to array_key_exists() and key_exists().
					if ( isset( self::$key_exists_functions[ strtolower( $tokens[ $i ]['content'] ) ] ) === false ) {
						continue 2;
					}

					$next_non_empty = $phpcsFile->findNext( Tokens::$emptyTokens, ( $i + 1 ), null, true );
					if ( false === $next_non_empty || \T_OPEN_PARENTHESIS !== $tokens[ $next_non_empty ]['code'] ) {
						// Not a function call.
						continue 2;
					}

					if ( Context::inAttribute( $phpcsFile, $i ) === true ) {
						// Definitely not the function call as those are not allowed in attributes.
						continue 2;
					}

					if ( ContextHelper::has_object_operator_before( $phpcsFile, $i ) === true ) {
						// Method call.
						continue 2;
					}

					if ( ContextHelper::is_token_namespaced( $phpcsFile, $i ) === true ) {
						// Namespaced function call.
						continue 2;
					}

					$params = PassedParameters::getParameters( $phpcsFile, $i );

					// As `key_exists()` is an alias of `array_key_exists()`, the param positions and names are the same.
					$array_param = PassedParameters::getParameterFromStack( $params, 2, 'array' );
					if ( false === $array_param ) {
						continue 2;
					}

					$array_param_first_token = $phpcsFile->findNext( Tokens::$emptyTokens, $array_param['start'], ( $array_param['end'] + 1 ), true );
					if ( false === $array_param_first_token
						|| \T_VARIABLE !== $tokens[ $array_param_first_token ]['code']
						|| $tokens[ $array_param_first_token ]['content'] !== $tokens[ $stackPtr ]['content']
					) {
						continue 2;
					}

					if ( ! empty( $bare_array_keys ) ) {
						// Prevent the original array from being altered.
						$bare_keys = $bare_array_keys;
						$last_key  = array_pop( $bare_keys );

						/*
						 * For multi-level array access, the complete set of keys could be split between
						 * the $key and the $array parameter, but could also be completely in the $array
						 * parameter, so we need to check both options.
						 */
						$found_keys = VariableHelper::get_array_access_keys( $phpcsFile, $array_param_first_token );
						$found_keys = self::strip_quotes_from_array_values( $found_keys );

						// First try matching the complete set against the array parameter.
						$diff = array_diff_assoc( $bare_array_keys, $found_keys );
						if ( empty( $diff ) ) {
							return true;
						}

						// If that failed, try getting an exact match for the subset against the
						// $array parameter and the last key against the first.
						$key_param = PassedParameters::getParameterFromStack( $params, 1, 'key' );
						if ( false !== $key_param
							&& $bare_keys === $found_keys
							&& TextStrings::stripQuotes( $key_param['raw'] ) === $last_key
						) {
							return true;
						}

						// Didn't find the correct array keys.
						continue 2;
					}

					return true;

				case 'coalesce':
					$prev = $i;
					do {
						$prev = $phpcsFile->findPrevious( Tokens::$emptyTokens, ( $prev - 1 ), null, true );
						// Skip over array keys, like `$_GET['key']['subkey']`.
						if ( \T_CLOSE_SQUARE_BRACKET === $tokens[ $prev ]['code'] ) {
							$prev = $tokens[ $prev ]['bracket_opener'];
							continue;
						}

						break;
					} while ( $prev >= ( $scope_start + 1 ) );

					// We should now have reached the variable.
					if ( \T_VARIABLE !== $tokens[ $prev ]['code'] ) {
						continue 2;
					}

					if ( $tokens[ $prev ]['content'] !== $tokens[ $stackPtr ]['content'] ) {
						continue 2;
					}

					if ( ! empty( $bare_array_keys ) ) {
						$found_keys = VariableHelper::get_array_access_keys( $phpcsFile, $prev );
						$found_keys = self::strip_quotes_from_array_values( $found_keys );
						$diff       = array_diff_assoc( $bare_array_keys, $found_keys );
						if ( ! empty( $diff ) ) {
							continue 2;
						}
					}

					// Right variable, correct key.
					return true;
			}
		}

		return false;
	}

	/**
	 * Strip quotes of all the values in an array containing only text strings.
	 *
	 * @since 3.0.0
	 *
	 * @param string[] $text_strings The input array.
	 *
	 * @return string[]
	 */
	private static function strip_quotes_from_array_values( array $text_strings ) {
		return array_map( array( 'PHPCSUtils\Utils\TextStrings', 'stripQuotes' ), $text_strings );
	}
}