<?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\WP;

use PHPCSUtils\Utils\MessageHelper;
use WordPressCS\WordPress\AbstractClassRestrictionsSniff;
use WordPressCS\WordPress\Helpers\MinimumWPVersionTrait;

/**
 * Restricts the use of deprecated WordPress classes and suggests alternatives.
 *
 * This sniff will throw an error when usage of a deprecated class is detected
 * if the class was deprecated before the minimum supported WP version;
 * a warning otherwise.
 * By default, it is set to presume that a project will support the current
 * WP version and up to three releases before.
 *
 * @since 0.12.0
 * @since 0.13.0 Class name changed: this class is now namespaced.
 * @since 0.14.0 Now has the ability to handle minimum supported WP version
 *               being provided via the command-line or as as <config> value
 *               in a custom ruleset.
 *
 * @uses \WordPressCS\WordPress\Helpers\MinimumWPVersionTrait::$minimum_wp_version
 */
final class DeprecatedClassesSniff extends AbstractClassRestrictionsSniff {

	use MinimumWPVersionTrait;

	/**
	 * List of deprecated classes with alternative when available.
	 *
	 * To be updated after every major release.
	 *
	 * Version numbers should be fully qualified.
	 *
	 * {@internal To be updated after every major release. Last updated for WordPress 6.8.1.}
	 *
	 * @var array
	 */
	private $deprecated_classes = array(

		// WP 3.1.0.
		'WP_User_Search' => array(
			'alt'     => 'WP_User_Query',
			'version' => '3.1.0',
		),

		// WP 3.7.0.
		'WP_HTTP_Fsockopen' => array(
			'alt'     => 'WP_HTTP::request()',
			'version' => '3.7.0',
		),

		// WP 4.9.0.
		'WP_Customize_New_Menu_Section' => array(
			'version' => '4.9.0',
		),
		'WP_Customize_New_Menu_Control' => array(
			'version' => '4.9.0',
		),

		// WP 5.3.0.
		'WP_Privacy_Data_Export_Requests_Table' => array(
			'alt'     => 'WP_Privacy_Data_Export_Requests_List_Table',
			'version' => '5.3.0',
		),
		'WP_Privacy_Data_Removal_Requests_Table' => array(
			'alt'     => 'WP_Privacy_Data_Removal_Requests_List_Table',
			'version' => '5.3.0',
		),
		'Services_JSON' => array(
			'alt'     => 'The PHP native JSON extension',
			'version' => '5.3.0',
		),
		'Services_JSON_Error' => array(
			'alt'     => 'The PHP native JSON extension',
			'version' => '5.3.0',
		),

		// WP 6.4.0.
		'WP_Http_Curl' => array(
			'alt'     => 'WP_Http',
			'version' => '6.4.0',
		),
		'WP_Http_Streams' => array(
			'alt'     => 'WP_Http',
			'version' => '6.4.0',
		),
	);

	/**
	 * Groups of classes to restrict.
	 *
	 * @return array
	 */
	public function getGroups() {
		// Make sure all array keys are lowercase.
		$this->deprecated_classes = array_change_key_case( $this->deprecated_classes, \CASE_LOWER );

		return array(
			'deprecated_classes' => array(
				'classes' => array_keys( $this->deprecated_classes ),
			),
		);
	}

	/**
	 * Process a matched token.
	 *
	 * @param int    $stackPtr        The position of the current token in the stack.
	 * @param string $group_name      The name of the group which was matched. Will
	 *                                always be 'deprecated_classes'.
	 * @param string $matched_content The token content (class name) which was matched
	 *                                in its original case.
	 *
	 * @return void
	 */
	public function process_matched_token( $stackPtr, $group_name, $matched_content ) {

		$this->set_minimum_wp_version();

		$class_name = ltrim( strtolower( $matched_content ), '\\' );

		$message = 'The %s class has been deprecated since WordPress version %s.';
		$data    = array(
			ltrim( $matched_content, '\\' ),
			$this->deprecated_classes[ $class_name ]['version'],
		);

		if ( ! empty( $this->deprecated_classes[ $class_name ]['alt'] ) ) {
			$message .= ' Use %s instead.';
			$data[]   = $this->deprecated_classes[ $class_name ]['alt'];
		}

		MessageHelper::addMessage(
			$this->phpcsFile,
			$message,
			$stackPtr,
			( $this->wp_version_compare( $this->deprecated_classes[ $class_name ]['version'], $this->minimum_wp_version, '<' ) ),
			MessageHelper::stringToErrorcode( $class_name . 'Found' ),
			$data
		);
	}
}