<?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 PHP_CodeSniffer\Files\File;
use PHP_CodeSniffer\Util\Tokens;
use PHPCSUtils\BackCompat\BCFile;
use PHPCSUtils\Tokens\Collections;

/**
 * Helper utilities for sniffs which examine WPDB method calls.
 *
 * @since 3.0.0 The method in this trait was previously contained in the
 *              `WordPressCS\WordPress\Sniff` class and has been moved here.
 */
trait WPDBTrait {

    /**
     * Checks whether this is a call to a $wpdb method that we want to sniff.
     *
     * If available in the class using this trait, the $methodPtr, $i and $end properties
     * are automatically set to correspond to the start and end of the method call.
     * The $i property is also set if this is not a method call but rather the
     * use of a $wpdb property.
     *
     * @since 0.8.0
     * @since 0.9.0  The return value is now always boolean. The $end and $i member
     *               vars are automatically updated.
     * @since 0.14.0 Moved this method from the `PreparedSQL` sniff to the base WP sniff.
     * @since 3.0.0  - Moved from the Sniff class to this dedicated Trait.
     *               - The `$phpcsFile` parameter was added.
     *
     * {@internal This method should be refactored to not exhibit "magic" behavior
     *            for properties in the sniff class(es) using it.}}
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile      The file being scanned.
     * @param int                         $stackPtr       The index of the $wpdb variable.
     * @param array                       $target_methods Array of methods. Key(s) should be method name
     *                                                    in lowercase.
     *
     * @return bool Whether this is a $wpdb method call.
     */
    final protected function is_wpdb_method_call( File $phpcsFile, $stackPtr, array $target_methods ) {
        $tokens = $phpcsFile->getTokens();
        if ( isset( $tokens[ $stackPtr ] ) === false ) {
            return false;
        }

        // Check for wpdb.
        if ( ( \T_VARIABLE === $tokens[ $stackPtr ]['code'] && '$wpdb' !== $tokens[ $stackPtr ]['content'] )
            || ( \T_STRING === $tokens[ $stackPtr ]['code'] && 'wpdb' !== strtolower( $tokens[ $stackPtr ]['content'] ) )
        ) {
            return false;
        }

        // Check that this is a method call.
        $is_object_call = $phpcsFile->findNext( Tokens::$emptyTokens, ( $stackPtr + 1 ), null, true );
        if ( false === $is_object_call
            || isset( Collections::objectOperators()[ $tokens[ $is_object_call ]['code'] ] ) === false
        ) {
            return false;
        }

        $methodPtr = $phpcsFile->findNext( Tokens::$emptyTokens, ( $is_object_call + 1 ), null, true, null, true );
        if ( false === $methodPtr ) {
            return false;
        }

        if ( \T_STRING === $tokens[ $methodPtr ]['code'] && property_exists( $this, 'methodPtr' ) ) {
            $this->methodPtr = $methodPtr;
        }

        // Find the opening parenthesis.
        $opening_paren = $phpcsFile->findNext( Tokens::$emptyTokens, ( $methodPtr + 1 ), null, true, null, true );

        if ( false === $opening_paren ) {
            return false;
        }

        if ( property_exists( $this, 'i' ) ) {
            $this->i = $opening_paren;
        }

        if ( \T_OPEN_PARENTHESIS !== $tokens[ $opening_paren ]['code']
            || ! isset( $tokens[ $opening_paren ]['parenthesis_closer'] )
        ) {
            return false;
        }

        // Check that this is one of the methods that we are interested in.
        if ( ! isset( $target_methods[ strtolower( $tokens[ $methodPtr ]['content'] ) ] ) ) {
            return false;
        }

        // Find the end of the first parameter.
        $end = BCFile::findEndOfStatement( $phpcsFile, $opening_paren + 1 );

        if ( \T_COMMA !== $tokens[ $end ]['code'] ) {
            ++$end;
        }

        if ( property_exists( $this, 'end' ) ) {
            $this->end = $end;
        }

        return true;
    }
}