<?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 PHPCSUtils\Utils\PassedParameters;

/**
 * Helper functions and function lists for checking whether a function applies a callback to an array.
 *
 * @since 3.0.0 The property in this class was previously contained in the
 *              `WordPressCS\WordPress\Sniff` class and has been moved here.
 */
final class ArrayWalkingFunctionsHelper {

    /**
     * List of array functions which apply a callback to the array.
     *
     * These are often used for sanitization/escaping an array variable.
     *
     * Note: functions which alter the array by reference are not listed here on purpose.
     * These cannot easily be used for sanitization as they can't be combined with unslashing.
     * Similarly, they cannot be used for late escaping as the return value is a boolean, not
     * the altered array.
     *
     * @since 2.1.0
     * @since 3.0.0 - Moved from the Sniff class to this class.
     *              - Visibility changed from protected to private and property made static.
     *                Use the `get_functions()` method for access.
     *              - The value has changed from an integer to an array containing the integer
     *                parameter position + its name.
     *
     * @var array<string, array>
     */
    private static $arrayWalkingFunctions = array(
        'array_map' => array(
            'position' => 1,
            'name'     => 'callback',
        ),
        'map_deep'  => array(
            'position' => 2,
            'name'     => 'callback',
        ),
    );

    /**
     * Retrieve a list of the supported "array walking" functions.
     *
     * @since 3.0.0
     *
     * @return array<string, bool>
     */
    public static function get_functions() {
        return \array_fill_keys( \array_keys( self::$arrayWalkingFunctions ), true );
    }

    /**
     * Check if a particular function is an "array walking" function.
     *
     * @since 3.0.0
     *
     * @param string $functionName The name of the function to check.
     *
     * @return bool
     */
    public static function is_array_walking_function( $functionName ) {
        return isset( self::$arrayWalkingFunctions[ strtolower( $functionName ) ] );
    }

    /**
     * Retrieve the parameter information for the callback parameter for an array walking function.
     *
     * @since 3.0.0
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
     * @param int                         $stackPtr  The position of function call name token.
     *
     * @return array|false Array with information on the callback parameter.
     *                     Or `FALSE` if the parameter is not found.
     *                     See the PHPCSUtils PassedParameters::getParameters() documentation
     *                     for the format of the returned (single-dimensional) array.
     */
    public static function get_callback_parameter( File $phpcsFile, $stackPtr ) {
        $tokens = $phpcsFile->getTokens();
        if ( isset( $tokens[ $stackPtr ] ) === false ) {
            return false;
        }

        $functionName = strtolower( $tokens[ $stackPtr ]['content'] );
        if ( isset( self::$arrayWalkingFunctions[ $functionName ] ) === false ) {
            return false;
        }

        return PassedParameters::getParameter(
            $phpcsFile,
            $stackPtr,
            self::$arrayWalkingFunctions[ $functionName ]['position'],
            self::$arrayWalkingFunctions[ $functionName ]['name']
        );
    }
}