PHPCSUtils

Lists

Utility functions to retrieve information when working with lists.

Tags
since
1.0.0

Table of Contents

getAssignments()  : array
Retrieves information on the assignments made in the specified (long/short) list.
getOpenClose()  : array|false
Find the list opener and closer based on a T_LIST or T_OPEN_SHORT_ARRAY token.
isShortList()  : bool
Determine whether a T_OPEN/CLOSE_SHORT_ARRAY token is a short list() construct.

Methods

getAssignments()

Retrieves information on the assignments made in the specified (long/short) list.

public static getAssignments(File $phpcsFile, int $stackPtr) : array

This method also accepts T_OPEN_SQUARE_BRACKET tokens to allow it to be PHPCS cross-version compatible as the short array tokenizing has been plagued by a number of bugs over time, which affects the short list determination.

The returned array will contain the following basic information for each assignment:

0 => array(
  'raw'                  => string,       // The full content of the variable definition,
                                          // including whitespace and comments.
                                          // This may be an empty string when a list
                                          // item is being skipped.
  'assignment'           => string,       // The content of the assignment part,
                                          // cleaned of comments.
                                          // This may be an empty string for an empty
                                          // list item; it could also be a nested list
                                          // represented as a string.
  'is_empty'             => bool,         // Whether this is an empty list item, i.e.
                                          // the second item in `list($a, , $b)`.
  'is_nested_list'       => bool,         // Whether this is a nested list.
  'variable'             => string|false, // The base variable being assigned to; or
                                          // FALSE in case of a nested list or
                                          // a variable variable.
                                          // I.e. `$a` in `list($a['key'])`.
  'assignment_token'     => int|false,    // The start pointer for the assignment.
                                          // For a nested list, this will be the pointer
                                          // to the `list` keyword or the open square
                                          // bracket in case of a short list.
  'assignment_end_token' => int|false,    // The end pointer for the assignment.
  'assign_by_reference'  => bool,         // Is the variable assigned by reference?
  'reference_token'      => int|false,    // The stack pointer to the reference operator;
                                          // or FALSE when not a reference assignment.
)

Assignments with keys will have the following additional array indexes set:

  'key'                 => string, // The content of the key, cleaned of comments.
  'key_token'           => int,    // The stack pointer to the start of the key.
  'key_end_token'       => int,    // The stack pointer to the end of the key.
  'double_arrow_token'  => int,    // The stack pointer to the double arrow.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The position in the stack of the function token to acquire the parameters for.

Tags
since
1.0.0
since
1.0.0-alpha3

The returned value has been simplified with sensible defaults and always available keys.

throws
RuntimeException

If the specified $stackPtr is not of type T_LIST, T_OPEN_SHORT_ARRAY or T_OPEN_SQUARE_BRACKET.

Return values
array

An array with information on each assignment made, including skipped assignments (empty), or an empty array if no assignments are made at all (fatal error in PHP >= 7.0).

getOpenClose()

Find the list opener and closer based on a T_LIST or T_OPEN_SHORT_ARRAY token.

public static getOpenClose(File $phpcsFile, int $stackPtr[, true|null $isShortList = null ]) : array|false

This method also accepts T_OPEN_SQUARE_BRACKET tokens to allow it to be PHPCS cross-version compatible as the short array tokenizing has been plagued by a number of bugs over time, which affects the short list determination.

Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The position of the T_LIST or T_OPEN_SHORT_ARRAY token in the stack.

$isShortList : true|null = null

Short-circuit the short list check for T_OPEN_SHORT_ARRAY tokens if it isn't necessary. Efficiency tweak for when this has already been established, i.e. when encountering a nested list while walking the tokens in a list. Use with care.

Tags
since
1.0.0
Return values
array|false

An array with the token pointers; or FALSE if this is not a (short) list token or if the opener/closer could not be determined. The format of the array return value is:

array(
  'opener' => integer, // Stack pointer to the list open bracket.
  'closer' => integer, // Stack pointer to the list close bracket.
)

isShortList()

Determine whether a T_OPEN/CLOSE_SHORT_ARRAY token is a short list() construct.

public static isShortList(File $phpcsFile, int $stackPtr) : bool

This method also accepts T_OPEN/CLOSE_SQUARE_BRACKET tokens to allow it to be PHPCS cross-version compatible as the short array tokenizing has been plagued by a number of bugs over time, which affects the short list determination.

Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The position of the short array bracket token.

Tags
since
1.0.0
Return values
bool

TRUE if the token passed is the open/close bracket of a short list. FALSE if the token is a short array bracket or plain square bracket or not one of the accepted tokens.

Search results