8000 minor #59305 [HttpFoundation] Document thrown exception by parameter … · symfony/symfony@1ea7204 · GitHub
[go: up one dir, main page]
Skip to content

Commit 1ea7204

Browse files
nicolas-grekasnicolas-grekas
committed
minor #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
2 parents cdc1101 + c7764de commit 1ea7204

File tree

2 files changed

+29
-0
lines changed

2 files changed

+29
-0
lines changed

‎src/Symfony/Component/HttpFoundation/InputBag.php

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ final class InputBag extends ParameterBag
2525
* Returns a scalar input value by name.
2626
*
2727
* @param string|int|float|bool|null $default The default value if the input key does not exist
28+
*
29+
* @throws BadRequestException if the input contains a non-scalar value
2830
*/
2931
public function get(string $key, mixed $default = null): string|int|float|bool|null
3032
{
@@ -85,6 +87,8 @@ public function set(string $key, mixed $value): void
8587
* @return ?T
8688
*
8789
* @psalm-return ($default is null ? T|null : T)
90+
*
91+
* @throws BadRequestException if the input cannot be converted to an enum
8892
*/
8993
public function getEnum(string $key, string $class, ?\BackedEnum $default = null): ?\BackedEnum
9094
{
@@ -97,13 +101,19 @@ public function getEnum(string $key, string $class, ?\BackedEnum $default = null
97101

98102
/**
99103
* Returns the parameter value converted to string.
104+
*
105+
* @throws BadRequestException if the input contains a non-scalar value
100106
*/
101107
public function getString(string $key, string $default = ''): string
102108
{
103109
// Shortcuts the parent method because the validation on scalar is already done in get().
104110
return (string) $this->get($key, $default);
105111
}
106112

113+
/**
114+
* @throws BadRequestException if the input value is an array and \FILTER_REQUIRE_ARRAY or \FILTER_FORCE_ARRAY is not set
115+
* @throws BadRequestException if the input value is invalid and \FILTER_NULL_ON_FAILURE is not set
116+
*/
107117
public function filter(string $key, mixed $default = null, int $filter = \FILTER_DEFAULT, mixed $options = []): mixed
108118
{
109119
$value = $this->has($key) ? $this->all()[$key] : $default;

‎src/Symfony/Component/HttpFoundation/ParameterBag.php

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ public function __construct(
3232
* Returns the parameters.
3333
*
3434
* @param string|null $key The name of the parameter to return or null to get them all
35+
*
36+
* @throws BadRequestException if the value is not an array
3537
*/
3638
public function all(?string $key = null): array
3739
{
@@ -98,6 +100,8 @@ public function remove(string $key): void
98100

99101
/**
100102
* Returns the alphabetic characters of the parameter value.
103+
*
104+
* @throws UnexpectedValueException if the value cannot be converted to string
101105
*/
102106
public function getAlpha(string $key, string $default = ''): string
103107
{
@@ -106,6 +110,8 @@ public function getAlpha(string $key, string $default = ''): string
106110

107111
/**
108112
* Returns the alphabetic characters and digits of the parameter value.
113+
*
114+
* @throws UnexpectedValueException if the value cannot be converted to string
109115
*/
110116
public function getAlnum(string $key, string $default = ''): string
111117
{
@@ -114,6 +120,8 @@ public function getAlnum(string $key, string $default = ''): string
114120

115121
/**
116122
* Returns the digits of the parameter value.
123+
*
124+
* @throws UnexpectedValueException if the value cannot be converted to string
117125
*/
118126
public function getDigits(string $key, string $default = ''): string
119127
{
@@ -122,6 +130,8 @@ public function getDigits(string $key, string $default = ''): string
122130

123131
/**
124132
* Returns the parameter as string.
133+
*
134+
* @throws UnexpectedValueException if the value cannot be converted to string
125135
*/
126136
public function getString(string $key, string $default = ''): string
127137
{
@@ -135,6 +145,8 @@ public function getString(string $key, string $default = ''): string
135145

136146
/**
137147
* Returns the parameter value converted to integer.
148+
*
149+
* @throws UnexpectedValueException if the value cannot be converted to integer
138150
*/
139151
public function getInt(string $key, int $default = 0): int
140152
{
@@ -143,6 +155,8 @@ public function getInt(string $key, int $default = 0): int
143155

144156
/**
145157
* Returns the parameter value converted to boolean.
158+
*
159+
* @throws UnexpectedValueException if the value cannot be converted to a boolean
146160
*/
147161
public function getBoolean(string $key, bool $default = false): bool
148162
{
@@ -160,6 +174,8 @@ public function getBoolean(string $key, bool $default = false): bool
160174
* @return ?T
161175
*
162176
* @psalm-return ($default is null ? T|null : T)
177+
*
178+
* @throws UnexpectedValueException if the parameter value cannot be converted to an enum
163179
*/
164180
public function getEnum(string $key, string $class, ?\BackedEnum $default = null): ?\BackedEnum
165181
{
@@ -183,6 +199,9 @@ public function getEnum(string $key, string $class, ?\BackedEnum $default = null
183199
* @param int|array{flags?: int, options?: array} $options Flags from FILTER_* constants
184200
*
185201
* @see https://php.net/filter-var
202+
*
203+
* @throws UnexpectedValueException if the parameter value is a non-stringable object
204+
* @throws UnexpectedValueException if the parameter value is invalid and \FILTER_NULL_ON_FAILURE is not set
186205
*/
187206
public function filter(string $key, mixed $default = null, int $filter = \FILTER_DEFAULT, mixed $options = []): mixed
188207
{

0 commit comments

Comments
 (0)
0