`Constants::getNames()`: new method to retrieve constant names from `const` declarations

[rodrigoprimo]

Is your feature request related to a problem?

When multiple constants are declared in a single const statement (e.g., const FOO = 10, BAR = 15;), there is currently no straightforward way to retrieve all the constant names from a T_CONST token.

Without a dedicated method, sniffs that need to check all constant names in a multi-constant declaration must manually walk through the tokens to identify each constant name, which requires additional logic.

Describe the solution you'd like

Add a new Constants::getNames() method that would:

• Accept a $stackPtr pointing to a T_CONST token.
• Work for both class constants and global constants (https://3v4l.org/r0Ldi demonstrates that multi-constant declaration syntax for both class and global constants is supported since PHP 5.3).
• Return an array of all constant names with their corresponding stack pointers.

Example usage

Given the following code:

class Example {
    const FOO = 10, BAR = 15, BAZ = 20;
}

Calling Constants::getNames($phpcsFile, $stackPtr) where $stackPtr points to the T_CONST token would return:

[
    'FOO' => #,
    'BAR' => #,
    'BAZ' => #,
]

And given the following code:

const GLOBAL_A = 1, GLOBAL_B = 2;

Calling Constants::getNames($phpcsFile, $stackPtr) where $stackPtr points again to the T_CONST token would return:

[
    'GLOBAL_A' => #,
    'GLOBAL_B' => #,
]

Additional context

Loosely related to #690.

• I intend to create a pull request to implement this feature.

[jrfnl]

@rodrigoprimo This sounds largely like a duplicate of #690.

As multi-constant declarations are rare, I'd like to understand the real world use-case for a method like this.
When would a sniff need this ?

[rodrigoprimo]

@rodrigoprimo This sounds largely like a duplicate of #690.

The biggest difference that I see between this issue and #690, is that ObjectDeclarations::getDeclaredConstants() only works for class constants while Constants::getNames() would work for both class and global constants.

As multi-constant declarations are rare, I'd like to understand the real world use-case for a method like this.
When would a sniff need this ?

WordPress.NamingConventions.PrefixAllGlobals could benefit from such a method to address WordPress/WordPress-Coding-Standards#2560. This sniff looks for global constants by searching for T_CONST tokens and then ignoring those in an OO construct using Scopes::isOOConstant(). Currently, it does not handle multi-constant declarations and only looks for a single constant name after the T_CONST token. With Constants::getNames(), the sniff could retrieve all constant names from both single and multi-constant declarations, fixing the false negatives described in #2560.

What do you think?

[jrfnl]

I'm thinking that a method like you suggest might actually be the best solution to fix #690 too ;-)

[jrfnl]

Note to self for when I start working on this: this needs to take into account that in recent years lots of new syntaxes are allowed in constant values, like class instantiations, callable declarations etc.