<?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\BackCompat\Helper;

/**
 * Helper utilities for sniffs which take the minimum supported WP version of the
 * code under examination into account.
 *
 * Usage instructions:
 * - Add appropriate `use` statement(s) to the file/class which intends to use this functionality.
 * - Call the `MinimumWPVersionTrait::set_minimum_wp_version()` method in the `process()`/`process_token()`
 *   method.
 * - After that, the `MinimumWPVersionTrait::$minimum_wp_version` property can be freely used
 *   in the sniff.
 *
 * @since 3.0.0 The property and method in this trait were previously contained in the
 *              `WordPressCS\WordPress\Sniff` class and have been moved here.
 */
trait MinimumWPVersionTrait {

	/**
	 * Minimum supported WordPress version.
	 *
	 * Currently used by the `WordPress.Security.PreparedSQLPlaceholders`,
	 * `WordPress.WP.AlternativeFunctions`, `WordPress.WP.Capabilities`,
	 * `WordPress.WP.DeprecatedClasses`, `WordPress.WP.DeprecatedFunctions`,
	 * `WordPress.WP.DeprecatedParameter` and the `WordPress.WP.DeprecatedParameterValues` sniff.
	 *
	 * These sniffs will adapt their behavior based on the minimum supported WP version
	 * indicated.
	 * By default, it is set to presume that a project will support the current
	 * WP version and up to three releases before.
	 *
	 * This property allows changing the minimum supported WP version used by
	 * these sniffs by setting a property in a custom phpcs.xml ruleset.
	 * This property will need to be set for each sniff which uses it.
	 *
	 * Example usage:
	 * <rule ref="WordPress.WP.DeprecatedClasses">
	 *  <properties>
	 *   <property name="minimum_wp_version" value="4.9"/>
	 *  </properties>
	 * </rule>
	 *
	 * Alternatively, the value can be passed in one go for all sniffs using it via
	 * the command line or by setting a `<config>` value in a custom phpcs.xml ruleset.
	 *
	 * CL:      `phpcs --runtime-set minimum_wp_version 5.7`
	 * Ruleset: `<config name="minimum_wp_version" value="6.0"/>`
	 *
	 * @since 0.14.0 Previously the individual sniffs each contained this property.
	 * @since 3.0.0  - Moved from the Sniff class to this dedicated Trait.
	 *               - The property has been renamed from `$minimum_supported_version` to `$minimum_wp_version`.
	 *               - The CLI option has been renamed from `minimum_supported_wp_version` to `minimum_wp_version`.
	 *
	 * @var string WordPress version.
	 */
	public $minimum_wp_version;

	/**
	 * Default minimum supported WordPress version.
	 *
	 * By default, the minimum_wp_version presumes that a project will support the current
	 * WP version and up to three releases before.
	 *
	 * {@internal This should be a constant, but constants in traits are not supported
	 *            until PHP 8.2.}}
	 *
	 * @since 3.0.0
	 *
	 * @var string WordPress version.
	 */
	private $default_minimum_wp_version = '6.5';

	/**
	 * Overrule the minimum supported WordPress version with a command-line/config value.
	 *
	 * Handle setting the minimum supported WP version in one go for all sniffs which
	 * expect it via the command line or via a `<config>` variable in a ruleset.
	 * The config variable overrules the default `$minimum_wp_version` and/or a
	 * `$minimum_wp_version` set for individual sniffs through the ruleset.
	 *
	 * @since 0.14.0
	 * @since 3.0.0  - Moved from the Sniff class to this dedicated Trait.
	 *               - Renamed from `get_wp_version_from_cl()` to `set_minimum_wp_version()`.
	 *
	 * @return void
	 */
	final protected function set_minimum_wp_version() {
		$minimum_wp_version = '';

		// Use a ruleset provided value if available.
		if ( ! empty( $this->minimum_wp_version ) ) {
			$minimum_wp_version = $this->minimum_wp_version;
		}

		// A CLI provided value overrules a ruleset provided value.
		$cli_supported_version = Helper::getConfigData( 'minimum_wp_version' );
		if ( ! empty( $cli_supported_version ) ) {
			$minimum_wp_version = $cli_supported_version;
		}

		// If no valid value was provided, use the default.
		if ( filter_var( $minimum_wp_version, \FILTER_VALIDATE_FLOAT ) === false ) {
			$minimum_wp_version = $this->default_minimum_wp_version;
		}

		$this->minimum_wp_version = $minimum_wp_version;
	}

	/**
	 * Compares two version numbers.
	 *
	 * @since 3.0.0
	 *
	 * @param string $version1 First version number.
	 * @param string $version2 Second version number.
	 * @param string $operator Comparison operator.
	 *
	 * @return bool
	 */
	final protected function wp_version_compare( $version1, $version2, $operator ) {
		$version1 = $this->normalize_version_number( $version1 );
		$version2 = $this->normalize_version_number( $version2 );

		return version_compare( $version1, $version2, $operator );
	}

	/**
	 * Normalize a version number.
	 *
	 * Ensures that a version number is comparable via the PHP version_compare() function
	 * by making sure it complies with the minimum "PHP-standardized" version number requirements.
	 *
	 * Presumes the input is a numeric version number string. The behavior with other input is undefined.
	 *
	 * @since 3.0.0
	 *
	 * @param string $version Version number.
	 *
	 * @return string
	 */
	private function normalize_version_number( $version ) {
		if ( preg_match( '`^\d+\.\d+$`', $version ) ) {
			$version .= '.0';
		}

		return $version;
	}
}