PHPCSUtils 1.1.0

ObjectDeclarations
in package

FinalYes

Utility functions for use when examining object declaration statements.

Tags
since
1.0.0

The ObjectDeclarations::get(Declaration)Name(), ObjectDeclarations::getClassProperties(), ObjectDeclarations::findExtendedClassName() and ObjectDeclarations::findImplementedInterfaceNames() methods are based on and inspired by the methods of the same name in the PHPCS native PHP_CodeSniffer\Files\File` class. Also see BCFile.

Table of Contents

Methods

findExtendedClassName()  : string|false
Retrieves the name of the class that the specified class extends.
findExtendedInterfaceNames()  : array<string|int, string>|false
Retrieves the names of the interfaces that the specified interface extends.
findImplementedInterfaceNames()  : array<string|int, string>|false
Retrieves the names of the interfaces that the specified class or enum implements.
getClassProperties()  : array<string, int|bool>
Retrieves the implementation properties of a class.
getDeclaredConstants()  : array<string, int>
Retrieve all constants declared in an OO structure.
getDeclaredEnumCases()  : array<string, int>
Retrieve all cases declared in an enum.
getDeclaredMethods()  : array<string, int>
Retrieve all methods declared in an OO structure.
getDeclaredProperties()  : array<string, int>
Retrieve all properties declared in an OO structure.
getName()  : string|null
Retrieves the declaration name for classes, interfaces, traits, enums and functions.

Methods

findExtendedClassName()

Retrieves 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, though it is strongly recommended to use the ObjectDeclarations::findExtendedInterfaceNames() method to examine interfaces instead. Interfaces can extend multiple parent interfaces, and that use-case is not handled by this method.

Main differences with the PHPCS version:

  • Bugs fixed:
    • Handling of PHPCS annotations.
    • Handling of comments.
  • Improved handling of parse errors.
  • The returned name will be clean of superfluous whitespace and/or comments.
  • Support for PHP 8.0 tokenization of identifier/namespaced names, cross-version PHP & PHPCS.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The stack position of the class or interface.

Tags
see
File::findExtendedClassName()

Original source.

see
BCFile::findExtendedClassName()

Cross-version compatible version of the original.

see
ObjectDeclarations::findExtendedInterfaceNames()

Similar method for extended interfaces.

since
1.0.0
Return values
string|false

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

findExtendedInterfaceNames()

Retrieves the names of the interfaces that the specified interface extends.

public static findExtendedInterfaceNames(File $phpcsFile, int $stackPtr) : array<string|int, string>|false
Parameters
$phpcsFile : File

The file where this token was found.

$stackPtr : int

The stack position of the interface keyword.

Tags
see
ObjectDeclarations::findExtendedClassName()

Similar method for extended classes.

since
1.0.0
Return values
array<string|int, string>|false

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

findImplementedInterfaceNames()

Retrieves the names of the interfaces that the specified class or enum implements.

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

Main differences with the PHPCS version:

  • Bugs fixed:
    • Handling of PHPCS annotations.
    • Handling of comments.
  • Improved handling of parse errors.
  • The returned name(s) will be clean of superfluous whitespace and/or comments.
  • Support for PHP 8.0 tokenization of identifier/namespaced names, cross-version PHP & PHPCS.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The stack position of the class or enum token.

Tags
see
File::findImplementedInterfaceNames()

Original source.

see
BCFile::findImplementedInterfaceNames()

Cross-version compatible version of the original.

since
1.0.0
Return values
array<string|int, string>|false

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

getClassProperties()

Retrieves the implementation properties of a class.

public static getClassProperties(File $phpcsFile, int $stackPtr) : array<string, int|bool>

Main differences with the PHPCS version:

  • Bugs fixed:
    • Handling of PHPCS annotations.
    • Handling of unorthodox docblock placement.
  • Defensive coding against incorrect calls to this method.
  • Additional 'abstract_token', 'final_token', and 'readonly_token' indexes in the return array.
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
BCFile::getClassProperties()

Cross-version compatible version of the original.

since
1.0.0
throws
TypeError

If the $stackPtr parameter is not an integer.

throws
OutOfBoundsStackPtr

If the token passed does not exist in the $phpcsFile.

throws
UnexpectedTokenType

If the token passed is not a T_CLASS token.

Return values
array<string, int|bool>

Array with implementation properties of a class. The format of the return value is:

array(
  'is_abstract'    => bool,      // TRUE if the abstract keyword was found.
  'abstract_token' => int|false, // The stack pointer to the `abstract` keyword or
                                 // FALSE if the abstract keyword was not found.
  'is_final'       => bool,      // TRUE if the final keyword was found.
  'final_token'    => int|false, // The stack pointer to the `final` keyword or
                                 // FALSE if the abstract keyword was not found.
  'is_readonly'    => bool,      // TRUE if the readonly keyword was found.
  'readonly_token' => int|false, // The stack pointer to the `readonly` keyword or
                                 // FALSE if the abstract keyword was not found.
);

getDeclaredConstants()

Retrieve all constants declared in an OO structure.

public static getDeclaredConstants(File $phpcsFile, int $stackPtr) : array<string, int>
Parameters
$phpcsFile : File

The file where this token was found.

$stackPtr : int

The stack position of the OO keyword.

Tags
since
1.1.0
throws
TypeError

If the $stackPtr parameter is not an integer.

throws
OutOfBoundsStackPtr

If the token passed does not exist in the $phpcsFile.

throws
UnexpectedTokenType

If the token passed is not an OO keyword token.

Return values
array<string, int>

Array with names of the found constants as keys and the stack pointers to the T_CONST token for each constant as values. If no constants are found or a parse error is encountered, an empty array is returned.

getDeclaredEnumCases()

Retrieve all cases declared in an enum.

public static getDeclaredEnumCases(File $phpcsFile, int $stackPtr) : array<string, int>
Parameters
$phpcsFile : File

The file where this token was found.

$stackPtr : int

The stack position of the OO keyword.

Tags
since
1.1.0
throws
TypeError

If the $stackPtr parameter is not an integer.

throws
OutOfBoundsStackPtr

If the token passed does not exist in the $phpcsFile.

throws
UnexpectedTokenType

If the token passed is not a T_ENUM token.

Return values
array<string, int>

Array with names of the found cases as keys and the stack pointers to the T_ENUM_CASE token for each case as values. If no cases are found or a parse error is encountered, an empty array is returned.

getDeclaredMethods()

Retrieve all methods declared in an OO structure.

public static getDeclaredMethods(File $phpcsFile, int $stackPtr) : array<string, int>
Parameters
$phpcsFile : File

The file where this token was found.

$stackPtr : int

The stack pointer to the OO keyword.

Tags
since
1.1.0
throws
TypeError

If the $stackPtr parameter is not an integer.

throws
OutOfBoundsStackPtr

If the token passed does not exist in the $phpcsFile.

throws
UnexpectedTokenType

If the token passed is not an OO keyword token.

Return values
array<string, int>

Array with names of the found methods as keys and the stack pointers to the T_FUNCTION keyword for each method as values. If no methods are found or a parse error is encountered, an empty array is returned.

getDeclaredProperties()

Retrieve all properties declared in an OO structure.

public static getDeclaredProperties(File $phpcsFile, int $stackPtr) : array<string, int>

Notes:

  • Properties declared via PHP 8.0+ contructor property promotion will be included in the return value. However, keep in mind that passing the stack pointer of such a property to the Variables::getMemberProperties() method is not supported.
  • Interfaces and enums cannot contain properties. This method does not take this into account to allow sniffs to flag this kind of incorrect PHP code.
Parameters
$phpcsFile : File

The file where this token was found.

$stackPtr : int

The stack position of the OO keyword.

Tags
since
1.1.0
throws
TypeError

If the $stackPtr parameter is not an integer.

throws
OutOfBoundsStackPtr

If the token passed does not exist in the $phpcsFile.

throws
UnexpectedTokenType

If the token passed is not an OO keyword token.

Return values
array<string, int>

Array with names of the found properties as keys and the stack pointers to the T_VARIABLE token for each property as values. If no properties are found or a parse error is encountered, an empty array is returned.

getName()

Retrieves the declaration name for classes, interfaces, traits, enums and functions.

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

Main differences with the PHPCS version:

  • Defensive coding against incorrect calls to this method.
  • Improved handling of invalid names, like names starting with a number. This allows sniffs to report on invalid names instead of ignoring them.
  • Bug fix: improved handling of parse errors. Using the original method, a parse error due to an invalid name could cause the method to return the name of the next construct, a partial name and/or the name of a class being extended/interface being implemented. Using this version of the utility method, either the complete name (invalid or not) will be returned or null in case of no name (parse error).
  • The PHPCS 4.0 change to no longer accept tokens for anonymous structures (T_CLOSURE/T_ANON_CLASS) has not been applied to this method (yet). This will change in PHPCSUtils 2.0.
  • The PHPCS 4.0 change to normalize the return type to string and no longer return null has not been applied to this method (yet). This will change in PHPCSUtils 2.0.
Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

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

Tags
see
File::getDeclarationName()

Original source.

see
BCFile::getDeclarationName()

Cross-version compatible version of the original.

since
1.0.0
throws
TypeError

If the $stackPtr parameter is not an integer.

throws
UnexpectedTokenType

If the token passed is not a T_FUNCTION, T_CLASS, T_ANON_CLASS, T_CLOSURE, T_TRAIT, T_ENUM or T_INTERFACE token.

Return values
string|null

The name of the class, interface, trait, enum, or function; or NULL if the passed token doesn't exist, the function or class is anonymous or in case of a parse error/live coding.


        
On this page

Search results