✨ New TypeString utility class

[jrfnl]

... to contain utilities methods for analysing typestrings as retrieved via the getParameters()/getProperties() methods.

Initially, the class comes with the following methods:

• getKeywordTypes(): array to retrieve an array of all currently supported type keywords.
• isKeyword(string $type): bool to determine whether a type is a keyword type.
• normalizeCase(string $type): string to normalize the case of keyword types to lowercase, while leaving the case of OO-based types alone.
• isSingular(string $typeString): bool to determine if a type is a purely singular type.
• isNullable(string $typeString): bool to determine if a type is a nullable type, either by it having the nullable type operator or by including null as part of a union or DNF type.
• isUnion(string $typeString): bool to determine if a type is a union type.
• isIntersection(string $typeString): bool to determine if a type is an intersection type.
• isDNF(string $typeString): bool to determine if a type is an intersection type.
• toArray(string $typeString, bool $normalize = true): array to split a type string to its individual types and optionally normalize the case of the types.
• toArrayUnique(string $typeString, bool $normalize = true): array to split a type string to its unique individual types and optionally normalize the case of the types.
• filterKeywordTypes(array $types): array to filter an array with individual types as found in a type string down to only the keyword types.
• filterOOTypes(array $types): array to filter an array with individual types as found in a type string down to only the OO-name based types.

Notes:

• The methods in this class have limited or no handling for surrounding or internal whitespace as the type strings these methods are intended to be used with do not contain whitespace.
• The behaviour with type strings not retrieved via the getParameters()/getProperties() methods, or non-type strings, is undefined. This includes type strings found in docblocks. Those are not typically supported by the methods in this class.
• The is*() methods will not check if the type string provided is valid, as doing so would inhibit what sniffs can flag. The is*() methods will only look at the form of the type string to determine if it could be valid for a certain type. Use the PHPCSUtils\Utils\NamingConventions::isValidIdentifierName() method if additional validity checks are needed on the individual "types" seen in a type string. And, if needed, use token walking on the tokens of the type to determine whether a type string actually complies with the type rules as set by PHP.

Includes extensive unit tests.

[fredden]

@jrfnl please can you help me understand why this should be a separate method, rather than built-in functionality of toArray()? When would a consumer of this library want to have a list of types which are not unique?

[jrfnl]

When would a consumer of this library want to have a list of types which are not unique?

The most typical case is when a sniff wants to flag all uses of a certain class/interface name. If the name is used twice in the type, like (A&B)|(A&D), it should also be flagged twice.

More of an edge case would be an error prevention sniff flagging non-OO duplicates in a type, like https://3v4l.org/FFjpT, or OO type redundancy, like https://3v4l.org/1heQE.

[jrfnl]

Rebased on top of #598 and added a commit to take advantage of the new exceptions. Moving to draft until #598 has been merged.

[jrfnl]

Rebased without changes, other than squashing the commits.
Marking as ready as #598 has been merged now. Merging once the build passes.