276 lines
8.5 KiB
PHP
276 lines
8.5 KiB
PHP
|
<?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\Universal\Sniffs\OOStructures;
|
||
|
|
|
||
|
|
use PHP_CodeSniffer\Files\File;
|
||
|
|
use PHP_CodeSniffer\Sniffs\Sniff;
|
||
|
|
use PHP_CodeSniffer\Util\Tokens;
|
||
|
|
use PHPCSUtils\Tokens\Collections;
|
||
|
|
use PHPCSUtils\Utils\ObjectDeclarations;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Verifies that the interface names used in a class/enum "implements" statement or an interface "extends" statement,
|
||
|
|
* are listed in alphabetic order.
|
||
|
|
*
|
||
|
|
* @since 1.0.0
|
||
|
|
*/
|
||
|
|
final class AlphabeticExtendsImplementsSniff implements Sniff
|
||
|
|
{
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Name of the "Alphabetically ordered" metric.
|
||
|
|
*
|
||
|
|
* @since 1.0.0
|
||
|
|
*
|
||
|
|
* @var string
|
||
|
|
*/
|
||
|
|
const METRIC_NAME_ALPHA = 'Interface names in implements/extends ordered alphabetically (%s)';
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Name of the "interface count" metric.
|
||
|
|
*
|
||
|
|
* @since 1.0.0
|
||
|
|
*
|
||
|
|
* @var string
|
||
|
|
*/
|
||
|
|
const METRIC_NAME_COUNT = 'Number of interfaces being implemented/extended';
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The sort order to use for the statement.
|
||
|
|
*
|
||
|
|
* If all names used are unqualified, the sort order won't make a difference.
|
||
|
|
* However, if one or more of the names are partially or fully qualified, the chosen
|
||
|
|
* sort order will determine how the sorting between unqualified, partially and
|
||
|
|
* fully qualified names is handled.
|
||
|
|
*
|
||
|
|
* The sniff supports two sort order options:
|
||
|
|
* - 'name' : sort by the interface name only (default);
|
||
|
|
* - 'full' : sort by the full name as used in the statement (without leading backslash).
|
||
|
|
*
|
||
|
|
* In both cases, the sorting will be done using natural sort, case-insensitive.
|
||
|
|
*
|
||
|
|
* Example:
|
||
|
|
* <code>
|
||
|
|
* class Foo implements \Vendor\DiffIterator, My\Count, DateTimeInterface {}
|
||
|
|
* </code>
|
||
|
|
*
|
||
|
|
* If sorted using the "name" sort-order, the sniff looks just at the interface name, i.e.
|
||
|
|
* `DiffIterator`, `Count` and `DateTimeInterface`, which for this example would mean
|
||
|
|
* the correct order would be `My\Count, DateTimeInterface, \Vendor\DiffIterator`.
|
||
|
|
*
|
||
|
|
* If sorted using the "full" sort-order, the sniff will look at the full name as used
|
||
|
|
* in the `implements` statement, without leading backslashes.
|
||
|
|
* For the example above, this would mean that the correct order would be:
|
||
|
|
* `DateTimeInterface, My\Count, \Vendor\DiffIterator`.
|
||
|
|
*
|
||
|
|
* @since 1.0.0
|
||
|
|
*
|
||
|
|
* @var string
|
||
|
|
*/
|
||
|
|
public $orderby = 'name';
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Returns an array of tokens this test wants to listen for.
|
||
|
|
*
|
||
|
|
* @since 1.0.0
|
||
|
|
*
|
||
|
|
* @return array<int|string>
|
||
|
|
*/
|
||
|
|
public function register()
|
||
|
|
{
|
||
|
|
return (Collections::ooCanExtend() + Collections::ooCanImplement());
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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 setting.
|
||
|
|
*/
|
||
|
|
if ($this->orderby !== 'full') {
|
||
|
|
// Use the default.
|
||
|
|
$this->orderby = 'name';
|
||
|
|
}
|
||
|
|
$metricNameAlpha = \sprintf(self::METRIC_NAME_ALPHA, $this->orderby);
|
||
|
|
|
||
|
|
$tokens = $phpcsFile->getTokens();
|
||
|
|
if (isset($tokens[$stackPtr]['scope_opener']) === false) {
|
||
|
|
// Parse error or live coding. Ignore.
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
|
||
|
|
$scopeOpener = $tokens[$stackPtr]['scope_opener'];
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Get the names.
|
||
|
|
*/
|
||
|
|
if (isset(Collections::ooCanImplement()[$tokens[$stackPtr]['code']]) === true) {
|
||
|
|
$names = ObjectDeclarations::findImplementedInterfaceNames($phpcsFile, $stackPtr);
|
||
|
|
} else {
|
||
|
|
$names = ObjectDeclarations::findExtendedInterfaceNames($phpcsFile, $stackPtr);
|
||
|
|
}
|
||
|
|
|
||
|
|
if (\is_array($names) === false) {
|
||
|
|
// Class/interface/enum doesn't extend or implement.
|
||
|
|
$phpcsFile->recordMetric($stackPtr, self::METRIC_NAME_COUNT, 0);
|
||
|
|
$phpcsFile->recordMetric($stackPtr, $metricNameAlpha, 'n/a');
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
|
||
|
|
$count = \count($names);
|
||
|
|
$phpcsFile->recordMetric($stackPtr, self::METRIC_NAME_COUNT, $count);
|
||
|
|
|
||
|
|
if ($count < 2) {
|
||
|
|
// Nothing to sort.
|
||
|
|
$phpcsFile->recordMetric($stackPtr, $metricNameAlpha, 'n/a');
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Check the order.
|
||
|
|
*/
|
||
|
|
if ($this->orderby === 'name') {
|
||
|
|
$sorted = $this->sortByName($names);
|
||
|
|
} else {
|
||
|
|
$sorted = $this->sortByFull($names);
|
||
|
|
}
|
||
|
|
|
||
|
|
if ($sorted === $names) {
|
||
|
|
// Order is already correct.
|
||
|
|
$phpcsFile->recordMetric($stackPtr, $metricNameAlpha, 'yes');
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
|
||
|
|
$phpcsFile->recordMetric($stackPtr, $metricNameAlpha, 'no');
|
||
|
|
|
||
|
|
/*
|
||
|
|
* Throw the error.
|
||
|
|
*/
|
||
|
|
$keyword = \T_IMPLEMENTS;
|
||
|
|
if (isset(Collections::ooCanImplement()[$tokens[$stackPtr]['code']]) === false) {
|
||
|
|
$keyword = \T_EXTENDS;
|
||
|
|
}
|
||
|
|
|
||
|
|
$fixable = true;
|
||
|
|
$keywordPtr = $phpcsFile->findNext($keyword, ($stackPtr + 1), $scopeOpener);
|
||
|
|
$hasComment = $phpcsFile->findNext(Tokens::$commentTokens, ($keywordPtr + 1), $scopeOpener);
|
||
|
|
if ($hasComment !== false) {
|
||
|
|
$fixable = false;
|
||
|
|
}
|
||
|
|
|
||
|
|
$error = "The interface names in a \"%s %s\" statement should be ordered alphabetically.\n";
|
||
|
|
$error .= 'Expected: %s; Found: %s';
|
||
|
|
$code = \ucfirst(\strtolower($tokens[$keywordPtr]['content'])) . 'WrongOrder';
|
||
|
|
$data = [
|
||
|
|
$tokens[$stackPtr]['content'],
|
||
|
|
$tokens[$keywordPtr]['content'],
|
||
|
|
\implode(', ', $names),
|
||
|
|
\implode(', ', $sorted),
|
||
|
|
];
|
||
|
|
|
||
|
|
if ($fixable === false) {
|
||
|
|
$code .= 'WithComments';
|
||
|
|
$phpcsFile->addError($error, $keywordPtr, $code, $data);
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
|
||
|
|
// OK, so we appear to have a fixable error.
|
||
|
|
$fix = $phpcsFile->addFixableError($error, $keywordPtr, $code, $data);
|
||
|
|
if ($fix === false) {
|
||
|
|
return;
|
||
|
|
}
|
||
|
|
|
||
|
|
$phpcsFile->fixer->beginChangeset();
|
||
|
|
|
||
|
|
// Remove the complete previous extends/implements part.
|
||
|
|
for ($i = ($keywordPtr + 1); $i < $scopeOpener; $i++) {
|
||
|
|
$phpcsFile->fixer->replaceToken($i, '');
|
||
|
|
}
|
||
|
|
|
||
|
|
$phpcsFile->fixer->addContent($keywordPtr, ' ' . \implode(', ', $sorted) . ' ');
|
||
|
|
|
||
|
|
$phpcsFile->fixer->endChangeset();
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Sort an array of potentially mixed qualified and unqualified names by the interface name.
|
||
|
|
*
|
||
|
|
* @since 1.0.0
|
||
|
|
*
|
||
|
|
* @param string[] $names Interface names, potentially mixed qualified and unqualified.
|
||
|
|
*
|
||
|
|
* @return string[]
|
||
|
|
*/
|
||
|
|
protected function sortByName(array $names)
|
||
|
|
{
|
||
|
|
$getLastName = function ($name) {
|
||
|
|
$last = \strrchr($name, '\\');
|
||
|
|
if ($last === false) {
|
||
|
|
$last = $name;
|
||
|
|
} else {
|
||
|
|
$last = \substr($last, 1);
|
||
|
|
}
|
||
|
|
|
||
|
|
return $last;
|
||
|
|
};
|
||
|
|
|
||
|
|
return $this->sortNames($names, $getLastName);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Sort an array of potentially mixed qualified and unqualified names by the full name.
|
||
|
|
*
|
||
|
|
* @since 1.0.0
|
||
|
|
*
|
||
|
|
* @param string[] $names Interface names, potentially mixed qualified and unqualified.
|
||
|
|
*
|
||
|
|
* @return string[]
|
||
|
|
*/
|
||
|
|
protected function sortByFull(array $names)
|
||
|
|
{
|
||
|
|
$trimLeadingBackslash = function ($name) {
|
||
|
|
return \ltrim($name, '\\');
|
||
|
|
};
|
||
|
|
|
||
|
|
return $this->sortNames($names, $trimLeadingBackslash);
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Sort an array of names.
|
||
|
|
*
|
||
|
|
* @since 1.0.0
|
||
|
|
*
|
||
|
|
* @param string[] $names Interface names, potentially mixed qualified and unqualified.
|
||
|
|
* @param callable $prepareNames Function to call to prepare the names before sorting.
|
||
|
|
*
|
||
|
|
* @return string[]
|
||
|
|
*/
|
||
|
|
private function sortNames(array $names, callable $prepareNames)
|
||
|
|
{
|
||
|
|
$preppedNames = \array_map($prepareNames, $names);
|
||
|
|
$names = \array_combine($names, $preppedNames);
|
||
|
|
|
||
|
|
\natcasesort($names);
|
||
|
|
|
||
|
|
return \array_keys($names);
|
||
|
|
}
|
||
|
|
}
|