<?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\ControlStructures;
use PHPCompatibility\Helpers\ComplexVersionNewFeatureTrait;
use PHPCompatibility\Helpers\ScannedCode;
use PHPCompatibility\Sniff;
use PHP_CodeSniffer\Files\File;
use PHP_CodeSniffer\Util\Tokens;
use PHPCSUtils\Utils\MessageHelper;
use PHPCSUtils\Utils\TextStrings;
/**
* Check for valid execution directives set with `declare()`.
*
* The sniff contains three distinct checks:
* - Check if the execution directive used is valid. PHP currently only supports
* three execution directives.
* - Check if the execution directive used is available in the PHP versions
* for which support is being checked.
* In the case of the `encoding` directive on PHP 5.3, support is conditional
* on the `--enable-zend-multibyte` compilation option. This will be indicated as such.
* - Check whether the value for the directive is valid.
*
* PHP version All
*
* @link https://www.php.net/manual/en/control-structures.declare.php
* @link https://wiki.php.net/rfc/scalar_type_hints_v5#strict_types_declare_directive
*
* @since 7.0.3
* @since 7.1.0 Now extends the `AbstractNewFeatureSniff` instead of the base `Sniff` class.
* @since 10.0.0 - Now extends the base `Sniff` class and uses the `ComplexVersionNewFeatureTrait`.
* - This class is now `final`.
*/
final class NewExecutionDirectivesSniff extends Sniff
{
use ComplexVersionNewFeatureTrait;
/**
* A list of new execution directives
*
* The array lists : version number with false (not present) or true (present).
* If the execution order is conditional, add the condition as a string to the version nr.
* If's sufficient to list the first version where the execution directive appears.
*
* @since 7.0.3
*
* @var array<string, array<string, bool|string|array>>
*/
protected $newDirectives = [
'ticks' => [
'3.1' => false,
'4.0' => true,
'valid_value_callback' => 'isNumeric',
],
'encoding' => [
'5.2' => false,
'5.3' => '--enable-zend-multibyte', // Directive ignored unless.
'5.4' => true,
'valid_value_callback' => 'validEncoding',
],
'strict_types' => [
'5.6' => false,
'7.0' => true,
'valid_values' => ['0', '1'],
],
];
/**
* Tokens to ignore when trying to find the value for the directive.
*
* @since 7.0.3
*
* @var array
*/
protected $ignoreTokens = [];
/**
* Returns an array of tokens this test wants to listen for.
*
* @since 7.0.3
*
* @return array<int|string>
*/
public function register()
{
$this->ignoreTokens = Tokens::$emptyTokens;
$this->ignoreTokens[\T_EQUAL] = \T_EQUAL;
return [\T_DECLARE];
}
/**
* Processes this test, when one of its tokens is encountered.
*
* @since 7.0.3
*
* @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)
{
$tokens = $phpcsFile->getTokens();
if (isset($tokens[$stackPtr]['parenthesis_opener'], $tokens[$stackPtr]['parenthesis_closer']) === false) {
return;
}
$openParenthesis = $tokens[$stackPtr]['parenthesis_opener'];
$closeParenthesis = $tokens[$stackPtr]['parenthesis_closer'];
$start = ($openParenthesis + 1);
do {
$comma = $phpcsFile->findNext(\T_COMMA, $start, $closeParenthesis);
if ($comma === false) {
// Found last directive.
$this->processDirective($phpcsFile, $start, $closeParenthesis);
break;
}
// Multi-directive declare statement.
$this->processDirective($phpcsFile, $start, $comma);
$start = ($comma + 1);
} while ($start < $closeParenthesis);
}
/**
* Processes one individual declare execution directive.
*
* @since 10.0.0
*
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
* @param int $start The position of the start of the directive.
* @param int $end The position of the end of the directive.
*
* @return void
*/
protected function processDirective($phpcsFile, $start, $end)
{
$tokens = $phpcsFile->getTokens();
$directivePtr = $phpcsFile->findNext(\T_STRING, $start, $end);
if ($directivePtr === false) {
return;
}
$directiveContent = $tokens[$directivePtr]['content'];
$directiveContentLC = \strtolower($directiveContent);
if (isset($this->newDirectives[$directiveContentLC]) === false) {
$error = 'Declare can only be used with the directives %s. Found: %s';
$data = [
\implode(', ', \array_keys($this->newDirectives)),
$directiveContent,
];
$phpcsFile->addError($error, $directivePtr, 'InvalidDirectiveFound', $data);
} else {
// Check for valid directive for version.
$itemInfo = [
'name' => $directiveContentLC,
];
$this->handleFeature($phpcsFile, $directivePtr, $itemInfo);
// Check for valid directive value.
$valuePtr = $phpcsFile->findNext($this->ignoreTokens, $directivePtr + 1, $end, true);
if ($valuePtr === false) {
return;
}
$this->addWarningOnInvalidValue($phpcsFile, $valuePtr, $directiveContentLC);
}
}
/**
* Retrieve the "last version before" and potential conditions from an array with arbitrary contents.
*
* The array is expected to have at least one entry with a PHP version number as a key
* and `false` as the value.
*
* @param array $itemArray Sub-array for a specific matched item from a complex version array.
*
* @return string[] Array with three keys `'not_in_version'`, `'conditional_version'`, `'condition'`.
* The array values will always be strings and will be either the values retrieved
* from the $itemArray or an empty string if the value for a key was unavailable
* or could not be determined.
*/
protected function getExtendedVersionInfo(array $itemArray)
{
$versionInfo = $this->getVersionInfo($itemArray);
$versionInfo['conditional_version'] = '';
$versionInfo['condition'] = '';
foreach ($itemArray as $version => $present) {
if (\preg_match('`^\d\.\d(\.\d{1,2})?$`', $version) !== 1) {
// Not a version key.
continue;
}
if (\is_string($present) === true) {
// We cannot test for compilation option (ok, except by scraping the output of phpinfo...).
$versionInfo['conditional_version'] = $version;
$versionInfo['condition'] = $present;
}
}
return $versionInfo;
}
/**
* Handle the retrieval of relevant information and - if necessary - throwing of an
* error for a matched item.
*
* @since 10.0.0
*
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
* @param int $stackPtr The position of the relevant token in
* the stack.
* @param array $itemInfo Base information about the item.
*
* @return void
*/
protected function handleFeature(File $phpcsFile, $stackPtr, array $itemInfo)
{
$itemArray = $this->newDirectives[$itemInfo['name']];
$versionInfo = $this->getExtendedVersionInfo($itemArray);
$shouldError = false;
if (empty($versionInfo['not_in_version']) === false
&& ScannedCode::shouldRunOnOrBelow($versionInfo['not_in_version']) === true
) {
$shouldError = true;
} elseif (empty($versionInfo['conditional_version']) === false
&& ScannedCode::shouldRunOnOrBelow($versionInfo['conditional_version']) === true
) {
$shouldError = true;
// Reset the 'not_in_version' info as it is not relevant for the current notice.
$versionInfo['not_in_version'] = '';
}
if ($shouldError === false) {
return;
}
$this->addError($phpcsFile, $stackPtr, $itemInfo, $itemArray, $versionInfo);
}
/**
* Generates the error or warning for this item.
*
* @since 7.0.3
* @since 7.1.0 This method now overloads the method from the `AbstractNewFeatureSniff` class.
* - Renamed from `maybeAddError()` to `addError()`.
* - Changed visibility from `protected` to `public`.
* @since 10.0.0 - Added new $itemArray parameter.
* - Changed visibility from `public` to `protected`.
*
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
* @param int $stackPtr The position of the relevant token in
* the stack.
* @param array $itemInfo Base information about the item.
* @param array $itemArray The sub-array with all the details about
* this item.
* @param string[] $versionInfo Array with detail (version) information
* relevant to the item.
*
* @return void
*/
protected function addError(File $phpcsFile, $stackPtr, array $itemInfo, array $itemArray, array $versionInfo)
{
if ($versionInfo['not_in_version'] !== '') {
// Overrule the default message template.
$this->msgTemplate = 'Directive %s is not present in PHP version %s or earlier';
$msgInfo = $this->getMessageInfo($itemInfo['name'], $itemInfo['name'], $versionInfo);
$phpcsFile->addError($msgInfo['message'], $stackPtr, $msgInfo['errorcode'], $msgInfo['data']);
} elseif ($versionInfo['conditional_version'] !== '') {
$error = 'Directive %s is present in PHP version %s but will be disregarded unless PHP is compiled with %s';
$errorCode = MessageHelper::stringToErrorCode($itemInfo['name'], true) . 'WithConditionFound';
$data = [
$itemInfo['name'],
$versionInfo['conditional_version'],
$versionInfo['condition'],
];
$phpcsFile->addWarning($error, $stackPtr, $errorCode, $data);
}
}
/**
* Generates a error or warning for this sniff.
*
* @since 7.0.3
* @since 7.0.6 Renamed from `addErrorOnInvalidValue()` to `addWarningOnInvalidValue()`.
*
* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
* @param int $stackPtr The position of the execution directive value
* in the token array.
* @param string $directive The directive.
*
* @return void
*/
protected function addWarningOnInvalidValue(File $phpcsFile, $stackPtr, $directive)
{
$tokens = $phpcsFile->getTokens();
$value = $tokens[$stackPtr]['content'];
if ($directive === 'encoding' && isset(Tokens::$stringTokens[$tokens[$stackPtr]['code']]) === true) {
$value = TextStrings::stripQuotes($value);
}
$isError = false;
if (isset($this->newDirectives[$directive]['valid_values'])) {
if (\in_array($value, $this->newDirectives[$directive]['valid_values'], true) === false) {
$isError = true;
}
} elseif (isset($this->newDirectives[$directive]['valid_value_callback'])) {
$valid = \call_user_func([$this, $this->newDirectives[$directive]['valid_value_callback']], $value);
if ($valid === false) {
$isError = true;
}
}
if ($isError === true) {
$error = 'The execution directive %s does not seem to have a valid value. Please review. Found: %s';
$errorCode = MessageHelper::stringToErrorCode($directive, true) . 'InvalidValueFound';
$data = [
$directive,
$value,
];
$phpcsFile->addWarning($error, $stackPtr, $errorCode, $data);
}
}
/**
* Check whether a value is numeric.
*
* Callback function to test whether the value for an execution directive is valid.
*
* @since 7.0.3
*
* @param mixed $value The value to test.
*
* @return bool
*/
protected function isNumeric($value)
{
return \is_numeric($value);
}
/**
* Check whether a value is a valid encoding.
*
* Callback function to test whether the value for an execution directive is valid.
*
* @since 7.0.3
*
* @param mixed $value The value to test.
*
* @return bool
*/
protected function validEncoding($value)
{
static $encodings;
if (isset($encodings) === false && \function_exists('mb_list_encodings')) {
$encodings = \mb_list_encodings();
}
if (empty($encodings) || \is_array($encodings) === false) {
// If we can't test the encoding, let it pass through.
return true;
}
return \in_array($value, $encodings, true);
}
}