<?php
/**
* PHPCSExtra, a collection of sniffs and standards for use with PHP_CodeSniffer.
*
* @package PHPCSExtra
* @copyright 2020 PHPCSExtra Contributors
* @license https://opensource.org/licenses/LGPL-3.0 LGPL3
* @link https://github.com/PHPCSStandards/PHPCSExtra
*/
namespace PHPCSExtra\NormalizedArrays\Sniffs\Arrays;
use PHP_CodeSniffer\Files\File;
use PHP_CodeSniffer\Sniffs\Sniff;
use PHP_CodeSniffer\Util\Tokens;
use PHPCSUtils\Tokens\Collections;
use PHPCSUtils\Utils\Arrays;
/**
* Enforce/forbid a comma after the last item in an array declaration.
*
* Allows for different settings for single-line and multi-line arrays.
*
* @since 1.0.0
*/
final class CommaAfterLastSniff implements Sniff
{
/**
* Name of the metric.
*
* @since 1.0.0
*
* @var string
*/
const METRIC_NAME = '%s array - comma after last item';
/**
* Whether or not to enforce a comma after the last array item in a single-line array.
*
* Valid values:
* - 'enforce' to always demand a comma after the last item in single-line arrays;
* - 'forbid' to disallow a comma after the last item in single-line arrays;
* - 'skip' to ignore single-line arrays.
*
* Defaults to: 'forbid'.
*
* @since 1.0.0
*
* @var string
*/
public $singleLine = 'forbid';
/**
* Whether or not to enforce a comma after the last array item in a multi-line array.
*
* Valid values:
* - 'enforce' to always demand a comma after the last item in single-line arrays;
* - 'forbid' to disallow a comma after the last item in single-line arrays;
* - 'skip' to ignore multi-line arrays.
*
* Defaults to: 'enforce'.
*
* @since 1.0.0
*
* @var string
*/
public $multiLine = 'enforce';
/**
* The input values to consider as valid for the public properties.
*
* Used for input validation.
*
* @since 1.0.0
*
* @var array<string, true>
*/
private $validValues = [
'enforce' => true,
'forbid' => true,
'skip' => true,
];
/**
* Returns an array of tokens this test wants to listen for.
*
* @since 1.0.0
*
* @return array<int|string>
*/
public function register()
{
return Collections::arrayOpenTokensBC();
}
/**
* Processes this test, when one of its tokens is encountered.
*
* @since 1.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)
{
// Validate the property input. Invalid values will result in the check being skipped.
if (isset($this->validValues[$this->singleLine]) === false) {
$this->singleLine = 'skip';
}
if (isset($this->validValues[$this->multiLine]) === false) {
$this->multiLine = 'skip';
}
$openClose = Arrays::getOpenClose($phpcsFile, $stackPtr);
if ($openClose === false) {
// Short list, real square bracket, live coding or parse error.
return;
}
$tokens = $phpcsFile->getTokens();
$opener = $openClose['opener'];
$closer = $openClose['closer'];
$action = $this->singleLine;
$phrase = 'single-line';
$errorCode = 'SingleLine';
if ($tokens[$opener]['line'] !== $tokens[$closer]['line']) {
$action = $this->multiLine;
$phrase = 'multi-line';
$errorCode = 'MultiLine';
}
if ($action === 'skip') {
// Nothing to do.
return;
}
$lastNonEmpty = $phpcsFile->findPrevious(Tokens::$emptyTokens, ($closer - 1), $opener, true);
if ($lastNonEmpty === false || $lastNonEmpty === $opener) {
// Bow out: empty array.
return;
}
// If the closer is on the same line as the last element, change the error code for multi-line arrays.
if ($errorCode === 'MultiLine'
&& $tokens[$lastNonEmpty]['line'] === $tokens[$closer]['line']
) {
$errorCode .= 'CloserSameLine';
}
$isComma = ($tokens[$lastNonEmpty]['code'] === \T_COMMA);
$phpcsFile->recordMetric(
$stackPtr,
\sprintf(self::METRIC_NAME, \ucfirst($phrase)),
($isComma === true ? 'yes' : 'no')
);
switch ($action) {
case 'enforce':
if ($isComma === true) {
return;
}
$error = 'There should be a comma after the last array item in a %s array.';
$errorCode = 'Missing' . $errorCode;
$data = [$phrase];
$fix = $phpcsFile->addFixableError($error, $lastNonEmpty, $errorCode, $data);
if ($fix === true) {
$extraContent = ',';
if (($tokens[$lastNonEmpty]['code'] === \T_END_HEREDOC
|| $tokens[$lastNonEmpty]['code'] === \T_END_NOWDOC)
// Check for indentation, if indented, it's a PHP 7.3+ heredoc/nowdoc.
&& $tokens[$lastNonEmpty]['content'] === \ltrim($tokens[$lastNonEmpty]['content'])
) {
// Prevent parse errors in PHP < 7.3 which doesn't support flexible heredoc/nowdoc.
$extraContent = $phpcsFile->eolChar . $extraContent;
}
$phpcsFile->fixer->addContent($lastNonEmpty, $extraContent);
}
return;
case 'forbid':
if ($isComma === false) {
return;
}
$error = 'A comma after the last array item in a %s array is not allowed.';
$errorCode = 'Found' . $errorCode;
$data = [$phrase];
$fix = $phpcsFile->addFixableError($error, $lastNonEmpty, $errorCode, $data);
if ($fix === true) {
$start = $lastNonEmpty;
$end = $lastNonEmpty;
// Make sure we're not leaving a superfluous blank line behind.
$prevNonWhitespace = $phpcsFile->findPrevious(\T_WHITESPACE, ($lastNonEmpty - 1), $opener, true);
$nextNonWhitespace = $phpcsFile->findNext(\T_WHITESPACE, ($lastNonEmpty + 1), ($closer + 1), true);
if ($prevNonWhitespace !== false
&& $tokens[$prevNonWhitespace]['line'] < $tokens[$lastNonEmpty]['line']
&& $nextNonWhitespace !== false
&& $tokens[$nextNonWhitespace]['line'] > $tokens[$lastNonEmpty]['line']
) {
$start = ($prevNonWhitespace + 1);
}
$phpcsFile->fixer->beginChangeset();
for ($i = $start; $i <= $end; $i++) {
$phpcsFile->fixer->replaceToken($i, '');
}
$phpcsFile->fixer->endChangeset();
}
return;
}
}
}