MultipleStatementAlignmentSniff
extends Sniff
in package
Enforces alignment of the double arrow assignment operator for multi-item, multi-line arrays.
- Align the double arrow operator to the same column for each item in a multi-item array.
- Allows for setting a maxColumn property to aid in managing line-length.
- Allows for new line(s) before a double arrow (configurable).
- Allows for handling multi-line array items differently if so desired (configurable).
Tags
Table of Contents
Properties
- $alignMultilineItems : string|int
- Whether or not to align the arrow operator for multi-line array items.
- $exact : bool
- Whether the alignment should be exact.
- $ignoreNewlines : bool
- Whether or not to ignore an array item for the purpose of alignment when a new line is found between the array key and the double arrow.
- $maxColumn : int
- The maximum column on which the double arrow alignment should be set.
- $phpcsFile : File
- The current file being sniffed.
- $tokens : array<string|int, mixed>
- The list of tokens in the current file being sniffed.
- $number : string
- Storage for parsed $alignMultilineItems numeric part.
- $operator : string
- Storage for parsed $alignMultilineItems operator part.
Methods
- process() : int|void
- Set sniff properties and hand off to child class for processing of the token.
- process_token() : int|void
- Processes this test, when one of its tokens is encountered.
- register() : array<string|int, mixed>
- Returns an array of tokens this test wants to listen for.
- process_multi_line_array() : void
- Process a multi-line array.
- process_single_line_array() : int|void
- Process a single-line array.
- validate_align_multiline_items() : void
- Validate that a valid value has been received for the alignMultilineItems property.
Properties
$alignMultilineItems
Whether or not to align the arrow operator for multi-line array items.
public
string|int
$alignMultilineItems
= 'always'
Whether or not an item is regarded as multi-line is based on the value of the item, not the key.
Valid values are:
- 'always': Default. Align all arrays items regardless of single/multi-line.
- 'never': Never align array items which span multiple lines. This will enforce one space between the array index and the double arrow operator for multi-line array items, independently of the alignment of the rest of the array items. Multi-line items where the arrow is already aligned with the "expected" alignment, however, will be left alone.
- operator : Only align the operator for multi-line arrays items if the
- number percentage of multi-line items passes the comparison.
- As it is a percentage, the number has to be between 0 and 100.
- Supported operators: <, <=, >, >=, ==, =, !=, <>
- The percentage is calculated against all array items
(with and without assignment operator).
- The (new) expected alignment will be calculated based only
on the items being aligned.
- Multi-line items where the arrow is already aligned with the
(new) "expected" alignment, however, will be left alone.
Examples:
* Setting this to
!=100or<100means that alignment will be enforced, unless all array items are multi-line. This is probably the most commonly desired situation. * Setting this to=100means that alignment will only be enforced, if all array items are multi-line. * Setting this to<50means that the majority of array items need to be single line before alignment is enforced for multi-line items in the array. * Setting this to=0is useless as in that case there are no multi-line items in the array anyway.
- number percentage of multi-line items passes the comparison.
- As it is a percentage, the number has to be between 0 and 100.
- Supported operators: <, <=, >, >=, ==, =, !=, <>
- The percentage is calculated against all array items
(with and without assignment operator).
- The (new) expected alignment will be calculated based only
on the items being aligned.
- Multi-line items where the arrow is already aligned with the
(new) "expected" alignment, however, will be left alone.
Examples:
* Setting this to
This setting will respect the ignoreNewlines and maxColumnn settings.
Tags
$exact
Whether the alignment should be exact.
public
bool
$exact
= true
Exact in this context means "largest index key + 1 space".
When false, that is seen as the minimum alignment.
Tags
$ignoreNewlines
Whether or not to ignore an array item for the purpose of alignment when a new line is found between the array key and the double arrow.
public
bool
$ignoreNewlines
= true
Tags
$maxColumn
The maximum column on which the double arrow alignment should be set.
public
int
$maxColumn
= 1000
This property allows for limiting the whitespace padding to prevent overly long lines.
If this value is set to, for instance, 60, it will:
- if the expected column < 60, align at the expected column.
- if the expected column >= 60, align at column 60.
- for the outliers, i.e. the array indexes where the end position goes past column 60, it will not align the arrow, the sniff will just make sure there is only one space between the end of the array index and the double arrow.
The column value is regarded as a hard value, i.e. includes indentation, so setting it very low is not a good idea.
Tags
$phpcsFile
The current file being sniffed.
protected
File
$phpcsFile
Tags
$tokens
The list of tokens in the current file being sniffed.
protected
array<string|int, mixed>
$tokens
Tags
$number
Storage for parsed $alignMultilineItems numeric part.
private
string
$number
Stored as a string as the comparison will be done string based.
Tags
$operator
Storage for parsed $alignMultilineItems operator part.
private
string
$operator
Tags
Methods
process()
Set sniff properties and hand off to child class for processing of the token.
public
process(File $phpcsFile, int $stackPtr) : int|void
Parameters
- $phpcsFile : File
-
The file being scanned.
- $stackPtr : int
-
The position of the current token in the stack passed in $tokens.
Tags
Return values
int|void —Integer stack pointer to skip forward or void to continue normal file processing.
process_token()
Processes this test, when one of its tokens is encountered.
public
process_token(int $stackPtr) : int|void
Parameters
- $stackPtr : int
-
The position of the current token in the stack.
Tags
Return values
int|void —Integer stack pointer to skip forward or void to continue normal file processing.
register()
Returns an array of tokens this test wants to listen for.
public
register() : array<string|int, mixed>
Tags
Return values
array<string|int, mixed>process_multi_line_array()
Process a multi-line array.
protected
process_multi_line_array(int $stackPtr, array<string|int, mixed> $items, int $opener, int $closer) : void
Parameters
- $stackPtr : int
-
The position of the current token in the stack.
- $items : array<string|int, mixed>
-
Info array containing information on each array item.
- $opener : int
-
The position of the array opener.
- $closer : int
-
The position of the array closer.
Tags
process_single_line_array()
Process a single-line array.
protected
process_single_line_array(int $stackPtr, array<string|int, mixed> $items, int $opener, int $closer) : int|void
While the WP standard does not allow single line multi-item associative arrays, this sniff should function independently of that.
The WordPress.WhiteSpace.OperatorSpacing sniff already covers checking that
there is a space between the array key and the double arrow, but doesn't
enforce it to be exactly one space for single line arrays.
That is what this method covers.
Parameters
- $stackPtr : int
-
The position of the current token in the stack.
- $items : array<string|int, mixed>
-
Info array containing information on each array item.
- $opener : int
-
The position of the array opener.
- $closer : int
-
The position of the array closer.
Tags
Return values
int|void —Integer stack pointer to skip forward or void to continue normal file processing.
validate_align_multiline_items()
Validate that a valid value has been received for the alignMultilineItems property.
protected
validate_align_multiline_items() : void
This message may be thrown more than once if the property is being changed inline in a file.