minor symfony#59305 [HttpFoundation] Document thrown exception by parameter and input bag (VincentLanglet)

This PR was submitted for the 6.4 branch but it was squashed and merged into the 7.3 branch instead.

Discussion
----------

[HttpFoundation] Document thrown exception by parameter and input bag

| Q             | A
| ------------- | ---
| Branch?       | 7.3
| Bug fix?      | no
| New feature?  | no
| Deprecations? | no
| Issues        | -
| License       | MIT

This PR documents RuntimeException which might be thrown by ParameterBag and InputBag.
This
- warns the developper that calls like `$request->query->get()` might throw exception
- avoid PHPStan to report useless try/catch when writing
```
try {
     $foo = $payload->getString('browser_language');
} catch (BadRequestException) {}
```

Commits
-------

c7764de [HttpFoundation] Document thrown exception by parameter and input bag

Author: nicolas-grekas

src/Symfony/Component/HttpFoundation/InputBag.php

@@ -25,6 +25,8 @@ final class InputBag extends ParameterBag
      * Returns a scalar input value by name.
      *
      * @param string|int|float|bool|null $default The default value if the input key does not exist
+     *
+     * @throws BadRequestException if the input contains a non-scalar value
      */
     public function get(string $key, mixed $default = null): string|int|float|bool|null
     {
@@ -85,6 +87,8 @@ public function set(string $key, mixed $value): void
      * @return ?T
      *
      * @psalm-return ($default is null ? T|null : T)
+     *
+     * @throws BadRequestException if the input cannot be converted to an enum
      */
     public function getEnum(string $key, string $class, ?\BackedEnum $default = null): ?\BackedEnum
     {
@@ -97,13 +101,19 @@ public function getEnum(string $key, string $class, ?\BackedEnum $default = null
 
     /**
      * Returns the parameter value converted to string.
+     *
+     * @throws BadRequestException if the input contains a non-scalar value
      */
     public function getString(string $key, string $default = ''): string
     {
         // Shortcuts the parent method because the validation on scalar is already done in get().
         return (string) $this->get($key, $default);
     }
 
+    /**
+     * @throws BadRequestException if the input value is an array and \FILTER_REQUIRE_ARRAY or \FILTER_FORCE_ARRAY is not set
+     * @throws BadRequestException if the input value is invalid and \FILTER_NULL_ON_FAILURE is not set
+     */
     public function filter(string $key, mixed $default = null, int $filter = \FILTER_DEFAULT, mixed $options = []): mixed
     {
         $value = $this->has($key) ? $this->all()[$key] : $default;

src/Symfony/Component/HttpFoundation/ParameterBag.php

@@ -32,6 +32,8 @@ public function __construct(
      * Returns the parameters.
      *
      * @param string|null $key The name of the parameter to return or null to get them all
+     *
+     * @throws BadRequestException if the value is not an array
      */
     public function all(?string $key = null): array
     {
@@ -98,6 +100,8 @@ public function remove(string $key): void
 
     /**
      * Returns the alphabetic characters of the parameter value.
+     *
+     * @throws UnexpectedValueException if the value cannot be converted to string
      */
     public function getAlpha(string $key, string $default = ''): string
     {
@@ -106,6 +110,8 @@ public function getAlpha(string $key, string $default = ''): string
 
     /**
      * Returns the alphabetic characters and digits of the parameter value.
+     *
+     * @throws UnexpectedValueException if the value cannot be converted to string
      */
     public function getAlnum(string $key, string $default = ''): string
     {
@@ -114,6 +120,8 @@ public function getAlnum(string $key, string $default = ''): string
 
     /**
      * Returns the digits of the parameter value.
+     *
+     * @throws UnexpectedValueException if the value cannot be converted to string
      */
     public function getDigits(string $key, string $default = ''): string
     {
@@ -122,6 +130,8 @@ public function getDigits(string $key, string $default = ''): string
 
     /**
      * Returns the parameter as string.
+     *
+     * @throws UnexpectedValueException if the value cannot be converted to string
      */
     public function getString(string $key, string $default = ''): string
     {
@@ -135,6 +145,8 @@ public function getString(string $key, string $default = ''): string
 
     /**
      * Returns the parameter value converted to integer.
+     *
+     * @throws UnexpectedValueException if the value cannot be converted to integer
      */
     public function getInt(string $key, int $default = 0): int
     {
@@ -143,6 +155,8 @@ public function getInt(string $key, int $default = 0): int
 
     /**
      * Returns the parameter value converted to boolean.
+     *
+     * @throws UnexpectedValueException if the value cannot be converted to a boolean
      */
     public function getBoolean(string $key, bool $default = false): bool
     {
@@ -160,6 +174,8 @@ public function getBoolean(string $key, bool $default = false): bool
      * @return ?T
      *
      * @psalm-return ($default is null ? T|null : T)
+     *
+     * @throws UnexpectedValueException if the parameter value cannot be converted to an enum
      */
     public function getEnum(string $key, string $class, ?\BackedEnum $default = null): ?\BackedEnum
     {
@@ -183,6 +199,9 @@ public function getEnum(string $key, string $class, ?\BackedEnum $default = null
      * @param int|array{flags?: int, options?: array} $options Flags from FILTER_* constants
      *
      * @see https://php.net/filter-var
+     *
+     * @throws UnexpectedValueException if the parameter value is a non-stringable object
+     * @throws UnexpectedValueException if the parameter value is invalid and \FILTER_NULL_ON_FAILURE is not set
      */
     public function filter(string $key, mixed $default = null, int $filter = \FILTER_DEFAULT, mixed $options = []): mixed
     {