Improve documentation of lowercase-string (and similar) types

[uuf6429]

I've been working on something that require validating lowercase-string values as defined in psalm/phpdoc/phpstan, and I thought about using a negated unicode category, which would normally make sense: /^[^\p{Lu}]*$/. As expected, this works well with (uppercase) characters like umlauts.

However, I found that psalm and phpstan actually allowed uppercase umlauts (interestingly, it seems that phpstan recognizes lowercase-string, but doesn't validate it - although to be fair, it doesn't seem documented).

Anyway, digging into psalm, I found the documentation for this type and the PR it was created in:
#3223
I also found the code where this is handled, and it seems to be using strtolower, which explains the behaviour.

I don't know enough about this feature to tell if that is intentional or not, but the documentation is at this point a bit lacking. It doesn't say if:

1. non-ascii characters are checked (e.g. umlauts)
2. if symbols/other characters are allowed
3. i.e. if this is a "lowercase characters only" type or if it is a "any character except uppercase" type (seems to be the 2nd one)

[psalm-github-bot]

I found these snippets:

https://psalm.dev/r/64cf69a1cd

<?php

/**
 * @return lowercase-string
 */
function testUmlaut() {
    return 'h$§Üüi';
}

/**
 * @return lowercase-string
 */
function testAscii() {
    return 'h$§Uui';
}

Psalm output (using commit 16b24bd):

ERROR: InvalidReturnStatement - 14:12 - The inferred type ''h$§Uui'' does not match the declared return type 'lowercase-string' for testAscii

ERROR: InvalidReturnType - 11:12 - The declared return type 'lowercase-string' for testAscii is incorrect, got ''h$§Uui''