<?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\Sniffs\PHP;

use PHPCSUtils\Utils\PassedParameters;
use WordPressCS\WordPress\AbstractFunctionParameterSniff;

/**
 * Flag calling in_array(), array_search() and array_keys() without true as the third parameter.
 *
 * @since 0.9.0
 * @since 0.10.0 - This sniff not only checks for `in_array()`, but also `array_search()`
 *                 and `array_keys()`.
 *               - The sniff no longer needlessly extends the `ArrayAssignmentRestrictionsSniff`
 *                 class which it didn't use.
 * @since 0.11.0 Refactored to extend the new WordPressCS native `AbstractFunctionParameterSniff` class.
 * @since 0.13.0 Class name changed: this class is now namespaced.
 */
final class StrictInArraySniff extends AbstractFunctionParameterSniff {

	/**
	 * The group name for this group of functions.
	 *
	 * @since 0.11.0
	 *
	 * @var string
	 */
	protected $group_name = 'strict';

	/**
	 * List of array functions to which a $strict parameter can be passed.
	 *
	 * The array_keys() function only requires the $strict parameter when the optional
	 * second parameter $filter_value has been set.
	 *
	 * @link https://www.php.net/in-array
	 * @link https://www.php.net/array-search
	 * @link https://www.php.net/array-keys
	 *
	 * @since 0.10.0
	 * @since 0.11.0 Renamed from $array_functions to $target_functions.
	 * @since 3.0.0  The format of the array value has changed from boolean to array.
	 *
	 * @var array<string, array{param_position: int, param_name: string, always_needed: bool}> Key is the function name.
	 */
	protected $target_functions = array(
		'in_array'     => array(
			'param_position' => 3,
			'param_name'     => 'strict',
			'always_needed'  => true,
		),
		'array_search' => array(
			'param_position' => 3,
			'param_name'     => 'strict',
			'always_needed'  => true,
		),
		'array_keys'   => array(
			'param_position' => 3,
			'param_name'     => 'strict',
			'always_needed'  => false,
		),
	);

	/**
	 * Process the parameters of a matched function.
	 *
	 * @since 0.11.0
	 *
	 * @param int    $stackPtr        The position of the current token in the stack.
	 * @param string $group_name      The name of the group which was matched.
	 * @param string $matched_content The token content (function name) which was matched
	 *                                in lowercase.
	 * @param array  $parameters      Array with information about the parameters.
	 *
	 * @return void
	 */
	public function process_parameters( $stackPtr, $group_name, $matched_content, $parameters ) {
		$param_info = $this->target_functions[ $matched_content ];

		/*
		 * Check if the strict check is actually needed.
		 *
		 * Important! This check only applies to array_keys() in the current form of the sniff
		 * and has been written to be specific to that function.
		 * If more functions would be added with 'always_needed' set to `false`,
		 * this code will need to be adjusted to handle those.
		 */
		if ( false === $param_info['always_needed'] ) {
			$has_filter_value = PassedParameters::getParameterFromStack( $parameters, 2, 'filter_value' );
			if ( false === $has_filter_value ) {
				return;
			}
		}

		$found_parameter = PassedParameters::getParameterFromStack( $parameters, $param_info['param_position'], $param_info['param_name'] );
		if ( false === $found_parameter || 'true' !== strtolower( $found_parameter['clean'] ) ) {
			$errorcode = 'MissingTrueStrict';

			/*
			 * Use a different error code when `false` is found to allow for excluding
			 * the warning as this will be a conscious choice made by the dev.
			 */
			if ( is_array( $found_parameter ) && 'false' === strtolower( $found_parameter['clean'] ) ) {
				$errorcode = 'FoundNonStrictFalse';
			}

			$this->phpcsFile->addWarning(
				'Not using strict comparison for %s; supply true for $%s argument.',
				( isset( $found_parameter['start'] ) ? $found_parameter['start'] : $stackPtr ),
				$errorcode,
				array( $matched_content, $param_info['param_name'] )
			);
		}
	}
}