Add strict type hints for placeholder arguments in FormattableMarkup and string translation classes

Problem/Motivation

From time to time I'm facing a very straightforward error:

php.ERROR: TypeError: Drupal\Component\Utility\Html::escape(): Argument #1 ($text) must be of type string, null given, called in /var/www/html/web/core/lib/Drupal/Component/Render/FormattableMarkup.php on line 238 in Drupal\Component\Utility\Html::escape() (line 433 of /var/www/html/web/core/lib/Drupal/Component/Utility/Html.php). {"severity_level":3,"exception":"[object] (TypeError(code: 0): Drupal\\Component\\Utility\\Html::escape(): Argument #1 ($text) must be of type string, null given, called in /var/www/html/web/core/lib/Drupal/Component/Render/FormattableMarkup.php on line 238 at /var/www/html/web/core/lib/Drupal/Component/Utility/Html.php:433)"}

This happens because method \Drupal\Component\Utility\Html::escape has strict string type for its argument:

public static function escape(string $text): string {
  return htmlspecialchars($text, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
}

This was done in that issue #3441394: Remove deprecated code in utilities (basically Drupal 11.0+).

The problem is that FormattableMarkup, TranslatableMarkup, PluralTranslatableMarkup and TranslationInterface have very weak PHPDoc type-hints in core for the $arguments parameter, which is just @param array $arguments.

It means, a simple (string) new TranslatableMarkup('@name is cool', ['@name' => NULL]) will end up with an error above. The other problem, which is not related to Html::escape, but still, very heavily related, is that the key for $arguments array can't be an empty string, because in \Drupal\Component\Render\FormattableMarkup::placeholderFormat we have:

foreach ($args as $key => $value) {
  switch ($key[0]) {
    // Other switched for '%', '!', ':'.
    default:
      if (!ctype_alnum($key[0])) {
        // Warn for random placeholders that won't be replaced.
        trigger_error(sprintf('Placeholders must begin with one of the following "@", ":" or "%%", invalid placeholder (%s) with string: "%s"', $key, $string), E_USER_WARNING);
      }
      // No replacement possible therefore we can discard the argument.
      unset($args[$key]);
      break;
  }
}

It means that an empty string is essentially not a valid value for the key either. This is why it should be non-empty-string.

Steps to reproduce

(string) new TranslatableMarkup('@name is cool', ['@name' => NULL])

Proposed resolution

Narrow the $arguments parameter for those classes and the interface to: @param array<non-empty-string, string|\Stringable> $args. This will allows tools such as PHPStan/Psalm detect those issues before it deployed to production.

Remaining tasks

User interface changes

Introduced terminology

API changes

Data model changes

Release notes snippet