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 ofT_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 beingT_STRING
, including array return type declarations. - Typed properties were not recognized prior to PHPCS 3.5.0, including the
?
nullability token not being converted toT_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
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
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
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
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
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
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. Iffalse
, will return the matched condition closest to the passed token.
Tags
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.4T_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
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 totrue
. - If the type contains namespace information, it will be cleaned of whitespace
and comments in the
"type"
value.
- The
- 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
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 totrue
orfalse
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.
- If a type hint is specified, the position of the last token in the hint will be
set in a
- 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
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 alwaysfalse
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 totrue
. - 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.
- The
- PHPCS 3.4.0: New
"has_body"
array index.false
if the method has no body (as with abstract and interface methods) ortrue
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
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.
- Now throws a
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
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
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
Return values
bool —TRUE
if the specified token position represents a reference.
FALSE
if the token represents a bitwise operator.