String literal matching specific regex annotation

[janbarasek]

Hello,

Often I want to prepare a package for my colleagues that defines very strict rules about the expectation of what input strings a method argument or property can handle.

If I implement the format validation as an assert, we will only learn about the error at runtime and it may never occur. If there is a native way to define the expected string format, it will be possible to automatically check huge code structures at compiletime.

For example (possible value can be v1.2.3):

function getFirstVersionPart(string $version): int
{
   preg_match('/^v(\d+)/', $version, $parser);

   return (int) $parser[1];
}

This annotation would help PhpStan recognize how to evaluate a regular expression and that all indexes will exist (and I don't need to handle the occurrence of the 1 index).

Thanks.

[ondrejmirtes]

Hi, unless you find a similar feature in a different language like TypeScript or Hacklang, I'm not really interested 😊

Personally I'd pass around objects instead of strings.

[EliW]

Hey @ondrejmirtes I posted something similar to what I'm putting below in the 'wrong thread' ... and moving it here ... since this ticket is still open.
....................
So I'm 100% behind the idea of making value objects and passing those around in 'more complicated' situations ... But I feel like there are enough cases where you just aren't going to make an object ... for a standardized string pattern that you use throughout the database.

And so I think that either a string{regex} or string<regex> or a more simplified string<pattern> type specification could be very useful in PHPstan.

Some very good examples can be simply: GUIDs ... and Hexidecimals strings (hashes, md5, sha1, etc)

If working in an API or database system where you are constantly passing around GUIDs, it would be great to be able to type-hint in PHPstan that X is a guid (and defining the specific GUID pattern that your GUIDs will have). So that phpstan can report/error when someone uses a different string value. Again, same for hashes in a lot of cases.

I think there are other 'solid' use cases as well. Such as US Zip Codes (5 'numbers' but where it has to stay a string, because it can start with 0) ...

And then I think you can start getting into 'adjacently-helpful' uses as well. Such as declaring a string as needing to be a 'valid filesystem' string, or 'valid URL string' ... not unlike how we have 'valid class-string'

Or where you might have an API that has a specific field, or set of fields, that are always 1 character. Yeah you could make a class called 'OneLetterString' ... but in many cases that's overkill, yet it could be useful to have static analysis pointing out if you happen to put '2 characters' into a place expecting a '1 character string'

The rabbit hole can go deeper with stuff like ISO country codes, API error codes that give strings that are '000' to '999', and other such things....

FWIW I don't see this any different than the existing ways we do this on integers:
ie: int<0, 100>

Or how we have some specific one-off things like class-string, numeric-string, lowercase-string, callable-string, etc ...

This would just be a way like that to provide bounds on a string, in a semi-flexible way to make sure that 'something stupid' doesn't happen like someone passing a string with "123" into a hash location that hsould be restricted to something like [0-9A0F]{32}

[ondrejmirtes]

@EliW Sure, please follow phpstan/phpstan#7703.