PHPCSUtils

BCFile

PHPCS native utility functions.

Backport of the latest versions of PHPCS native utility functions to make them available in older PHPCS versions without the bugs and other quirks that the older versions of the native functions had.

Additionally, this class works round the following tokenizer issues for any affected utility functions:

  • Array return type declarations were incorrectly tokenized to T_ARRAY_HINT instead of T_RETURN_TYPE in some circumstances prior to PHPCS 2.8.0.
  • T_NULLABLE was not available prior to PHPCS 2.8.0 and utility functions did not take nullability of types into account.
  • The PHPCS native ignore annotations were not available prior to PHPCS 3.2.0.
  • The way return types were tokenized has changed in PHPCS 3.3.0. Previously a lot of them were tokenized as T_RETURN_HINT. For namespaced classnames this only tokenized the classname, not the whole return type. Now tokenization is "normalized" with most tokens being T_STRING, including array return type declarations.
  • Typed properties were not recognized prior to PHPCS 3.5.0, including the ? nullability token not being converted to T_NULLABLE.
  • Arrow functions were not recognized properly until PHPCS 3.5.3/4.
  • General PHP cross-version incompatibilities.

Most functions in this class will have a related twin-function in the relevant class in the PHPCSUtils\Utils namespace. These will be indicated with @see tags in the docblock of the function.

The PHPCSUtils native twin-functions will often have additional features and/or improved functionality, but will generally be fully compatible with the PHPCS native functions. The differences between the functions here and the twin functions are documented in the docblock of the respective twin-function.

Tags
see
File

Original source of these utility methods.

since
1.0.0

Table of Contents

findEndOfStatement()  : int
Returns the position of the last non-whitespace token in a statement.
findExtendedClassName()  : string|false
Returns the name of the class that the specified class extends.
findImplementedInterfaceNames()  : array|false
Returns the names of the interfaces that the specified class implements.
findStartOfStatement()  : int
Returns the position of the first non-whitespace token in a statement.
getClassProperties()  : array
Returns the implementation properties of a class.
getCondition()  : int|false
Return the position of the condition for the passed token.
getDeclarationName()  : string|null
Returns the declaration names for classes, interfaces, traits, and functions.
getMemberProperties()  : array
Returns the visibility and implementation properties of a class member var.
getMethodParameters()  : array
Returns the method parameters for the specified function token.
getMethodProperties()  : array
Returns the visibility and implementation properties of a method.
getTokensAsString()  : string
Returns the content of the tokens from the specified start position in the token stack for the specified length.
hasCondition()  : bool
Determine if the passed token has a condition of one of the passed types.
isReference()  : bool
Determine if the passed token is a reference operator.

Methods

findEndOfStatement()

Returns the position of the last non-whitespace token in a statement.

public static findEndOfStatement(File $phpcsFile, int $start[, int|string|array $ignore = null ]) : int

PHPCS cross-version compatible version of the `File::findEndOfStatement() method.

Changelog for the PHPCS native function:

  • Introduced in PHPCS 2.1.0.
  • PHPCS 2.6.2: New optional $ignore parameter to selectively ignore stop points.
  • PHPCS 2.7.1: Improved handling of short arrays, PHPCS #1203.
  • PHPCS 3.3.0: Bug fix: end of statement detection when passed a scope opener, PHPCS #1863.
  • PHPCS 3.5.0: Improved handling of group use statements.
  • PHPCS 3.5.3: Added support for PHP 7.4 T_FN arrow functions.
  • PHPCS 3.5.4: Improved support for PHP 7.4 T_FN arrow functions.
  • PHPCS 3.5.5: Improved support for PHP 7.4 T_FN arrow functions, PHPCS #2895.
Parameters
$phpcsFile : File

The file being scanned.

$start : int

The position to start searching from in the token stack.

$ignore : int|string|array = null

Token types that should not be considered stop points.

Tags
see
File::findEndOfStatement()

Original source.

since
1.0.0
since
1.0.0-alpha2

Added BC support for PHP 7.4 arrow functions.

Return values
int

findExtendedClassName()

Returns the name of the class that the specified class extends.

public static findExtendedClassName(File $phpcsFile, int $stackPtr) : string|false

(works for classes, anonymous classes and interfaces)

PHPCS cross-version compatible version of the File::findExtendedClassName() method.

Changelog for the PHPCS native function:

  • Introduced in PHPCS 1.2.0.
  • PHPCS 2.8.0: Now supports anonymous classes.
  • PHPCS 3.1.0: Now supports interfaces extending interfaces (incorrectly, only supporting single interface extension).
  • PHPCS 3.3.2: Fixed bug causing bleed through with nested classes, PHPCS#2127.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The stack position of the class or interface.

Tags
see
File::findExtendedClassName()

Original source.

see
ObjectDeclarations::findExtendedClassName()

PHPCSUtils native improved version.

since
1.0.0
Return values
string|false

The extended class name or FALSE on error or if there is no extended class name.

findImplementedInterfaceNames()

Returns the names of the interfaces that the specified class implements.

public static findImplementedInterfaceNames(File $phpcsFile, int $stackPtr) : array|false

PHPCS cross-version compatible version of the File::findImplementedInterfaceNames() method.

Changelog for the PHPCS native function:

  • Introduced in PHPCS 2.7.0.
  • PHPCS 2.8.0: Now supports anonymous classes.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The stack position of the class.

Tags
see
File::findImplementedInterfaceNames()

Original source.

see
ObjectDeclarations::findImplementedInterfaceNames()

PHPCSUtils native improved version.

since
1.0.0
Return values
array|false

Array with names of the implemented interfaces or FALSE on error or if there are no implemented interface names.

findStartOfStatement()

Returns the position of the first non-whitespace token in a statement.

public static findStartOfStatement(File $phpcsFile, int $start[, int|string|array $ignore = null ]) : int

PHPCS cross-version compatible version of the File::findStartOfStatement() method.

Changelog for the PHPCS native function:

  • Introduced in PHPCS 2.1.0.
  • PHPCS 2.6.2: New optional $ignore parameter to selectively ignore stop points.
  • PHPCS 3.5.5: Added support for PHP 7.4 T_FN arrow functions.
Parameters
$phpcsFile : File

The file being scanned.

$start : int

The position to start searching from in the token stack.

$ignore : int|string|array = null

Token types that should not be considered stop points.

Tags
see
File::findStartOfStatement()

Original source.

since
1.0.0
since
1.0.0-alpha2

Added BC support for PHP 7.4 arrow functions.

Return values
int

getClassProperties()

Returns the implementation properties of a class.

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

The format of the return value is:

array(
  'is_abstract' => false, // TRUE if the abstract keyword was found.
  'is_final'    => false, // TRUE if the final keyword was found.
);

PHPCS cross-version compatible version of the File::getClassProperties() method.

Changelog for the PHPCS native function:

  • Introduced in PHPCS 1.3.0.
  • PHPCS 3.0.0: The Exception thrown changed from a PHP_CodeSniffer_Exception to \PHP_CodeSniffer\Exceptions\TokenizerException.
  • PHPCS 3.5.0: The Exception thrown changed from a \PHP_CodeSniffer\Exceptions\TokenizerException to\PHP_CodeSniffer\Exceptions\RuntimeException.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The position in the stack of the T_CLASS token to acquire the properties for.

Tags
see
File::getClassProperties()

Original source.

see
ObjectDeclarations::getClassProperties()

PHPCSUtils native improved version.

since
1.0.0
throws
RuntimeException

If the specified position is not a T_CLASS token.

Return values
array

getCondition()

Return the position of the condition for the passed token.

public static getCondition(File $phpcsFile, int $stackPtr, int|string $type[, bool $first = true ]) : int|false

PHPCS cross-version compatible version of the File::getCondition() method.

Changelog for the PHPCS native function:

  • Introduced in PHPCS 1.3.0.
  • PHPCS 3.5.4: New $first parameter which allows for the closest matching token to be returned. By default, it continues to return the first matched token found from the top of the file.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The position of the token we are checking.

$type : int|string

The type of token to search for.

$first : bool = true

If true, will return the matched condition furthest away from the passed token. If false, will return the matched condition closest to the passed token.

Tags
see
File::getCondition()

Original source.

see
Conditions::getCondition()

More versatile alternative.

since
1.0.0
since
1.0.0-alpha2

Added support for the PHPCS 3.5.4 $first parameter.

Return values
int|false

Integer stack pointer to the condition or FALSE if the token does not have the condition.

getDeclarationName()

Returns the declaration names for classes, interfaces, traits, and functions.

public static getDeclarationName(File $phpcsFile, int $stackPtr) : string|null

PHPCS cross-version compatible version of the File::getDeclarationName() method.

Changelog for the PHPCS native function:

  • Introduced in PHPCS 0.0.5.
  • PHPCS 2.8.0: Returns null when passed an anonymous class. Previously, the method would throw a "token not of an accepted type" exception.
  • PHPCS 2.9.0: Returns null when passed a PHP closure. Previously, the method would throw a "token not of an accepted type" exception.
  • PHPCS 3.0.0: Added support for ES6 class/method syntax.
  • PHPCS 3.0.0: The Exception thrown changed from a PHP_CodeSniffer_Exception to \PHP_CodeSniffer\Exceptions\RuntimeException.
  • PHPCS 3.5.3: Allow for functions to be called fn for backwards compatibility. Related to PHP 7.4 T_FN arrow functions.
  • PHPCS 3.5.5: Remove arrow function work-around which is no longer needed due to a change in the tokenization of arrow functions.

Note:

  • For ES6 classes in combination with PHPCS 2.x, passing a T_STRING token to this method will be accepted for JS files.
  • Support for JS ES6 method syntax has not been back-filled for PHPCS < 3.0.0. and sniffing JS files is not officially supported by PHPCSUtils.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The position of the declaration token which declared the class, interface, trait, or function.

Tags
see
File::getDeclarationName()

Original source.

see
ObjectDeclarations::getName()

PHPCSUtils native improved version.

since
1.0.0
since
1.0.0-alpha2

Added BC support for PHP 7.4 arrow functions.

throws
RuntimeException

If the specified token is not of type T_FUNCTION, T_CLASS, T_TRAIT, or T_INTERFACE.

Return values
string|null

The name of the class, interface, trait, or function; or NULL if the function or class is anonymous or in case of a parse error/live coding.

getMemberProperties()

Returns the visibility and implementation properties of a class member var.

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

The format of the return value is:

array(
  'scope'           => string,  // Public, private, or protected.
  'scope_specified' => boolean, // TRUE if the scope was explicitly specified.
  'is_static'       => boolean, // TRUE if the static keyword was found.
  'type'            => string,  // The type of the var (empty if no type specified).
  'type_token'      => integer, // The stack pointer to the start of the type
                                // or FALSE if there is no type.
  'type_end_token'  => integer, // The stack pointer to the end of the type
                                // or FALSE if there is no type.
  'nullable_type'   => boolean, // TRUE if the type is nullable.
);

PHPCS cross-version compatible version of the `File::getMemberProperties() method.

Changelog for the PHPCS native function:

  • Introduced in PHPCS 0.0.5.
  • PHPCS 3.0.0: The Exception thrown changed from a PHP_CodeSniffer_Exception to \PHP_CodeSniffer\Exceptions\TokenizerException.
  • PHPCS 3.4.0: Fixed method params being recognized as properties, PHPCS#2214.
  • PHPCS 3.5.0: New "type", "type_token", "type_end_token" and "nullable_type" array indexes.
    • The "type" index contains the type of the member var, or a blank string if not specified.
    • If the type is nullable, "type" will contain the leading ?.
    • If a type is specified, the position of the first token in the type will be set in a "type_token" array index.
    • If a type is specified, the position of the last token in the type will be set in a "type_end_token" array index.
    • If the type is nullable, a "nullable_type" array index will also be set to true.
    • If the type contains namespace information, it will be cleaned of whitespace and comments in the "type" value.
  • PHPCS 3.5.0: The Exception thrown changed from a \PHP_CodeSniffer\Exceptions\TokenizerException to \PHP_CodeSniffer\Exceptions\RuntimeException.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The position in the stack of the T_VARIABLE token to acquire the properties for.

Tags
see
File::getMemberProperties()

Original source.

see
Variables::getMemberProperties()

PHPCSUtils native improved version.

since
1.0.0
throws
RuntimeException

If the specified position is not a T_VARIABLE token, or if the position is not a class member variable.

Return values
array

getMethodParameters()

Returns the method parameters for the specified function token.

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

Also supports passing in a T_USE token for a closure use group.

Each parameter is in the following format:

0 => array(
  'name'                => '$var',  // The variable name.
  'token'               => integer, // The stack pointer to the variable name.
  'content'             => string,  // The full content of the variable definition.
  'pass_by_reference'   => boolean, // Is the variable passed by reference?
  'reference_token'     => integer, // The stack pointer to the reference operator
                                    // or FALSE if the param is not passed by reference.
  'variable_length'     => boolean, // Is the param of variable length through use of `...` ?
  'variadic_token'      => integer, // The stack pointer to the ... operator
                                    // or FALSE if the param is not variable length.
  'type_hint'           => string,  // The type hint for the variable.
  'type_hint_token'     => integer, // The stack pointer to the start of the type hint
                                    // or FALSE if there is no type hint.
  'type_hint_end_token' => integer, // The stack pointer to the end of the type hint
                                    // or FALSE if there is no type hint.
  'nullable_type'       => boolean, // TRUE if the var type is nullable.
  'comma_token'         => integer, // The stack pointer to the comma after the param
                                    // or FALSE if this is the last param.
)

Parameters with default values have the following additional array indexes:

  'default'             => string,  // The full content of the default value.
  'default_token'       => integer, // The stack pointer to the start of the default value.
  'default_equal_token' => integer, // The stack pointer to the equals sign.

PHPCS cross-version compatible version of the File::getMethodParameters() method.

Changelog for the PHPCS native function:

  • Introduced in PHPCS 0.0.5.
  • PHPCS 2.8.0: Now recognises self as a valid type declaration.
  • PHPCS 2.8.0: The return array now contains a new "token" index containing the stack pointer to the variable.
  • PHPCS 2.8.0: The return array now contains a new "content" index containing the raw content of the param definition.
  • PHPCS 2.8.0: Added support for nullable types. The return array now contains a new "nullable_type" index set to true or false for each method parameter.
  • PHPCS 2.8.0: Added support for closures.
  • PHPCS 3.0.0: The Exception thrown changed from a PHP_CodeSniffer_Exception to \PHP_CodeSniffer\Exceptions\TokenizerException.
  • PHPCS 3.3.0: The return array now contains a new "type_hint_token" array index. Provides the position in the token stack of the first token in the type declaration.
  • PHPCS 3.3.1: Fixed incompatibility with PHP 7.3.
  • PHPCS 3.5.0: The Exception thrown changed from a \PHP_CodeSniffer\Exceptions\TokenizerException to \PHP_CodeSniffer\Exceptions\RuntimeException.
  • PHPCS 3.5.0: Added support for closure USE groups.
  • PHPCS 3.5.0: The return array now contains yet more more information.
    • If a type hint is specified, the position of the last token in the hint will be set in a "type_hint_end_token" array index.
    • If a default is specified, the position of the first token in the default value will be set in a "default_token" array index.
    • If a default is specified, the position of the equals sign will be set in a "default_equal_token" array index.
    • If the param is not the last, the position of the comma will be set in a "comma_token" array index.
    • If the param is passed by reference, the position of the reference operator will be set in a "reference_token" array index.
    • If the param is variable length, the position of the variadic operator will be set in a "variadic_token" array index.
  • PHPCS 3.5.3: Fixed a bug where the "type_hint_end_token" array index for a type hinted parameter would bleed through to the next (non-type hinted) parameter.
  • PHPCS 3.5.3: Added support for PHP 7.4 T_FN arrow functions.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

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

Tags
see
File::getMethodParameters()

Original source.

see
FunctionDeclarations::getParameters()

PHPCSUtils native improved version.

since
1.0.0
since
1.0.0-alpha2

Added BC support for PHP 7.4 arrow functions.

throws
RuntimeException

If the specified $stackPtr is not of type T_FUNCTION, T_CLOSURE, T_USE, or T_FN.

Return values
array

getMethodProperties()

Returns the visibility and implementation properties of a method.

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

The format of the return value is:

array(
  'scope'                => 'public', // Public, private, or protected
  'scope_specified'      => true,     // TRUE if the scope keyword was found.
  'return_type'          => '',       // The return type of the method.
  'return_type_token'    => integer,  // The stack pointer to the start of the return type
                                      // or FALSE if there is no return type.
  'nullable_return_type' => false,    // TRUE if the return type is nullable.
  'is_abstract'          => false,    // TRUE if the abstract keyword was found.
  'is_final'             => false,    // TRUE if the final keyword was found.
  'is_static'            => false,    // TRUE if the static keyword was found.
  'has_body'             => false,    // TRUE if the method has a body
);

PHPCS cross-version compatible version of the File::getMethodProperties() method.

Changelog for the PHPCS native function:

  • Introduced in PHPCS 0.0.5.
  • PHPCS 3.0.0: Removed the "is_closure" array index which was always false anyway.
  • PHPCS 3.0.0: The Exception thrown changed from a PHP_CodeSniffer_Exception to \PHP_CodeSniffer\Exceptions\TokenizerException.
  • PHPCS 3.3.0: New "return_type", "return_type_token" and "nullable_return_type" array indexes.
    • The "return_type" index contains the return type of the function or closer, or a blank string if not specified.
    • If the return type is nullable, the return type will contain the leading ?.
    • A "nullable_return_type" array index in the return value will also be set to true.
    • If the return type contains namespace information, it will be cleaned of whitespace and comments.
    • To access the original return value string, use the main tokens array.
  • PHPCS 3.4.0: New "has_body" array index. false if the method has no body (as with abstract and interface methods) or true otherwise.
  • PHPCS 3.5.0: The Exception thrown changed from a \PHP_CodeSniffer\Exceptions\TokenizerException to \PHP_CodeSniffer\Exceptions\RuntimeException.
  • PHPCS 3.5.3: Added support for PHP 7.4 T_FN arrow functions.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

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

Tags
see
File::getMethodProperties()

Original source.

see
FunctionDeclarations::getProperties()

PHPCSUtils native improved version.

since
1.0.0
since
1.0.0-alpha2

Added BC support for PHP 7.4 arrow functions.

since
1.0.0-alpha3

Added support for PHP 8.0 static return type (expected in future PHPCS release).

throws
RuntimeException

If the specified position is not a T_FUNCTION, T_CLOSURE, or T_FN token.

Return values
array

getTokensAsString()

Returns the content of the tokens from the specified start position in the token stack for the specified length.

public static getTokensAsString(File $phpcsFile, int $start, int $length[, bool $origContent = false ]) : string

PHPCS cross-version compatible version of the File::getTokensAsString() method.

Changelog for the PHPCS native function:

  • Introduced in PHPCS 0.0.5.
  • PHPCS 3.3.0: New $origContent parameter to optionally return original (non tab-replaced) content.
  • PHPCS 3.4.0:
    • Now throws a RuntimeException if the $start param is invalid. This stops an infinite loop when the function is passed invalid data.
    • If the $length param is invalid, an empty string will be returned.
Parameters
$phpcsFile : File

The file being scanned.

$start : int

The position to start from in the token stack.

$length : int

The length of tokens to traverse from the start pos.

$origContent : bool = false

Whether the original content or the tab replaced content should be used.

Tags
see
File::getTokensAsString()

Original source.

see
GetTokensAsString

Related set of functions.

since
1.0.0
throws
RuntimeException

If the specified start position does not exist.

Return values
string

The token contents.

hasCondition()

Determine if the passed token has a condition of one of the passed types.

public static hasCondition(File $phpcsFile, int $stackPtr, int|string|array $types) : bool

PHPCS cross-version compatible version of the File::hasCondition() method.

Changelog for the PHPCS native function:

  • Introduced in PHPCS 0.0.5.
  • This method has received no significant code updates since PHPCS 2.6.0.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The position of the token we are checking.

$types : int|string|array

The type(s) of tokens to search for.

Tags
see
File::hasCondition()

Original source.

see
Conditions::hasCondition()

PHPCSUtils native alternative.

since
1.0.0
Return values
bool

isReference()

Determine if the passed token is a reference operator.

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

PHPCS cross-version compatible version of the File::isReference() method.

Changelog for the PHPCS native function:

  • Introduced in PHPCS 0.0.5.
  • PHPCS 3.1.1: Bug fix: misidentification of reference vs bitwise operator, PHPCS#1604/#1609.
    • An array assignment of a calculated value with a bitwise and operator in it, was being misidentified as a reference.
    • A calculated default value for a function parameter with a bitwise and operator in it, was being misidentified as a reference.
    • New by reference was not recognized as a reference.
    • References to class properties with self::, parent::, static::, namespace\ClassName::, classname:: were not recognized as references.
  • PHPCS 3.5.3: Added support for PHP 7.4 T_FN arrow functions returning by reference.
  • PHPCS 3.5.6: Bug fix: the reference operator for closures declared to return by reference was not recognized as a reference. PHPCS#2977.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The position of the T_BITWISE_AND token.

Tags
see
File::isReference()

Original source.

see
Operators::isReference()

PHPCSUtils native improved version.

since
1.0.0
since
1.0.0-alpha2

Added BC support for PHP 7.4 arrow functions.

Return values
bool

TRUE if the specified token position represents a reference. FALSE if the token represents a bitwise operator.

Search results