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

/**
 * Helper utilities for recognizing functions related to the WP Hook mechanism.
 *
 * @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 WPHookHelper {

	/**
	 * A list of functions that invoke WP hooks (filters/actions).
	 *
	 * @since 0.10.0
	 * @since 0.11.0 Changed from public static to protected non-static.
	 * @since 3.0.0  - Moved from the Sniff class to this class.
	 *               - The property visibility has changed from `protected` to `private static`.
	 *                 Use the `get_functions()` method for access.
	 *               - The format of the value has changed from a non-relevant boolean to
	 *                 an array with the parameter position and name(s) for the hook name parameter.
	 *
	 * @var array<string, array<string, int|string|string[]>> Function name as key, array with target
	 *                                                        parameter position and name(s) as value.
	 */
	private static $hookInvokeFunctions = array(
		'do_action' => array(
			'position' => 1,
			'name'     => 'hook_name',
		),
		'do_action_ref_array' => array(
			'position' => 1,
			'name'     => 'hook_name',
		),
		'do_action_deprecated' => array(
			'position' => 1,
			'name'     => 'hook_name',
		),
		'apply_filters' => array(
			'position' => 1,
			'name'     => 'hook_name',
		),
		'apply_filters_ref_array' => array(
			'position' => 1,
			'name'     => 'hook_name',
		),
		'apply_filters_deprecated' => array(
			'position' => 1,
			'name'     => 'hook_name',
		),
	);

	/**
	 * Retrieve a list of the WordPress functions which invoke hooks.
	 *
	 * @since 3.0.0
	 *
	 * @param bool $include_deprecated Whether to include the names of functions
	 *                                 which are used to invoke deprecated hooks.
	 *                                 Defaults to `true`.
	 *
	 * @return array<string, bool> Array with the function names as keys. The value is irrelevant.
	 */
	public static function get_functions( $include_deprecated = true ) {
		$hooks = array_fill_keys( array_keys( self::$hookInvokeFunctions ), true );
		if ( false === $include_deprecated ) {
			unset(
				$hooks['do_action_deprecated'],
				$hooks['apply_filters_deprecated']
			);
		}

		return $hooks;
	}

	/**
	 * Retrieve the parameter information for the hook name parameter from a stack of parameters
	 * passed to one of the WP hook functions.
	 *
	 * @since 3.0.0
	 *
	 * @param string $function_name The name of the WP hook function which the parameters were passed to.
	 * @param array  $parameters    The output of a previous call to PassedParameters::getParameters().
	 *
	 * @return array|false Array with information on the parameter at the specified offset,
	 *                     or with the specified name.
	 *                     Or `FALSE` if the specified parameter is not found.
	 *                     See the PHPCSUtils PassedParameters::getParameters() documentation
	 *                     for the format of the returned (single-dimensional) array.
	 */
	public static function get_hook_name_param( $function_name, array $parameters ) {
		$function_lc = strtolower( $function_name );
		if ( isset( self::$hookInvokeFunctions[ $function_lc ] ) === false ) {
			return false;
		}

		return PassedParameters::getParameterFromStack(
			$parameters,
			self::$hookInvokeFunctions[ $function_lc ]['position'],
			self::$hookInvokeFunctions[ $function_lc ]['name']
		);
	}
}