File "ArrayDeclarationSpacingSniff.php"
Full Path: /home/warrior1/public_html/wp-content/themes/storefront/vendor/wp-coding-standards/wpcs/WordPress/Sniffs/Arrays/ArrayDeclarationSpacingSniff.php
File size: 14.56 KB
MIME-type: text/x-php
Charset: utf-8
<?php
/**
* WordPress Coding Standard.
*
* @package WPCS\WordPressCodingStandards
* @link https://github.com/WordPress/WordPress-Coding-Standards
* @license https://opensource.org/licenses/MIT MIT
*/
namespace WordPressCS\WordPress\Sniffs\Arrays;
use WordPressCS\WordPress\Sniff;
use PHP_CodeSniffer\Util\Tokens;
/**
* Enforces WordPress array spacing format.
*
* - Check for no space between array keyword and array opener.
* - Check for no space between the parentheses of an empty array.
* - Checks for one space after the array opener / before the array closer in single-line arrays.
* - Checks that associative arrays are multi-line.
* - Checks that each array item in a multi-line array starts on a new line.
* - Checks that the array closer in a multi-line array is on a new line.
*
* @link https://make.wordpress.org/core/handbook/best-practices/coding-standards/php/#indentation
*
* @package WPCS\WordPressCodingStandards
*
* @since 0.11.0 - The WordPress specific additional checks have now been split off
* from the `WordPress.Arrays.ArrayDeclaration` sniff into this sniff.
* - Added sniffing & fixing for associative arrays.
* @since 0.12.0 Decoupled this sniff from the upstream sniff completely.
* This sniff now extends the WordPressCS native `Sniff` class instead.
* @since 0.13.0 Added the last remaining checks from the `WordPress.Arrays.ArrayDeclaration`
* sniff which were not covered elsewhere.
* The `WordPress.Arrays.ArrayDeclaration` sniff has now been deprecated.
* @since 0.13.0 Class name changed: this class is now namespaced.
* @since 0.14.0 Single item associative arrays are now by default exempt from the
* "must be multi-line" rule. This behaviour can be changed using the
* `allow_single_item_single_line_associative_arrays` property.
*/
class ArrayDeclarationSpacingSniff extends Sniff {
/**
* Whether or not to allow single item associative arrays to be single line.
*
* @since 0.14.0
*
* @var bool Defaults to true.
*/
public $allow_single_item_single_line_associative_arrays = true;
/**
* Token this sniff targets.
*
* Also used for distinguishing between the array and an array value
* which is also an array.
*
* @since 0.12.0
*
* @var array
*/
private $targets = array(
\T_ARRAY => \T_ARRAY,
\T_OPEN_SHORT_ARRAY => \T_OPEN_SHORT_ARRAY,
);
/**
* Returns an array of tokens this test wants to listen for.
*
* @since 0.12.0
*
* @return array
*/
public function register() {
return $this->targets;
}
/**
* Processes this test, when one of its tokens is encountered.
*
* @since 0.12.0 The actual checks contained in this method used to
* be in the `processSingleLineArray()` method.
*
* @param int $stackPtr The position of the current token in the stack.
*
* @return void
*/
public function process_token( $stackPtr ) {
if ( \T_OPEN_SHORT_ARRAY === $this->tokens[ $stackPtr ]['code']
&& $this->is_short_list( $stackPtr )
) {
// Short list, not short array.
return;
}
/*
* Determine the array opener & closer.
*/
$array_open_close = $this->find_array_open_close( $stackPtr );
if ( false === $array_open_close ) {
// Array open/close could not be determined.
return;
}
$opener = $array_open_close['opener'];
$closer = $array_open_close['closer'];
unset( $array_open_close );
/*
* Long arrays only: Check for space between the array keyword and the open parenthesis.
*/
if ( \T_ARRAY === $this->tokens[ $stackPtr ]['code'] ) {
if ( ( $stackPtr + 1 ) !== $opener ) {
$error = 'There must be no space between the "array" keyword and the opening parenthesis';
$error_code = 'SpaceAfterKeyword';
$nextNonWhitespace = $this->phpcsFile->findNext( \T_WHITESPACE, ( $stackPtr + 1 ), ( $opener + 1 ), true );
if ( $nextNonWhitespace !== $opener ) {
// Don't auto-fix: Something other than whitespace found between keyword and open parenthesis.
$this->phpcsFile->addError( $error, $stackPtr, $error_code );
} else {
$fix = $this->phpcsFile->addFixableError( $error, $stackPtr, $error_code );
if ( true === $fix ) {
$this->phpcsFile->fixer->beginChangeset();
for ( $i = ( $stackPtr + 1 ); $i < $opener; $i++ ) {
$this->phpcsFile->fixer->replaceToken( $i, '' );
}
$this->phpcsFile->fixer->endChangeset();
unset( $i );
}
}
unset( $error, $error_code, $nextNonWhitespace, $fix );
}
}
/*
* Check for empty arrays.
*/
$nextNonWhitespace = $this->phpcsFile->findNext( \T_WHITESPACE, ( $opener + 1 ), ( $closer + 1 ), true );
if ( $nextNonWhitespace === $closer ) {
if ( ( $opener + 1 ) !== $closer ) {
$fix = $this->phpcsFile->addFixableError(
'Empty array declaration must have no space between the parentheses',
$stackPtr,
'SpaceInEmptyArray'
);
if ( true === $fix ) {
$this->phpcsFile->fixer->beginChangeset();
for ( $i = ( $opener + 1 ); $i < $closer; $i++ ) {
$this->phpcsFile->fixer->replaceToken( $i, '' );
}
$this->phpcsFile->fixer->endChangeset();
unset( $i );
}
}
// This array is empty, so the below checks aren't necessary.
return;
}
unset( $nextNonWhitespace );
// Pass off to either the single line or multi-line array analysis.
if ( $this->tokens[ $opener ]['line'] === $this->tokens[ $closer ]['line'] ) {
$this->process_single_line_array( $stackPtr, $opener, $closer );
} else {
$this->process_multi_line_array( $stackPtr, $opener, $closer );
}
}
/**
* Process a single-line array.
*
* @since 0.13.0 The actual checks contained in this method used to
* be in the `process()` method.
*
* @param int $stackPtr The position of the current token in the stack.
* @param int $opener The position of the array opener.
* @param int $closer The position of the array closer.
*
* @return void
*/
protected function process_single_line_array( $stackPtr, $opener, $closer ) {
/*
* Check that associative arrays are always multi-line.
*/
$array_has_keys = $this->phpcsFile->findNext( \T_DOUBLE_ARROW, $opener, $closer );
if ( false !== $array_has_keys ) {
$array_items = $this->get_function_call_parameters( $stackPtr );
if ( ( false === $this->allow_single_item_single_line_associative_arrays
&& ! empty( $array_items ) )
|| ( true === $this->allow_single_item_single_line_associative_arrays
&& \count( $array_items ) > 1 )
) {
/*
* Make sure the double arrow is for *this* array, not for a nested one.
*/
$array_has_keys = false; // Reset before doing more detailed check.
foreach ( $array_items as $item ) {
for ( $ptr = $item['start']; $ptr <= $item['end']; $ptr++ ) {
if ( \T_DOUBLE_ARROW === $this->tokens[ $ptr ]['code'] ) {
$array_has_keys = true;
break 2;
}
// Skip passed any nested arrays.
if ( isset( $this->targets[ $this->tokens[ $ptr ]['code'] ] ) ) {
$nested_array_open_close = $this->find_array_open_close( $ptr );
if ( false === $nested_array_open_close ) {
// Nested array open/close could not be determined.
continue;
}
$ptr = $nested_array_open_close['closer'];
}
}
}
if ( true === $array_has_keys ) {
$phrase = 'an';
if ( true === $this->allow_single_item_single_line_associative_arrays ) {
$phrase = 'a multi-item';
}
$fix = $this->phpcsFile->addFixableError(
'When %s array uses associative keys, each value should start on a new line.',
$closer,
'AssociativeArrayFound',
array( $phrase )
);
if ( true === $fix ) {
$this->phpcsFile->fixer->beginChangeset();
foreach ( $array_items as $item ) {
/*
* Add a line break before the first non-empty token in the array item.
* Prevents extraneous whitespace at the start of the line which could be
* interpreted as alignment whitespace.
*/
$first_non_empty = $this->phpcsFile->findNext(
Tokens::$emptyTokens,
$item['start'],
( $item['end'] + 1 ),
true
);
if ( false === $first_non_empty ) {
continue;
}
if ( $item['start'] <= ( $first_non_empty - 1 )
&& \T_WHITESPACE === $this->tokens[ ( $first_non_empty - 1 ) ]['code']
) {
// Remove whitespace which would otherwise becoming trailing
// (as it gives problems with the fixed file).
$this->phpcsFile->fixer->replaceToken( ( $first_non_empty - 1 ), '' );
}
$this->phpcsFile->fixer->addNewlineBefore( $first_non_empty );
}
$this->phpcsFile->fixer->endChangeset();
}
// No need to check for spacing around opener/closer as this array should be multi-line.
return;
}
}
}
/*
* Check that there is a single space after the array opener and before the array closer.
*/
if ( \T_WHITESPACE !== $this->tokens[ ( $opener + 1 ) ]['code'] ) {
$fix = $this->phpcsFile->addFixableError(
'Missing space after array opener.',
$opener,
'NoSpaceAfterArrayOpener'
);
if ( true === $fix ) {
$this->phpcsFile->fixer->addContent( $opener, ' ' );
}
} elseif ( ' ' !== $this->tokens[ ( $opener + 1 ) ]['content'] ) {
$fix = $this->phpcsFile->addFixableError(
'Expected 1 space after array opener, found %s.',
$opener,
'SpaceAfterArrayOpener',
array( \strlen( $this->tokens[ ( $opener + 1 ) ]['content'] ) )
);
if ( true === $fix ) {
$this->phpcsFile->fixer->replaceToken( ( $opener + 1 ), ' ' );
}
}
if ( \T_WHITESPACE !== $this->tokens[ ( $closer - 1 ) ]['code'] ) {
$fix = $this->phpcsFile->addFixableError(
'Missing space before array closer.',
$closer,
'NoSpaceBeforeArrayCloser'
);
if ( true === $fix ) {
$this->phpcsFile->fixer->addContentBefore( $closer, ' ' );
}
} elseif ( ' ' !== $this->tokens[ ( $closer - 1 ) ]['content'] ) {
$fix = $this->phpcsFile->addFixableError(
'Expected 1 space before array closer, found %s.',
$closer,
'SpaceBeforeArrayCloser',
array( \strlen( $this->tokens[ ( $closer - 1 ) ]['content'] ) )
);
if ( true === $fix ) {
$this->phpcsFile->fixer->replaceToken( ( $closer - 1 ), ' ' );
}
}
}
/**
* Process a multi-line array.
*
* @since 0.13.0 The actual checks contained in this method used to
* be in the `ArrayDeclaration` sniff.
*
* @param int $stackPtr The position of the current token in the stack.
* @param int $opener The position of the array opener.
* @param int $closer The position of the array closer.
*
* @return void
*/
protected function process_multi_line_array( $stackPtr, $opener, $closer ) {
/*
* Check that the closing bracket is on a new line.
*/
$last_content = $this->phpcsFile->findPrevious( \T_WHITESPACE, ( $closer - 1 ), $opener, true );
if ( false !== $last_content
&& $this->tokens[ $last_content ]['line'] === $this->tokens[ $closer ]['line']
) {
$fix = $this->phpcsFile->addFixableError(
'Closing parenthesis of array declaration must be on a new line',
$closer,
'CloseBraceNewLine'
);
if ( true === $fix ) {
$this->phpcsFile->fixer->beginChangeset();
if ( $last_content < ( $closer - 1 )
&& \T_WHITESPACE === $this->tokens[ ( $closer - 1 ) ]['code']
) {
// Remove whitespace which would otherwise becoming trailing
// (as it gives problems with the fixed file).
$this->phpcsFile->fixer->replaceToken( ( $closer - 1 ), '' );
}
$this->phpcsFile->fixer->addNewlineBefore( $closer );
$this->phpcsFile->fixer->endChangeset();
}
}
/*
* Check that each array item starts on a new line.
*/
$array_items = $this->get_function_call_parameters( $stackPtr );
$end_of_last_item = $opener;
foreach ( $array_items as $item ) {
$end_of_this_item = ( $item['end'] + 1 );
// Find the line on which the item starts.
$first_content = $this->phpcsFile->findNext(
array( \T_WHITESPACE, \T_DOC_COMMENT_WHITESPACE ),
$item['start'],
$end_of_this_item,
true
);
// Ignore comments after array items if the next real content starts on a new line.
if ( $this->tokens[ $first_content ]['line'] === $this->tokens[ $end_of_last_item ]['line']
&& ( \T_COMMENT === $this->tokens[ $first_content ]['code']
|| isset( Tokens::$phpcsCommentTokens[ $this->tokens[ $first_content ]['code'] ] ) )
) {
$end_of_comment = $first_content;
// Find the end of (multi-line) /* */- style trailing comments.
if ( substr( ltrim( $this->tokens[ $end_of_comment ]['content'] ), 0, 2 ) === '/*' ) {
while ( ( \T_COMMENT === $this->tokens[ $end_of_comment ]['code']
|| isset( Tokens::$phpcsCommentTokens[ $this->tokens[ $end_of_comment ]['code'] ] ) )
&& substr( rtrim( $this->tokens[ $end_of_comment ]['content'] ), -2 ) !== '*/'
&& ( $end_of_comment + 1 ) < $end_of_this_item
) {
$end_of_comment++;
}
if ( $this->tokens[ $end_of_comment ]['line'] !== $this->tokens[ $end_of_last_item ]['line'] ) {
// Multi-line trailing comment.
$end_of_last_item = $end_of_comment;
}
}
$next = $this->phpcsFile->findNext(
array( \T_WHITESPACE, \T_DOC_COMMENT_WHITESPACE ),
( $end_of_comment + 1 ),
$end_of_this_item,
true
);
if ( false === $next ) {
// Shouldn't happen, but just in case.
$end_of_last_item = $end_of_this_item;
continue;
}
if ( $this->tokens[ $next ]['line'] !== $this->tokens[ $first_content ]['line'] ) {
$first_content = $next;
}
}
if ( false === $first_content ) {
// Shouldn't happen, but just in case.
$end_of_last_item = $end_of_this_item;
continue;
}
if ( $this->tokens[ $end_of_last_item ]['line'] === $this->tokens[ $first_content ]['line'] ) {
$fix = $this->phpcsFile->addFixableError(
'Each item in a multi-line array must be on a new line',
$first_content,
'ArrayItemNoNewLine'
);
if ( true === $fix ) {
$this->phpcsFile->fixer->beginChangeset();
if ( ( $end_of_last_item + 1 ) <= ( $first_content - 1 )
&& \T_WHITESPACE === $this->tokens[ ( $first_content - 1 ) ]['code']
) {
// Remove whitespace which would otherwise becoming trailing
// (as it gives problems with the fixed file).
$this->phpcsFile->fixer->replaceToken( ( $first_content - 1 ), '' );
}
$this->phpcsFile->fixer->addNewlineBefore( $first_content );
$this->phpcsFile->fixer->endChangeset();
}
}
$end_of_last_item = $end_of_this_item;
}
}
}