PHPCSUtils

Numbers

Utility functions for working with integer/float tokens.

PHP 7.4 introduced numeric literal separators which break number tokenization in older PHP versions. PHPCS backfills this since PHPCS 3.5.3/4.

In other words, if an external standard intends to support PHPCS < 3.5.4 and PHP < 7.4, working with number tokens has suddenly become a challenge.

The functions in this class have been put in place to ease that pain and it is strongly recommended to always use these functions when sniffing for and examining the contents of T_LNUMBER or T_DNUMBER tokens.

Tags
link
https://www.php.net/migration74.new-features.php#migration74.new-features.core.numeric-literal-separator

PHP Manual on numeric literal separators.

since
1.0.0

Table of Contents

REGEX_BINARY_INT  = '`^0b[0-1]+$`iD'
Regex to determine whether the contents of an arbitrary string represents a binary integer.
REGEX_DECIMAL_INT  = '`^(?:0|[1-9][0-9]*)$`D'
Regex to determine whether the contents of an arbitrary string represents a decimal integer.
REGEX_FLOAT  = '` ^(?: (?: (?: (?P<LNUM>[0-9]+) | (?P<DNUM>([0-9]*\.(?P>LNUM)|(?P>LNUM)\.[0-9]*)) ) [e][+-]?(?P>LNUM) ) | (?P>DNUM) | (?:0|[1-9][0-9]*) )$ `ixD'
Regex to determine whether the contents of an arbitrary string represents a float.
REGEX_HEX_INT  = '`^0x[0-9A-F]+$`iD'
Regex to determine whether the contents of an arbitrary string represents a hexidecimal integer.
REGEX_HEX_NUMLIT_STRING  = '`^((?<!\.)_[0-9A-F]*)+$`iD'
Regex to determine is a T_STRING following a T_[DL]NUMBER is part of a hexidecimal numeric literal sequence.
REGEX_NUMLIT_STRING  = '`^((?<![\.e])_[0-9][0-9e\.]*)+$`iD'
Regex to determine if a T_STRING following a T_[DL]NUMBER is part of a numeric literal sequence.
REGEX_OCTAL_INT  = '`^0[0-7]+$`D'
Regex to determine whether the contents of an arbitrary string represents an octal integer.
UNSUPPORTED_PHPCS_VERSION  = '3.5.3'
PHPCS versions in which the backfill for PHP 7.4 numeric literal separators is broken.
getCompleteNumber()  : array
Retrieve information about a number token in a cross-version compatible manner.
getDecimalValue()  : string|false
Get the decimal number value of a numeric string.
isBinaryInt()  : bool
Verify whether the contents of an arbitrary string represents a binary integer.
isDecimalInt()  : bool
Verify whether the contents of an arbitrary string represents a decimal integer.
isFloat()  : bool
Verify whether the contents of an arbitrary string represents a floating point number.
isHexidecimalInt()  : bool
Verify whether the contents of an arbitrary string represents a hexidecimal integer.
isOctalInt()  : bool
Verify whether the contents of an arbitrary string represents an octal integer.

Constants

REGEX_BINARY_INT

Regex to determine whether the contents of an arbitrary string represents a binary integer.

public string REGEX_BINARY_INT = '`^0b[0-1]+$`iD'
Tags
since
1.0.0

REGEX_DECIMAL_INT

Regex to determine whether the contents of an arbitrary string represents a decimal integer.

public string REGEX_DECIMAL_INT = '`^(?:0|[1-9][0-9]*)$`D'
Tags
since
1.0.0

REGEX_FLOAT

Regex to determine whether the contents of an arbitrary string represents a float.

public string REGEX_FLOAT = '` ^(?: (?: (?: (?P<LNUM>[0-9]+) | (?P<DNUM>([0-9]*\.(?P>LNUM)|(?P>LNUM)\.[0-9]*)) ) [e][+-]?(?P>LNUM) ) | (?P>DNUM) | (?:0|[1-9][0-9]*) )$ `ixD'
Tags
link
https://www.php.net/language.types.float

PHP Manual on floats

since
1.0.0

REGEX_HEX_INT

Regex to determine whether the contents of an arbitrary string represents a hexidecimal integer.

public string REGEX_HEX_INT = '`^0x[0-9A-F]+$`iD'
Tags
since
1.0.0

REGEX_HEX_NUMLIT_STRING

Regex to determine is a T_STRING following a T_[DL]NUMBER is part of a hexidecimal numeric literal sequence.

public string REGEX_HEX_NUMLIT_STRING = '`^((?<!\.)_[0-9A-F]*)+$`iD'

Cross-version compatibility helper for PHP 7.4 numeric literals with underscore separators.

Tags
since
1.0.0

REGEX_NUMLIT_STRING

Regex to determine if a T_STRING following a T_[DL]NUMBER is part of a numeric literal sequence.

public string REGEX_NUMLIT_STRING = '`^((?<![\.e])_[0-9][0-9e\.]*)+$`iD'

Cross-version compatibility helper for PHP 7.4 numeric literals with underscore separators.

Tags
since
1.0.0

REGEX_OCTAL_INT

Regex to determine whether the contents of an arbitrary string represents an octal integer.

public string REGEX_OCTAL_INT = '`^0[0-7]+$`D'
Tags
since
1.0.0

UNSUPPORTED_PHPCS_VERSION

PHPCS versions in which the backfill for PHP 7.4 numeric literal separators is broken.

public string UNSUPPORTED_PHPCS_VERSION = '3.5.3'
Tags
since
1.0.0
since
1.0.0-alpha2

Changed from a property to a class constant. Changed from an array to a string.

Methods

getCompleteNumber()

Retrieve information about a number token in a cross-version compatible manner.

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

Helper function to deal with numeric literals, potentially with underscore separators.

PHP < 7.4 does not tokenize numeric literals containing underscores correctly. As of PHPCS 3.5.3, PHPCS contains a backfill, but this backfill was buggy in the initial implementation. A fix for this broken backfill is included in PHPCS 3.5.4.

Either way, this function can be used with all PHPCS/PHP combinations and will, if necessary, provide a backfill for PHPCS/PHP combinations where PHP 7.4 numbers with underscore separators are tokenized incorrectly - with the exception of PHPCS 3.5.3 as the buggyness of the original backfill implementation makes it impossible to provide reliable results.

Parameters
$phpcsFile : File

The file being scanned.

$stackPtr : int

The position of a T_LNUMBER or T_DNUMBER token.

Tags
link
https://github.com/squizlabs/PHP_CodeSniffer/issues/2546

PHPCS issue #2546

link
https://github.com/squizlabs/PHP_CodeSniffer/pull/2771

PHPCS PR #2771

since
1.0.0
throws
RuntimeException

If the specified token is not of type T_LNUMBER or T_DNUMBER.

throws
RuntimeException

If this function is called in combination with an unsupported PHPCS version.

Return values
array

An array with information about the number. The format of the array return value is:

array(
  'orig_content' => string, // The (potentially concatenated) original
                            // content of the tokens;
  'content'      => string, // The (potentially concatenated) content,
                            // underscore(s) removed;
  'code'         => int,    // The token code of the number, either
                            // T_LNUMBER or T_DNUMBER.
  'type'         => string, // The token type, either 'T_LNUMBER'
                            // or 'T_DNUMBER'.
  'decimal'      => string, // The decimal value of the number;
  'last_token'   => int,    // The stackPtr to the last token which was
                            // part of the number.
                            // This will be the same as the original
                            // stackPtr if it is not a PHP 7.4 number
                            // with underscores.
)

getDecimalValue()

Get the decimal number value of a numeric string.

public static getDecimalValue(string $string) : string|false

Takes PHP 7.4 numeric literal separators in numbers into account.

Parameters
$string : string

Arbitrary token content string.

Tags
since
1.0.0
Return values
string|false

Decimal number as a string or FALSE if the passed parameter was not a numeric string.

Note: floating point numbers with exponent will not be expanded, but returned as-is.

isBinaryInt()

Verify whether the contents of an arbitrary string represents a binary integer.

public static isBinaryInt(string $string) : bool

Takes PHP 7.4 numeric literal separators in numbers into account.

Parameters
$string : string

Arbitrary string.

Tags
since
1.0.0
Return values
bool

isDecimalInt()

Verify whether the contents of an arbitrary string represents a decimal integer.

public static isDecimalInt(string $string) : bool

Takes PHP 7.4 numeric literal separators in numbers into account.

Parameters
$string : string

Arbitrary string.

Tags
since
1.0.0
Return values
bool

isFloat()

Verify whether the contents of an arbitrary string represents a floating point number.

public static isFloat(string $string) : bool

Takes PHP 7.4 numeric literal separators in numbers into account.

Parameters
$string : string

Arbitrary string.

Tags
since
1.0.0
Return values
bool

isHexidecimalInt()

Verify whether the contents of an arbitrary string represents a hexidecimal integer.

public static isHexidecimalInt(string $string) : bool

Takes PHP 7.4 numeric literal separators in numbers into account.

Parameters
$string : string

Arbitrary string.

Tags
since
1.0.0
Return values
bool

isOctalInt()

Verify whether the contents of an arbitrary string represents an octal integer.

public static isOctalInt(string $string) : bool

Takes PHP 7.4 numeric literal separators in numbers into account.

Parameters
$string : string

Arbitrary string.

Tags
since
1.0.0
Return values
bool

Search results