<?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 WordPressCS\WordPress\Helpers\RulesetPropertyHelper;

/**
 * Helper functions and function lists for checking whether a function prints output.
 *
 * Any sniff class which incorporates this trait will automatically support the
 * following `public` property which can be changed from within a custom ruleset:
 * - `customPrintingFunctions`.
 *
 * @since 3.0.0 The properties in this trait were previously contained partially in the
 *              `WordPressCS\WordPress\Sniff` class and partially in the `EscapeOutputSniff`
 *              class and have been moved here.
 */
trait PrintingFunctionsTrait {

	/**
	 * Custom list of functions which print output incorporating the passed values.
	 *
	 * @since 0.4.0
	 * @since 3.0.0 Moved from the EscapeOutput Sniff class to this trait.
	 *
	 * @var string[]
	 */
	public $customPrintingFunctions = array();

	/**
	 * Functions which print output incorporating the values passed to them.
	 *
	 * @since 0.5.0
	 * @since 0.11.0 Changed from public static to protected non-static.
	 * @since 3.0.0 - Moved from the Sniff class to this trait.
	 *              - Visibility changed from protected to private.
	 *
	 * @var array<string, bool>
	 */
	private $printingFunctions = array(
		'_deprecated_argument'    => true,
		'_deprecated_constructor' => true,
		'_deprecated_file'        => true,
		'_deprecated_function'    => true,
		'_deprecated_hook'        => true,
		'_doing_it_wrong'         => true,
		'_e'                      => true,
		'_ex'                     => true,
		'printf'                  => true,
		'trigger_error'           => true,
		'user_error'              => true,
		'vprintf'                 => true,
		'wp_die'                  => true,
		'wp_dropdown_pages'       => true,
	);

	/**
	 * Cache of previously added custom functions.
	 *
	 * Prevents having to do the same merges over and over again.
	 *
	 * @since 0.4.0
	 * @since 0.11.0 - Changed from public static to protected non-static.
	 *               - Changed the format from simple bool to array.
	 * @since 3.0.0  - Moved from the EscapeOutput Sniff class to this trait.
	 *               - Visibility changed from protected to private.
	 *
	 * @var string[]
	 */
	private $addedCustomPrintingFunctions = array();

	/**
	 * Combined list of WP/PHP native and custom printing functions.
	 *
	 * @since 3.0.0
	 *
	 * @var array<string, bool>
	 */
	private $allPrintingFunctions = array();

	/**
	 * Retrieve a list of all known printing functions.
	 *
	 * @since 3.0.0
	 *
	 * @return array<string, bool>
	 */
	final public function get_printing_functions() {
		if ( array() === $this->allPrintingFunctions
			|| $this->customPrintingFunctions !== $this->addedCustomPrintingFunctions
		) {
			$this->allPrintingFunctions = RulesetPropertyHelper::merge_custom_array(
				$this->customPrintingFunctions,
				$this->printingFunctions
			);

			$this->addedCustomPrintingFunctions = $this->customPrintingFunctions;
		}

		return $this->allPrintingFunctions;
	}

	/**
	 * Check if a particular function is regarded as a printing function.
	 *
	 * @since 3.0.0
	 *
	 * @param string $functionName The name of the function to check.
	 *
	 * @return bool
	 */
	final public function is_printing_function( $functionName ) {
		return isset( $this->get_printing_functions()[ strtolower( $functionName ) ] );
	}
}