PHPCSUtils

FunctionDeclarations

Utility functions for use when examining function declaration statements.

Tags
since
1.0.0

The FunctionDeclarations::getProperties() and the FunctionDeclarations::getParameters() methods are based on and inspired by respectively the getMethodProperties() and getMethodParameters() methods in the PHPCS native PHP_CodeSniffer\Files\File class. Also see {@see \PHPCSUtils\BackCompat\BCFile}.

Table of Contents

$magicFunctions  : array
A list of all PHP magic functions.
$magicMethods  : array
A list of all PHP magic methods.
$methodsDoubleUnderscore  : array
A list of all PHP native non-magic methods starting with a double underscore.
getArrowFunctionOpenClose()  : array|false
Retrieve the parenthesis opener, parenthesis closer, the scope opener and the scope closer for an arrow function.
getName()  : string|null
Returns the declaration name for a function.
getParameters()  : array
Retrieves the method parameters for the specified function token.
getProperties()  : array
Retrieves the visibility and implementation properties of a method.
isArrowFunction()  : bool
Check if an arbitrary token is the "fn" keyword for a PHP 7.4 arrow function.
isMagicFunction()  : bool
Checks if a given function is a PHP magic function.
isMagicFunctionName()  : bool
Verify if a given function name is the name of a PHP magic function.
isMagicMethod()  : bool
Checks if a given function is a PHP magic method.
isMagicMethodName()  : bool
Verify if a given function name is the name of a PHP magic method.
isPHPDoubleUnderscoreMethod()  : bool
Checks if a given function is a non-magic PHP native double underscore method.
isPHPDoubleUnderscoreMethodName()  : bool
Verify if a given function name is the name of a non-magic PHP native double underscore method.
isSpecialMethod()  : bool
Checks if a given function is a magic method or a PHP native double underscore method.
isSpecialMethodName()  : bool
Verify if a given function name is the name of a magic method or a PHP native double underscore method.

Properties

$magicFunctions

A list of all PHP magic functions.

public static array $magicFunctions = ['__autoload' => 'autoload']

The array keys contain the function names. The values contain the name without the double underscore.

The function names are listed in lowercase as these function names in PHP are case-insensitive and comparisons against this list should therefore always be done in a case-insensitive manner.

Tags
since
1.0.0

$magicMethods

A list of all PHP magic methods.

public static array $magicMethods = [ '__construct' => 'construct', '__destruct' => 'destruct', '__call' => 'call', '__callstatic' => 'callstatic', '__get' => 'get', '__set' => 'set', '__isset' => 'isset', '__unset' => 'unset', '__sleep' => 'sleep', '__wakeup' => 'wakeup', '__tostring' => 'tostring', '__set_state' => 'set_state', '__clone' => 'clone', '__invoke' => 'invoke', '__debuginfo' => 'debuginfo', // PHP >= 5.6. '__serialize' => 'serialize', // PHP >= 7.4. '__unserialize' => 'unserialize', ]

The array keys contain the method names. The values contain the name without the double underscore.

The method names are listed in lowercase as these method names in PHP are case-insensitive and comparisons against this list should therefore always be done in a case-insensitive manner.

Tags
since
1.0.0

$methodsDoubleUnderscore

A list of all PHP native non-magic methods starting with a double underscore.

public static array $methodsDoubleUnderscore = ['__dorequest' => 'SOAPClient', '__getcookies' => 'SOAPClient', '__getfunctions' => 'SOAPClient', '__getlastrequest' => 'SOAPClient', '__getlastrequestheaders' => 'SOAPClient', '__getlastresponse' => 'SOAPClient', '__getlastresponseheaders' => 'SOAPClient', '__gettypes' => 'SOAPClient', '__setcookie' => 'SOAPClient', '__setlocation' => 'SOAPClient', '__setsoapheaders' => 'SOAPClient', '__soapcall' => 'SOAPClient']

These come from PHP modules such as SOAPClient.

The array keys are the method names, the values the name of the PHP class containing the function.

The method names are listed in lowercase as function names in PHP are case-insensitive and comparisons against this list should therefore always be done in a case-insensitive manner.

Tags
since
1.0.0

Methods

getArrowFunctionOpenClose()

Retrieve the parenthesis opener, parenthesis closer, the scope opener and the scope closer for an arrow function.

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

Helper function for cross-version compatibility with both PHP as well as PHPCS. In PHPCS versions prior to PHPCS 3.5.3/3.5.4, the T_FN token is not yet backfilled and does not have parenthesis opener/closer nor scope opener/closer indexes assigned in the $tokens array.

Parameters
$phpcsFile : File

The file where this token was found.

$stackPtr : int

The token to retrieve the openers/closers for. Typically a T_FN or T_STRING token as those are the only two tokens which can be the arrow function keyword.

Tags
see
FunctionDeclarations::isArrowFunction()

Related function.

since
1.0.0
Return values
array|false

An array with the token pointers or FALSE if this is not an arrow function. The format of the return value is:

array(
  'parenthesis_opener' => integer, // Stack pointer to the parenthesis opener.
  'parenthesis_closer' => integer, // Stack pointer to the parenthesis closer.
  'scope_opener'       => integer, // Stack pointer to the scope opener (arrow).
  'scope_closer'       => integer, // Stack pointer to the scope closer.
)

getName()

Returns the declaration name for a function.

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

Alias for the \PHPCSUtils\Utils\ObjectDeclarations::getName() method.

Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The position of the function keyword token.

Tags
see
BCFile::getDeclarationName()

Original function.

see
ObjectDeclarations::getName()

PHPCSUtils native improved version.

since
1.0.0
codeCoverageIgnore
throws
RuntimeException

If the specified token is not of type T_FUNCTION.

Return values
string|null

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

getParameters()

Retrieves the method parameters for the specified function token.

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

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

The returned array will contain the following information for each parameter:

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.

Main differences with the PHPCS version:

  • Defensive coding against incorrect calls to this method.
  • More efficient and more stable checking whether a T_USE token is a closure use.
  • More efficient and more stable looping of the default value.
  • Clearer exception message when a non-closure use token was passed to the function.
  • To allow for backward compatible handling of arrow functions, this method will also accept T_STRING tokens and examine them to check if these are 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
BCFile::getMethodParameters()

Cross-version compatible version of the original.

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 or T_USE, nor an arrow function.

throws
RuntimeException

If a passed T_USE token is not a closure use token.

Return values
array

getProperties()

Retrieves the visibility and implementation properties of a method.

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

Main differences with the PHPCS version:

  • Bugs fixed:
    • Handling of PHPCS annotations.
    • "has_body" index could be set to true for functions without body in the case of parse errors or live coding.
  • Defensive coding against incorrect calls to this method.
  • More efficient checking whether a function has a body.
  • New "return_type_end_token" (int|false) array index.
  • To allow for backward compatible handling of arrow functions, this method will also accept T_STRING tokens and examine them to check if these are 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
BCFile::getMethodProperties()

Cross-version compatible version of the original.

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.

throws
RuntimeException

If the specified position is not a T_FUNCTION or T_CLOSURE token, nor an arrow function.

Return values
array

Array with information about a function declaration. 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.
  'return_type_end_token' => integer,  // The stack pointer to the end 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
);

isArrowFunction()

Check if an arbitrary token is the "fn" keyword for a PHP 7.4 arrow function.

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

Helper function for cross-version compatibility with both PHP as well as PHPCS.

  • PHP 7.4+ will tokenize most tokens with the content "fn" as T_FN, even when it isn't an arrow function.
  • PHPCS < 3.5.3 will tokenize arrow functions keywords as T_STRING.
  • PHPCS 3.5.3/3.5.4 will tokenize the keyword differently depending on which PHP version is used and similar to PHP will tokenize most tokens with the content "fn" as T_FN, even when it's not an arrow function.

    Note: the tokens tokenized by PHPCS 3.5.3 - 3.5.4 as T_FN are not 100% the same as those tokenized by PHP 7.4+ as T_FN.

Either way, the T_FN token is not a reliable search vector for finding or examining arrow functions, at least not until PHPCS 3.5.5. This function solves that and will give reliable results in the same way as this is now solved in PHPCS 3.5.5.

Note: Bugs are still being found and reported about how PHPCS tokenizes the arrow functions. This method will keep up with upstream changes and backport them, in as far possible, to allow for sniffing arrow functions in PHPCS < current.

Parameters
$phpcsFile : File

The file where this token was found.

$stackPtr : int

The token to check. Typically a T_FN or T_STRING token as those are the only two tokens which can be the arrow function keyword.

Tags
see
FunctionDeclarations::getArrowFunctionOpenClose()

Related function.

since
1.0.0
Return values
bool

TRUE if the token is the "fn" keyword for an arrow function. FALSE when it's not or in case of live coding/parse error.

isMagicFunction()

Checks if a given function is a PHP magic function.

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

The file where this token was found.

$stackPtr : int

The T_FUNCTION token to check.

Tags
todo

Add check for the function declaration being namespaced!

see
FunctionDeclaration::$magicFunctions

List of names of magic functions.

see
FunctionDeclaration::isMagicFunctionName()

For when you already know the name of the function and scope checking is done in the sniff.

since
1.0.0
Return values
bool

isMagicFunctionName()

Verify if a given function name is the name of a PHP magic function.

public static isMagicFunctionName(string $name) : bool
Parameters
$name : string

The full function name.

Tags
see
FunctionDeclaration::$magicFunctions

List of names of magic functions.

since
1.0.0
Return values
bool

isMagicMethod()

Checks if a given function is a PHP magic method.

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

The file where this token was found.

$stackPtr : int

The T_FUNCTION token to check.

Tags
see
FunctionDeclaration::$magicMethods

List of names of magic methods.

see
FunctionDeclaration::isMagicMethodName()

For when you already know the name of the method and scope checking is done in the sniff.

since
1.0.0
Return values
bool

isMagicMethodName()

Verify if a given function name is the name of a PHP magic method.

public static isMagicMethodName(string $name) : bool
Parameters
$name : string

The full function name.

Tags
see
FunctionDeclaration::$magicMethods

List of names of magic methods.

since
1.0.0
Return values
bool

isPHPDoubleUnderscoreMethod()

Checks if a given function is a non-magic PHP native double underscore method.

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

The file where this token was found.

$stackPtr : int

The T_FUNCTION token to check.

Tags
see
FunctionDeclaration::$methodsDoubleUnderscore

List of the PHP native non-magic double underscore method names.

see
FunctionDeclaration::isPHPDoubleUnderscoreMethodName()

For when you already know the name of the method and scope checking is done in the sniff.

since
1.0.0
Return values
bool

isPHPDoubleUnderscoreMethodName()

Verify if a given function name is the name of a non-magic PHP native double underscore method.

public static isPHPDoubleUnderscoreMethodName(string $name) : bool
Parameters
$name : string

The full function name.

Tags
see
FunctionDeclaration::$methodsDoubleUnderscore

List of the PHP native non-magic double underscore method names.

since
1.0.0
Return values
bool

isSpecialMethod()

Checks if a given function is a magic method or a PHP native double underscore method.

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

{@internal Not the most efficient way of checking this, but less efficient ways will get less reliable results or introduce a lot of code duplication.}

Parameters
$phpcsFile : File

The file where this token was found.

$stackPtr : int

The T_FUNCTION token to check.

Tags
see
FunctionDeclaration::isSpecialMethodName()

For when you already know the name of the method and scope checking is done in the sniff.

since
1.0.0
Return values
bool

isSpecialMethodName()

Verify if a given function name is the name of a magic method or a PHP native double underscore method.

public static isSpecialMethodName(string $name) : bool
Parameters
$name : string

The full function name.

Tags
since
1.0.0
Return values
bool

Search results