DX: Narrow docblock types in Tokenizer

[jrmajor]

No description provided.

[coveralls]

Coverage increased (+0.002%) to 92.889% when pulling b13205c on jrmajor:stan into 76bd49d on FriendsOfPHP:master.

[keradus]

👎🏻 I don't see the value of this change, tbh

[jrmajor]

Static analysis tools interpret CaseAnalysis[] as array<array-key, CaseAnalysis>, which tells you nothing about keys. This change makes it easier to understand what do they actually mean:

• array<string, CaseAnalysis> means that keys are strings and probably are meaningful, maybe case name?
• array<int, CaseAnalysis> means that keys are integers and may mean something, maybe index of T_CASE token?
• list<CaseAnalysis> means that this is just a list, keys are not meaningful,
• CaseAnalysis[] may be any of the above.

Take a look at changes in FunctionsAnalyser. This method also uses Foo[] type, but turns out that in that case keys are actually argument names:

  /**
-  * @return ArgumentAnalysis[]
+  * @return array<string, ArgumentAnalysis>
   */
  public function getFunctionArguments(Tokens $tokens, int $functionIndex): array

[keradus]

pls don't, there is no such type as Tokens::BLOCK_TYPE_*

some sca tools will try to convert it to

-private static function assertFindBlockEnd(int $expectedIndex, string $source, int $type, int $searchIndex): void
+private static function assertFindBlockEnd(int $expectedIndex, string $source, Tokens::BLOCK_TYPE_* $type, int $searchIndex): void

which will obviously fail

[keradus]

Suggested change

	* @param Tokens::BLOCK_TYPE_* $type
	* @param int $type one of Tokens::BLOCK_TYPE_*

[jrmajor]

there is no such type as Tokens::BLOCK_TYPE_*

Surely there's no such native PHP type, but neither there is ArgumentAnalysis[].

As for modern static analysis tools, they understand it — here's an example in PHPStan and Psalm.

some sca tools will try to convert it to

What tools? That would probably mean they're broken; they should validate that the PHPDoc type is a correct PHP type before making such changes. If they don't do that, ArgumentAnalysis[] would also break them.

[jrmajor]

@keradus This is a place where Tokens::BLOCK_TYPE_* type actually helps to find invalid usage of this method.

[julienfalque]

Thank you @jrmajor.