Bump/install phpcsutils to 1.0.1 (4fd2e30)

Those utilities were previously part of the PHPCompatibility standard
and now, as many of them and a lot new, are general-purpose, reusable by other
standards, they are a separate (meta) standard.

PHPCSUtils/BackCompat/BCTokens.php

@@ -0,0 +1,123 @@
+<?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\BackCompat;
+
+use PHP_CodeSniffer\Util\Tokens;
+use PHPCSUtils\Exceptions\InvalidTokenArray;
+use PHPCSUtils\Tokens\Collections;
+
+/**
+ * Token arrays related utility methods.
+ *
+ * PHPCS provides a number of static token arrays in the {@see \PHP_CodeSniffer\Util\Tokens}
+ * class.
+ * Some of these token arrays will not be available in older PHPCS versions.
+ * Some will not contain the same set of tokens across PHPCS versions.
+ *
+ * This class is a compatibility layer to allow for retrieving these token arrays
+ * with a consistent token content across PHPCS versions.
+ * The one caveat is that the token constants do need to be available.
+ *
+ * Recommended usage:
+ * Only use the methods in this class when needed. I.e. when your sniff unit tests indicate
+ * a PHPCS cross-version compatibility issue related to inconsistent token arrays.
+ *
+ * All PHPCS token arrays are supported, though only a limited number of them are different
+ * across PHPCS versions.
+ *
+ * The names of the PHPCS native token arrays translate one-on-one to the methods in this class:
+ * - `PHP_CodeSniffer\Util\Tokens::$emptyTokens` => `PHPCSUtils\BackCompat\BCTokens::emptyTokens()`
+ * - `PHP_CodeSniffer\Util\Tokens::$operators` => `PHPCSUtils\BackCompat\BCTokens::operators()`
+ * - ... etc
+ *
+ * The order of the tokens in the arrays may differ between the PHPCS native token arrays and
+ * the token arrays returned by this class.
+ *
+ * @since 1.0.0
+ *
+ * @method static array arithmeticTokens() Tokens that represent arithmetic operators.
+ * @method static array assignmentTokens() Tokens that represent assignments.
+ * @method static array blockOpeners() Tokens that open code blocks.
+ * @method static array booleanOperators() Tokens that perform boolean operations.
+ * @method static array bracketTokens() Tokens that represent brackets and parenthesis.
+ * @method static array castTokens() Tokens that represent type casting.
+ * @method static array commentTokens() Tokens that are comments.
+ * @method static array comparisonTokens() Tokens that represent comparison operator.
+ * @method static array contextSensitiveKeywords() Tokens representing context sensitive keywords in PHP.
+ * @method static array emptyTokens() Tokens that don't represent code.
+ * @method static array equalityTokens() Tokens that represent equality comparisons.
+ * @method static array heredocTokens() Tokens that make up a heredoc string.
+ * @method static array includeTokens() Tokens that include files.
+ * @method static array magicConstants() Tokens representing PHP magic constants.
+ * @method static array methodPrefixes() Tokens that can prefix a method name.
+ * @method static array ooScopeTokens() Tokens that open class and object scopes.
+ * @method static array operators() Tokens that perform operations.
+ * @method static array parenthesisOpeners() Token types that open parenthesis.
+ * @method static array phpcsCommentTokens() Tokens that are comments containing PHPCS instructions.
+ * @method static array scopeModifiers() Tokens that represent scope modifiers.
+ * @method static array scopeOpeners() Tokens that are allowed to open scopes.
+ * @method static array stringTokens() Tokens that represent strings.
+ * Note that `T_STRING`s are NOT represented in this list as this list
+ * is about _text_ strings.
+ * @method static array textStringTokens() Tokens that represent text strings.
+ */
+final class BCTokens
+{
+
+ /**
+ * Handle calls to (undeclared) methods for token arrays which haven't received any
+ * changes since PHPCS 3.7.1.
+ *
+ * @since 1.0.0
+ *
+ * @param string $name The name of the method which has been called.
+ * @param array $args Any arguments passed to the method.
+ * Unused as none of the methods take arguments.
+ *
+ * @return array <int|string> => <int|string> Token array
+ *
+ * @throws \PHPCSUtils\Exceptions\InvalidTokenArray When an invalid token array is requested.
+ */
+ public static function __callStatic($name, $args)
+ {
+ if (isset(Tokens::${$name})) {
+ return Tokens::${$name};
+ }
+
+ // Unknown token array requested.
+ throw InvalidTokenArray::create($name);
+ }
+
+ /**
+ * Tokens that represent the names of called functions.
+ *
+ * Retrieve the PHPCS function name tokens array in a cross-version compatible manner.
+ *
+ * Changelog for the PHPCS native array:
+ * - Introduced in PHPCS 2.3.3.
+ * - PHPCS 3.7.2: `T_PARENT` added to the array.
+ * - PHPCS 4.0.0: `T_NAME_QUALIFIED`, `T_NAME_FULLY_QUALIFIED` and `T_NAME_RELATIVE` added to the array.
+ *
+ * @see \PHP_CodeSniffer\Util\Tokens::$functionNameTokens Original array.
+ *
+ * @since 1.0.0
+ *
+ * @return array <int|string> => <int|string> Token array.
+ */
+ public static function functionNameTokens()
+ {
+ $tokens = Tokens::$functionNameTokens;
+ $tokens += Collections::ooHierarchyKeywords();
+ $tokens += Collections::nameTokens();
+
+ return $tokens;
+ }
+}

PHPCSUtils/BackCompat/Helper.php

@@ -0,0 +1,197 @@
+<?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\BackCompat;
+
+use PHP_CodeSniffer\Config;
+use PHP_CodeSniffer\Exceptions\RuntimeException;
+use PHP_CodeSniffer\Files\File;
+
+/**
+ * Utility methods to retrieve (configuration) information from PHP_CodeSniffer.
+ *
+ * PHP_CodeSniffer cross-version compatibility helper.
+ *
+ * @since 1.0.0 The initial methods in this class have been ported over from
+ * the external PHPCompatibility & WPCS standards.
+ */
+final class Helper
+{
+
+ /**
+ * The default tab width used by PHP_CodeSniffer.
+ *
+ * @since 1.0.0
+ *
+ * @var int
+ */
+ const DEFAULT_TABWIDTH = 4;
+
+ /**
+ * Get the PHP_CodeSniffer version number.
+ *
+ * @since 1.0.0
+ *
+ * @return string
+ */
+ public static function getVersion()
+ {
+ return Config::VERSION;
+ }
+
+ /**
+ * Pass config data to PHP_CodeSniffer.
+ *
+ * @since 1.0.0
+ *
+ * @param string $key The name of the config value.
+ * @param string|null $value The value to set. If `null`, the config entry
+ * is deleted, reverting it to the default value.
+ * @param bool $temp Set this config data temporarily for this script run.
+ * This will not write the config data to the config file.
+ * @param \PHP_CodeSniffer\Config $config The PHPCS config object.
+ * This parameter is required for PHPCS 4.x, optional
+ * for PHPCS 3.x and not possible to pass for PHPCS 2.x.
+ * Passing the `$phpcsFile->config` property should work
+ * in PHPCS 3.x and higher.
+ *
+ * @return bool Whether the setting of the data was successfull.
+ */
+ public static function setConfigData($key, $value, $temp = false, $config = null)
+ {
+ if (isset($config) === true) {
+ // PHPCS 3.x and 4.x.
+ return $config->setConfigData($key, $value, $temp);
+ }
+
+ if (\version_compare(self::getVersion(), '3.99.99', '>') === true) {
+ throw new RuntimeException('Passing the $config parameter is required in PHPCS 4.x');
+ }
+
+ // PHPCS 3.x.
+ return Config::setConfigData($key, $value, $temp);
+ }
+
+ /**
+ * Get the value of a single PHP_CodeSniffer config key.
+ *
+ * @see Helper::getCommandLineData() Alternative for the same which is more reliable
+ * if the `$phpcsFile` object is available.
+ *
+ * @since 1.0.0
+ *
+ * @param string $key The name of the config value.
+ *
+ * @return string|null
+ */
+ public static function getConfigData($key)
+ {
+ return Config::getConfigData($key);
+ }
+
+ /**
+ * Get the value of a CLI overrulable single PHP_CodeSniffer config key.
+ *
+ * Use this for config keys which can be set in the `CodeSniffer.conf` file,
+ * on the command-line or in a ruleset.
+ *
+ * @since 1.0.0
+ *
+ * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being processed.
+ * @param string $key The name of the config value.
+ *
+ * @return string|null
+ */
+ public static function getCommandLineData(File $phpcsFile, $key)
+ {
+ if (isset($phpcsFile->config->{$key})) {
+ return $phpcsFile->config->{$key};
+ }
+
+ return null;
+ }
+
+ /**
+ * Get the applicable tab width as passed to PHP_CodeSniffer from the
+ * command-line or the ruleset.
+ *
+ * @since 1.0.0
+ *
+ * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being processed.
+ *
+ * @return int Tab width. Defaults to the PHPCS native default of 4.
+ */
+ public static function getTabWidth(File $phpcsFile)
+ {
+ $tabWidth = self::getCommandLineData($phpcsFile, 'tabWidth');
+ if ($tabWidth > 0) {
+ return (int) $tabWidth;
+ }
+
+ return self::DEFAULT_TABWIDTH;
+ }
+
+ /**
+ * Get the applicable (file) encoding as passed to PHP_CodeSniffer from the
+ * command-line or the ruleset.
+ *
+ * @since 1.0.0
+ *
+ * @param \PHP_CodeSniffer\Files\File|null $phpcsFile Optional. The current file being processed.
+ *
+ * @return string Encoding. Defaults to the PHPCS native default, which is 'utf-8'
+ * for PHPCS 3.x.
+ */
+ public static function getEncoding(File $phpcsFile = null)
+ {
+ $default = 'utf-8';
+
+ if ($phpcsFile instanceof File) {
+ // Most reliable.
+ $encoding = self::getCommandLineData($phpcsFile, 'encoding');
+ if ($encoding === null) {
+ $encoding = $default;
+ }
+
+ return $encoding;
+ }
+
+ // Less reliable.
+ $encoding = self::getConfigData('encoding');
+ if ($encoding === null) {
+ $encoding = $default;
+ }
+
+ return $encoding;
+ }
+
+ /**
+ * Check whether the "--ignore-annotations" option is in effect.
+ *
+ * @since 1.0.0
+ *
+ * @param \PHP_CodeSniffer\Files\File|null $phpcsFile Optional. The current file being processed.
+ *
+ * @return bool `TRUE` if annotations should be ignored, `FALSE` otherwise.
+ */
+ public static function ignoreAnnotations(File $phpcsFile = null)
+ {
+ if (isset($phpcsFile, $phpcsFile->config->annotations)) {
+ return ! $phpcsFile->config->annotations;
+ }
+
+ $annotations = Config::getConfigData('annotations');
+ if (isset($annotations)) {
+ return ! $annotations;
+ }
+
+ return false;
+ }
+}

PHPCSUtils/Exceptions/InvalidTokenArray.php

@@ -0,0 +1,44 @@
+<?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\Exceptions;
+
+use PHP_CodeSniffer\Exceptions\RuntimeException;
+
+/**
+ * Exception thrown when an non-existent token array is requested.
+ *
+ * @since 1.0.0
+ */
+final class InvalidTokenArray extends RuntimeException
+{
+
+ /**
+ * Create a new invalid token array exception with a standardized text.
+ *
+ * @since 1.0.0
+ *
+ * @param string $name The name of the token array requested.
+ *
+ * @return \PHPCSUtils\Exceptions\InvalidTokenArray
+ */
+ public static function create($name)
+ {
+ $stack = \debug_backtrace(\DEBUG_BACKTRACE_IGNORE_ARGS, 2);
+
+ return new self(
+ \sprintf(
+ 'Call to undefined method %s::%s()',
+ $stack[1]['class'],
+ $name
+ )
+ );
+ }
+}