PHPCSUtils

FunctionDeclarations
in package

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

since
1.0.0-alpha4

Dropped support for PHPCS < 3.7.1.

Table of Contents

$magicFunctions  : array<string|int, mixed>
A list of all PHP magic functions.
$magicMethods  : array<string|int, mixed>
A list of all PHP magic methods.
$methodsDoubleUnderscore  : array<string|int, mixed>
A list of all PHP native non-magic methods starting with a double underscore.
getArrowFunctionOpenClose()  : array<string|int, mixed>|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<string|int, mixed>
Retrieves the method parameters for the specified function token.
getProperties()  : array<string|int, mixed>
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<string|int, mixed> $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<string|int, mixed> $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<string|int, mixed> $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<string|int, mixed>|false

Helper function for cross-version compatibility with both PHP as well as PHPCS. As of PHPCS 3.5.6, this function is no longer be needed.

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
deprecated
1.0.0-alpha4

Use the T_FN token constant instead.

Return values
array<string|int, mixed>|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 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
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<string|int, mixed>

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.
  'has_attributes'      => boolean, // Does the parameter have one or more attributes attached ?
  '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 preceded by the nullability
                                    // operator.
  '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.

Parameters declared using PHP 8 constructor property promotion, have these additional array indexes:

  'property_visibility' => string,  // The property visibility as declared.
  'visibility_token'    => integer, // The stack pointer to the visibility modifier token.
  'property_readonly'   => bool,    // TRUE if the readonly keyword was found.
  'readonly_token'      => integer, // The stack pointer to the readonly modifier token.

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.
  • Support for PHP 8.0 identifier name tokens in parameter types, cross-version PHP & PHPCS.
  • Support for the PHP 8.2 true type.
  • The results of this function call are cached during a PHPCS run for faster response times.
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 support for PHP 7.4 arrow functions.

since
1.0.0-alpha4

Added support for PHP 8.0 union types.

since
1.0.0-alpha4

Added support for PHP 8.0 constructor property promotion.

since
1.0.0-alpha4

Added support for PHP 8.0 identifier name tokenization.

since
1.0.0-alpha4

Added support for PHP 8.0 parameter attributes.

since
1.0.0-alpha4

Added support for PHP 8.1 readonly keyword for constructor property promotion.

since
1.0.0-alpha4

Added support for PHP 8.1 intersection types.

since
1.0.0-alpha4

Added support for PHP 8.2 true type.

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<string|int, mixed>

getProperties()

Retrieves the visibility and implementation properties of a method.

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

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.
  • Support for PHP 8.0 identifier name tokens in return types, cross-version PHP & PHPCS.
  • Support for the PHP 8.2 true type.
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 support for PHP 7.4 arrow functions.

since
1.0.0-alpha3

Added support for PHP 8.0 static return type.

since
1.0.0-alpha4

Added support for PHP 8.0 union types.

since
1.0.0-alpha4

Added support for PHP 8.1 intersection types.

since
1.0.0-alpha4

Added support for PHP 8.2 true type.

throws
RuntimeException

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

Return values
array<string|int, mixed>

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 preceded
                                       // by the nullability operator.
  '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. As of PHPCS 3.5.6, this function is no longer be needed.

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
deprecated
1.0.0-alpha4

Use the T_FN token constant instead.

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