<?php
/**
 * PHPCompatibility, an external standard for PHP_CodeSniffer.
 *
 * @package   PHPCompatibility
 * @copyright 2012-2019 PHPCompatibility Contributors
 * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
 * @link      https://github.com/PHPCompatibility/PHPCompatibility
 */

namespace PHPCompatibility\Sniffs\ParameterValues;

use PHPCompatibility\AbstractFunctionCallParameterSniff;
use PHP_CodeSniffer_File as File;
use PHP_CodeSniffer_Tokens as Tokens;

/**
 * Detect passing `$encoding` to `mb_strrpos()` as 3rd argument.
 *
 * The `$encoding` parameter was moved from the third position to the fourth in PHP 5.2.0.
 * For backward compatibility, `$encoding` could be specified as the third parameter, but doing
 * so is deprecated and will be removed in the future.
 *
 * Between PHP 5.2 and PHP 7.3, this was a deprecation in documentation only.
 * As of PHP 7.4, a deprecation warning will be thrown if an encoding is passed as the 3rd
 * argument.
 * As of PHP 8, the argument is expected to change to accept an integer only.
 *
 * PHP version 5.2
 * PHP version 7.4
 *
 * @link https://www.php.net/manual/en/migration74.deprecated.php#migration74.deprecated.mbstring
 * @link https://wiki.php.net/rfc/deprecations_php_7_4#mb_strrpos_with_encoding_as_3rd_argument
 * @link https://www.php.net/manual/en/function.mb-strrpos.php
 *
 * @since 9.3.0
 */
class RemovedMbStrrposEncodingThirdParamSniff extends AbstractFunctionCallParameterSniff {


	/**
	 * Functions to check for.
	 *
	 * @since 9.3.0
	 *
	 * @var array
	 */
	protected $targetFunctions = array(
		'mb_strrpos' => true,
	);

	/**
	 * Tokens which should be recognized as text.
	 *
	 * @since 9.3.0
	 *
	 * @var array
	 */
	private $textStringTokens = array(
		\T_CONSTANT_ENCAPSED_STRING,
		\T_DOUBLE_QUOTED_STRING,
		\T_HEREDOC,
		\T_NOWDOC,
	);

	/**
	 * Tokens which should be recognized as numbers.
	 *
	 * @since 9.3.0
	 *
	 * @var array
	 */
	private $numberTokens = array(
		\T_LNUMBER => \T_LNUMBER,
		\T_DNUMBER => \T_DNUMBER,
		\T_MINUS   => \T_MINUS,
		\T_PLUS    => \T_PLUS,
	);


	/**
	 * Do a version check to determine if this sniff needs to run at all.
	 *
	 * @since 9.3.0
	 *
	 * @return bool
	 */
	protected function bowOutEarly() {
		return $this->supportsAbove( '5.2' ) === false;
	}


	/**
	 * Process the parameters of a matched function.
	 *
	 * @since 9.3.0
	 *
	 * @param \PHP_CodeSniffer_File $phpcsFile    The file being scanned.
	 * @param int                   $stackPtr     The position of the current token in the stack.
	 * @param string                $functionName The token content (function name) which was matched.
	 * @param array                 $parameters   Array with information about the parameters.
	 *
	 * @return int|void Integer stack pointer to skip forward or void to continue
	 *                  normal file processing.
	 */
	public function processParameters( File $phpcsFile, $stackPtr, $functionName, $parameters ) {
		if ( isset( $parameters[3] ) === false ) {
			// Optional third parameter not set.
			return;
		}

		if ( isset( $parameters[4] ) === true ) {
			// Encoding set as fourth parameter.
			return;
		}

		$targetParam = $parameters[3];
		$targets     = $this->numberTokens + Tokens::$emptyTokens;
		$nonNumber   = $phpcsFile->findNext( $targets, $targetParam['start'], ( $targetParam['end'] + 1 ), true );
		if ( $nonNumber === false ) {
			return;
		}

		if ( $this->isNumericCalculation( $phpcsFile, $targetParam['start'], $targetParam['end'] ) === true ) {
			return;
		}

		$hasString = $phpcsFile->findNext( $this->textStringTokens, $targetParam['start'], ( $targetParam['end'] + 1 ) );
		if ( $hasString === false ) {
			// No text strings found. Undetermined.
			return;
		}

		$error = 'Passing the encoding to mb_strrpos() as third parameter is soft deprecated since PHP 5.2';
		if ( $this->supportsAbove( '7.4' ) === true ) {
			$error .= ' and hard deprecated since PHP 7.4';
		}

		$error .= '. Use an explicit 0 as the offset in the third parameter.';

		$phpcsFile->addWarning(
			$error,
			$targetParam['start'],
			'Deprecated'
		);
	}
}
