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

namespace PHPCompatibility\Sniffs\Syntax;

use PHPCompatibility\Helpers\ScannedCode;
use PHPCompatibility\Sniff;
use PHP_CodeSniffer\Files\File;
use PHP_CodeSniffer\Util\Tokens;
use PHPCSUtils\Tokens\Collections;

/**
 * Detect function array dereferencing as introduced in PHP 5.4.
 *
 * PHP 5.4 supports direct array dereferencing on the return of a method/function call.
 *
 * As of PHP 7.0, this also works when using curly braces for the dereferencing.
 * While unclear, this most likely has to do with the Uniform Variable Syntax changes.
 *
 * PHP version 5.4
 * PHP version 7.0
 *
 * @link https://www.php.net/manual/en/language.types.array.php#example-63
 * @link https://www.php.net/manual/en/migration54.new-features.php
 * @link https://wiki.php.net/rfc/functionarraydereferencing
 * @link https://wiki.php.net/rfc/uniform_variable_syntax
 *
 * {@internal The reason for splitting the logic of this sniff into different methods is
 *            to allow re-use of the logic by the PHP 7.4 RemovedCurlyBraceArrayAccess sniff.}
 *
 * @since 7.0.0
 * @since 9.3.0  Now also detects dereferencing using curly braces.
 * @since 10.0.0 This class is now `final`.
 */
final class NewFunctionArrayDereferencingSniff extends Sniff
{

    /**
     * Returns an array of tokens this test wants to listen for.
     *
     * @since 7.0.0
     *
     * @return array<int|string>
     */
    public function register()
    {
        return Collections::nameTokens();
    }

    /**
     * Processes this test, when one of its tokens is encountered.
     *
     * @since 7.0.0
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
     * @param int                         $stackPtr  The position of the current token in
     *                                               the stack passed in $tokens.
     *
     * @return void
     */
    public function process(File $phpcsFile, $stackPtr)
    {
        if (ScannedCode::shouldRunOnOrBelow('5.6') === false) {
            return;
        }

        $dereferencing = $this->isFunctionArrayDereferencing($phpcsFile, $stackPtr);
        if (empty($dereferencing)) {
            return;
        }

        $tokens     = $phpcsFile->getTokens();
        $supports53 = ScannedCode::shouldRunOnOrBelow('5.3');

        foreach ($dereferencing as $openBrace => $closeBrace) {
            if ($supports53 === true
                && $tokens[$openBrace]['code'] === \T_OPEN_SQUARE_BRACKET
            ) {
                $phpcsFile->addError(
                    'Function array dereferencing is not present in PHP version 5.3 or earlier',
                    $openBrace,
                    'Found'
                );

                continue;
            }

            // PHP 7.0 function array dereferencing using curly braces.
            if ($tokens[$openBrace]['code'] === \T_OPEN_CURLY_BRACKET) {
                $phpcsFile->addError(
                    'Function array dereferencing using curly braces is not present in PHP version 5.6 or earlier',
                    $openBrace,
                    'FoundUsingCurlies'
                );
            }
        }
    }


    /**
     * Check if the return of a function/method call is being dereferenced.
     *
     * @since 9.3.0 Logic split off from the process method.
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
     * @param int                         $stackPtr  The position of the current token in
     *                                               the stack passed in $tokens.
     *
     * @return array Array containing stack pointers to the open/close braces
     *               involved in the function dereferencing;
     *               or an empty array if no function dereferencing was detected.
     */
    public function isFunctionArrayDereferencing(File $phpcsFile, $stackPtr)
    {
        $tokens = $phpcsFile->getTokens();

        // Next non-empty token should be the open parenthesis.
        $openParenthesis = $phpcsFile->findNext(Tokens::$emptyTokens, ($stackPtr + 1), null, true, null, true);
        if ($openParenthesis === false || $tokens[$openParenthesis]['code'] !== \T_OPEN_PARENTHESIS) {
            return [];
        }

        // Don't throw errors during live coding.
        if (isset($tokens[$openParenthesis]['parenthesis_closer']) === false) {
            return [];
        }

        // Is this token really a function or method call ?
        if ($tokens[$stackPtr]['code'] === \T_STRING) {
            $prevToken = $phpcsFile->findPrevious(Tokens::$emptyTokens, ($stackPtr - 1), null, true);
            if ($prevToken !== false
                && isset(Collections::objectOperators()[$tokens[$prevToken]['code']]) === false
            ) {
                if ($tokens[$prevToken]['code'] === \T_BITWISE_AND) {
                    // This may be a function declared by reference.
                    $prevToken = $phpcsFile->findPrevious(Tokens::$emptyTokens, ($prevToken - 1), null, true);
                }

                $ignore = [
                    \T_FUNCTION  => true,
                    \T_CONST     => true,
                    \T_USE       => true,
                    \T_NEW       => true,
                    \T_CLASS     => true,
                    \T_INTERFACE => true,
                ];

                if (isset($ignore[$tokens[$prevToken]['code']]) === true) {
                    // Not a call to a PHP function or method.
                    return [];
                }
            }
        }

        $current = $tokens[$openParenthesis]['parenthesis_closer'];
        $braces  = [];

        do {
            $nextNonEmpty = $phpcsFile->findNext(Tokens::$emptyTokens, ($current + 1), null, true, null, true);
            if ($nextNonEmpty === false) {
                break;
            }

            if ($tokens[$nextNonEmpty]['code'] === \T_OPEN_SQUARE_BRACKET
                || $tokens[$nextNonEmpty]['code'] === \T_OPEN_CURLY_BRACKET // PHP 7.0+.
            ) {
                if (isset($tokens[$nextNonEmpty]['bracket_closer']) === false) {
                    // Live coding or parse error.
                    break;
                }

                $braces[$nextNonEmpty] = $tokens[$nextNonEmpty]['bracket_closer'];

                // Continue, just in case there is nested array access, i.e. `echo $foo->bar()[0][2];`.
                $current = $tokens[$nextNonEmpty]['bracket_closer'];
                continue;
            }

            // If we're still here, we've reached the end of the function call.
            break;

        } while (true);

        return $braces;
    }
}