PHPCSUtils 1.0.12

PassedParameters
in package

FinalYes

Utility functions to retrieve information about parameters passed to function calls, class instantiations, array declarations, isset and unset constructs.

Tags
since
1.0.0

Table of Contents

Methods

getParameter()  : array<string, int|string>|false
Get information on a specific parameter passed.
getParameterCount()  : int
Count the number of parameters which have been passed.
getParameterFromStack()  : array<string, int|string>|false
Get information on a specific function call parameter passed.
getParameters()  : array<int|string, array<string, int|string>>
Get information on all parameters passed.
hasParameters()  : bool
Checks if any parameters have been passed.

Methods

getParameter()

Get information on a specific parameter passed.

public static getParameter(File $phpcsFile, int $stackPtr, int $paramOffset[, string|array<string|int, string> $paramNames = [] ]) : array<string, int|string>|false

See PassedParameters::hasParameters() for information on the supported constructs.

Parameters
$phpcsFile : File

The file where this token was found.

$stackPtr : int

The position of function call name, language construct or array open token.

$paramOffset : int

The 1-based index position of the parameter to retrieve.

$paramNames : string|array<string|int, string> = []

Optional. Either the name of the target parameter to retrieve as a string or an array of names for the same target parameter. Only relevant for function calls. An arrays of names is supported to allow for functions for which the parameter names have undergone name changes over time. When specified, the name will take precedence over the offset. For PHP 8 support, it is STRONGLY recommended to always pass both the offset as well as the parameter name when examining function calls.

Tags
see
PassedParameters::getParameterFromStack()

For when the parameter stack of a function call is already retrieved.

since
1.0.0
throws
RuntimeException

If the token passed is not one of the accepted types or doesn't exist.

throws
RuntimeException

If a function call parameter is requested and the $paramName parameter is not passed.

Return values
array<string, int|string>|false —

Array with information on the parameter/array item at the specified offset, or with the specified name. Or FALSE if the specified parameter/array item is not found. See PassedParameters::getParameters() for the format of the returned (single-dimensional) array.

getParameterCount()

Count the number of parameters which have been passed.

public static getParameterCount(File $phpcsFile, int $stackPtr) : int

See PassedParameters::hasParameters() for information on the supported constructs.

Parameters
$phpcsFile : File

The file where this token was found.

$stackPtr : int

The position of function call name, language construct or array open token.

Tags
since
1.0.0
throws
RuntimeException

If the token passed is not one of the accepted types or doesn't exist.

Return values
int

getParameterFromStack()

Get information on a specific function call parameter passed.

public static getParameterFromStack(array<int|string, array<string, int|string>> $parameters, int $paramOffset, string|array<string|int, string> $paramNames) : array<string, int|string>|false

This is an efficiency method to correctly handle positional versus named parameters for function calls when multiple parameters need to be examined.

See PassedParameters::hasParameters() for information on the supported constructs.

Parameters
$parameters : array<int|string, array<string, int|string>>

The output of a previous call to PassedParameters::getParameters().

$paramOffset : int

The 1-based index position of the parameter to retrieve.

$paramNames : string|array<string|int, string>

Either the name of the target parameter to retrieve as a string or an array of names for the same target parameter. An array of names is supported to allow for functions for which the parameter names have undergone name changes over time. The name will take precedence over the offset.

Tags
since
1.0.0
throws
RuntimeException

If the $paramNames parameter is not passed and the requested parameter was not passed as a positional parameter in the function call being examined.

Return values
array<string, int|string>|false —

Array with information on the parameter at the specified offset, or with the specified name. Or FALSE if the specified parameter is not found. See PassedParameters::getParameters() for the format of the returned (single-dimensional) array.

getParameters()

Get information on all parameters passed.

public static getParameters(File $phpcsFile, int $stackPtr[, int $limit = 0 ][, true|null $isShortArray = null ]) : array<int|string, array<string, int|string>>

See PassedParameters::hasParameters() for information on the supported constructs.

Parameters
$phpcsFile : File

The file where this token was found.

$stackPtr : int

The position of function call name, language construct or array open token.

$limit : int = 0

Optional. Limit the parameter retrieval to the first # parameters/array entries. Use with care on function calls, as this can break support for named parameters!

$isShortArray : true|null = null

Optional. Short-circuit the short array check for T_OPEN_SHORT_ARRAY tokens if it isn't necessary. Efficiency tweak for when this has already been established, Use with EXTREME care.

Tags
since
1.0.0
throws
RuntimeException

If the token passed is not one of the accepted types or doesn't exist.

Return values
array<int|string, array<string, int|string>> —

A multi-dimentional array with information on each parameter/array item. The information gathered about each parameter/array item is in the following format:

1 => array(
  'start' => int,    // The stack pointer to the first token in the parameter/array item.
  'end'   => int,    // The stack pointer to the last token in the parameter/array item.
  'raw'   => string, // A string with the contents of all tokens between `start` and `end`.
  'clean' => string, // Same as `raw`, but all comment tokens have been stripped out.
)

If a named parameter is encountered in a function call, the top-level index will not be the parameter position, but the parameter name and the array will include two extra keys:

'parameter_name' => array(
  'name'       => string, // The parameter name (without the colon).
  'name_token' => int,    // The stack pointer to the parameter name token.
  ...
)

The 'start', 'end', 'raw' and 'clean' indexes will always contain just and only information on the parameter value. Note: The array starts at index 1 for positional parameters. The key for named parameters will be the parameter name. If no parameters/array items are found, an empty array will be returned.

hasParameters()

Checks if any parameters have been passed.

public static hasParameters(File $phpcsFile, int $stackPtr[, true|null $isShortArray = null ]) : bool
  • If passed a T_STRING, T_NAME_FULLY_QUALIFIED, T_NAME_RELATIVE, T_NAME_QUALIFIED, or T_VARIABLE stack pointer, it will treat it as a function call. If a token which is not a function call is passed, the behaviour is undetermined.
  • If passed a T_ANON_CLASS stack pointer, it will accept it as a class instantiation.
  • If passed a T_SELF, T_STATIC or T_PARENT stack pointer, it will accept it as a class instantiation function call when used like new self() (with or without parentheses). When these hierarchiecal keywords are not preceded by the new keyword, parentheses will be required for the token to be accepted.
  • If passed a T_ARRAY or T_OPEN_SHORT_ARRAY stack pointer, it will detect whether the array has values or is empty. For purposes of backward-compatibility with older PHPCS versions, T_OPEN_SQUARE_BRACKET tokens will also be accepted and will be checked whether they are in reality a short array opener.
  • If passed a T_ISSET or T_UNSET stack pointer, it will detect whether those language constructs have "parameters".
Parameters
$phpcsFile : File

The file where this token was found.

$stackPtr : int

The position of function call name, language construct or array open token.

$isShortArray : true|null = null

Optional. Short-circuit the short array check for T_OPEN_SHORT_ARRAY tokens if it isn't necessary. Efficiency tweak for when this has already been established, Use with EXTREME care.

Tags
since
1.0.0
throws
RuntimeException

If the token passed is not one of the accepted types or doesn't exist.

Return values
bool 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results