Merge pull request #392 from PHPCSStandards/utils/isshortlist-isshort…

…array-refactor-improve-performance

IsShortArrayOrList: refactor for better accuracy and improved performance

PHPCSUtils/Internal/IsShortArrayOrListWithCache.php

@@ -0,0 +1,269 @@
+<?php
+/**
+ * PHPCSUtils, utility functions and classes for PHP_CodeSniffer sniff developers.
+ *
+ * @package   PHPCSUtils
+ * @copyright 2019-2020 PHPCSUtils Contributors
+ * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
+ * @link      https://github.com/PHPCSStandards/PHPCSUtils
+ */
+
+namespace PHPCSUtils\Internal;
+
+use PHP_CodeSniffer\Files\File;
+use PHPCSUtils\Internal\Cache;
+use PHPCSUtils\Internal\IsShortArrayOrList;
+use PHPCSUtils\Tokens\Collections;
+
+/**
+ * Determination of short array vs short list vs square brackets.
+ *
+ * Uses caching of previous results to mitigate performance issues.
+ *
+ * ---------------------------------------------------------------------------------------------
+ * This class is only intended for internal use by PHPCSUtils and is not part of the public API.
+ * This also means that it has no promise of backward compatibility.
+ *
+ * End-users should use the {@see \PHPCSUtils\Utils\Arrays::isShortArray()}
+ * or the {@see \PHPCSUtils\Utils\Lists::isShortList()} method instead.
+ * ---------------------------------------------------------------------------------------------
+ *
+ * @internal
+ *
+ * @since 1.0.0-alpha4
+ */
+final class IsShortArrayOrListWithCache
+{
+
+    /**
+     * Key used for caching the return value of the short array/short list determination.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @var string
+     */
+    const CACHE_KEY = __CLASS__;
+
+    /**
+     * The PHPCS file in which the current stackPtr was found.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @var \PHP_CodeSniffer\Files\File
+     */
+    private $phpcsFile;
+
+    /**
+     * The token stack from the current file.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @var array
+     */
+    private $tokens;
+
+    /**
+     * The current stack pointer.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @var int
+     */
+    private $stackPtr;
+
+    /**
+     * Stack pointer to the open bracket.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @var int
+     */
+    private $opener;
+
+    /**
+     * Determine whether a T_OPEN/CLOSE_SHORT_ARRAY token is a short array construct
+     * and not a short list.
+     *
+     * This method also accepts `T_OPEN/CLOSE_SQUARE_BRACKET` tokens to allow it to be
+     * PHPCS cross-version compatible as the short array tokenizing has been plagued by
+     * a number of bugs over time.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
+     * @param int                         $stackPtr  The position of the short array bracket token.
+     *
+     * @return bool `TRUE` if the token passed is the open/close bracket of a short array.
+     *              `FALSE` if the token is a short list bracket, a plain square bracket
+     *              or not one of the accepted tokens.
+     */
+    public static function isShortArray(File $phpcsFile, $stackPtr)
+    {
+        return (self::getType($phpcsFile, $stackPtr) === IsShortArrayOrList::SHORT_ARRAY);
+    }
+
+    /**
+     * Determine whether a T_OPEN/CLOSE_SHORT_ARRAY token is a short list construct
+     * in contrast to a short array.
+     *
+     * This method also accepts `T_OPEN/CLOSE_SQUARE_BRACKET` tokens to allow it to be
+     * PHPCS cross-version compatible as the short array tokenizing has been plagued by
+     * a number of bugs over time, which affects the short list determination.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
+     * @param int                         $stackPtr  The position of the short array bracket token.
+     *
+     * @return bool `TRUE` if the token passed is the open/close bracket of a short list.
+     *              `FALSE` if the token is a short array bracket or plain square bracket
+     *              or not one of the accepted tokens.
+     */
+    public static function isShortList(File $phpcsFile, $stackPtr)
+    {
+        return (self::getType($phpcsFile, $stackPtr) === IsShortArrayOrList::SHORT_LIST);
+    }
+
+    /**
+     * Determine whether a T_OPEN/CLOSE_SHORT_ARRAY token is a short array or short list construct.
+     *
+     * This method also accepts `T_OPEN/CLOSE_SQUARE_BRACKET` tokens to allow it to be
+     * PHPCS cross-version compatible as the short array tokenizing has been plagued by
+     * a number of bugs over time, which affects the short list determination.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
+     * @param int                         $stackPtr  The position of the short array bracket token.
+     *
+     * @return string|false The type of construct this bracket was determined to be.
+     *                      Either 'short array', 'short list' or 'square brackets'.
+     *                      Or FALSE is this was not a bracket token.
+     */
+    public static function getType(File $phpcsFile, $stackPtr)
+    {
+        return (new self($phpcsFile, $stackPtr))->process();
+    }
+
+    /**
+     * Constructor.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
+     * @param int                         $stackPtr  The position of the short array bracket token.
+     *
+     * @return void
+     */
+    private function __construct(File $phpcsFile, $stackPtr)
+    {
+        $this->phpcsFile = $phpcsFile;
+        $this->tokens    = $phpcsFile->getTokens();
+        $this->stackPtr  = $stackPtr;
+    }
+
+    /**
+     * Determine whether a T_[OPEN|CLOSE}_[SHORT_ARRAY|SQUARE_BRACKET] token is a short array
+     * or short list construct using previously cached results whenever possible.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @return string|false The type of construct this bracket was determined to be.
+     *                      Either 'short array', 'short list' or 'square brackets'.
+     *                      Or FALSE is this was not a bracket token.
+     */
+    private function process()
+    {
+        if ($this->isValidStackPtr() === false) {
+            return false;
+        }
+
+        $this->opener = $this->getOpener();
+
+        /*
+         * Check the cache in case we've seen this token before.
+         */
+        $type = $this->getFromCache();
+        if ($type !== false) {
+            return $type;
+        }
+
+        /*
+         * If we've not seen the token before, try and solve it and cache the results.
+         *
+         * Make sure to safeguard against unopened/unclosed square brackets (parse error),
+         * which should always be regarded as real square brackets.
+         */
+        $type = IsShortArrayOrList::SQUARE_BRACKETS;
+        if (isset($this->tokens[$this->stackPtr]['bracket_opener'], $this->tokens[$this->stackPtr]['bracket_closer'])) {
+            $solver = new IsShortArrayOrList($this->phpcsFile, $this->opener);
+            $type   = $solver->solve();
+        }
+
+        $this->updateCache($type);
+
+        return $type;
+    }
+
+    /**
+     * Verify the passed token could potentially be a short array or short list token.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @return bool
+     */
+    private function isValidStackPtr()
+    {
+        return (isset($this->tokens[$this->stackPtr]) === true
+            && isset(Collections::shortArrayTokensBC()[$this->tokens[$this->stackPtr]['code']]) === true);
+    }
+
+    /**
+     * Get the stack pointer to the short array/list opener.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @return int
+     */
+    private function getOpener()
+    {
+        $opener = $this->stackPtr;
+        if (isset($this->tokens[$this->stackPtr]['bracket_opener'])) {
+            $opener = $this->tokens[$this->stackPtr]['bracket_opener'];
+        }
+
+        return $opener;
+    }
+
+    /**
+     * Retrieve the bracket "type" of a token from the cache.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @return string|false The previously determined type (which could be an empty string)
+     *                      or FALSE if no cache entry was found for this token.
+     */
+    private function getFromCache()
+    {
+        if (Cache::isCached($this->phpcsFile, self::CACHE_KEY, $this->opener) === true) {
+            return Cache::get($this->phpcsFile, self::CACHE_KEY, $this->opener);
+        }
+
+        return false;
+    }
+
+    /**
+     * Update the cache with information about a particular bracket token.
+     *
+     * @since 1.0.0-alpha4
+     *
+     * @param string $type The type this bracket has been determined to be.
+     *                     Either 'short array', 'short list' or 'square brackets'.
+     *
+     * @return void
+     */
+    private function updateCache($type)
+    {
+        Cache::set($this->phpcsFile, self::CACHE_KEY, $this->opener, $type);
+    }
+}