Documentation

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.
  • 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.

Table of Contents

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

Methods

getDeclarationName()

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

public static getDeclarationName( $phpcsFile : File , $stackPtr : int ) : 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. Note: support for JS ES6 method syntax has not been back-filled for PHPCS < 3.0.0.

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

Original source.

see

PHPCSUtils native improved version.

since
since

Added BC support for PHP 7.4 arrow functions.

throws

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.

getMethodParameters()

Returns the method parameters for the specified function token.

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

Also supports passing in a 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 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

Original source.

see

PHPCSUtils native improved version.

since
since

Added BC support for PHP 7.4 arrow functions.

throws

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( $phpcsFile : File , $stackPtr : int ) : 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 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

Original source.

see

PHPCSUtils native improved version.

since
since

Added BC support for PHP 7.4 arrow functions.

throws

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

Return values
array

getMemberProperties()

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

public static getMemberProperties( $phpcsFile : File , $stackPtr : int ) : 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 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

Original source.

see

PHPCSUtils native improved version.

since
throws

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

Return values
array

getClassProperties()

Returns the implementation properties of a class.

public static getClassProperties( $phpcsFile : File , $stackPtr : int ) : 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 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

Original source.

see

PHPCSUtils native improved version.

since
throws

If the specified position is not a T_CLASS token.

Return values
array

isReference()

Determine if the passed token is a reference operator.

public static isReference( $phpcsFile : File , $stackPtr : int ) : 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.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The position of the T_BITWISE_AND token.

Tags
see

Original source.

see

PHPCSUtils native improved version.

since
since

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.

getTokensAsString()

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

public static getTokensAsString( $phpcsFile : File , $start : int , $length : int [, $origContent : bool = 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

Original source.

see

Related set of functions.

since
throws

If the specified start position does not exist.

Return values
string —

The token contents.

findStartOfStatement()

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

public static findStartOfStatement( $phpcsFile : File , $start : int [, $ignore : int|string|array = 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

Original source.

since
since

Added BC support for PHP 7.4 arrow functions.

Return values
int

findEndOfStatement()

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

public static findEndOfStatement( $phpcsFile : File , $start : int [, $ignore : int|string|array = 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.
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

Original source.

since
since

Added BC support for PHP 7.4 arrow functions.

Return values
int

hasCondition()

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

public static hasCondition( $phpcsFile : File , $stackPtr : int , $types : int|string|array ) : 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

Original source.

see

PHPCSUtils native alternative.

since
Return values
bool

getCondition()

Return the position of the condition for the passed token.

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

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

Original source.

see

More versatile alternative.

since
since

Added support for the PHPCS 3.5.4 $first parameter.

Return values
int|bool —

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

findExtendedClassName()

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

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

(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

Original source.

see

PHPCSUtils native improved version.

since
Return values
string|bool —

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( $phpcsFile : File , $stackPtr : int ) : array|bool

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

Original source.

see

PHPCSUtils native improved version.

since
Return values
array|bool —

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

Search results