## BCFile

BCFile.php : 83

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()

BCFile.php : 1274

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()

BCFile.php : 1474

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()

BCFile.php : 1537

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()

BCFile.php : 1192

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()

BCFile.php : 922

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()

BCFile.php : 1422

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()

BCFile.php : 129

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()

BCFile.php : 755

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()

BCFile.php : 274

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()

BCFile.php : 552

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()

BCFile.php : 1140

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()

BCFile.php : 1390

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()

BCFile.php : 994

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