ā Input parameter validation
docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
en/docs/api/json-rpc-bundle/add_rpc_service/assertions.md
new file +134
ā0
1
+
## Summary
2
+
3
+
::::::block class="floatinginfobox"
4
+
:::::columns border="1" zebra="1"
5
+
::::row
6
+
:::col width="40%"
7
+
**Classname**
8
+
:::
9
+
10
+
:::col
11
+
`Assertions`
12
+
:::
13
+
::::
14
+
15
+
::::row
16
+
:::col width="40%"
17
+
**Namespace**
18
+
:::
19
+
20
+
:::col
21
+
`Ufo\RpcObject\RPC`
22
+
:::
23
+
::::
24
+
25
+
::::row
26
+
:::col width="40%"
27
+
**Target**
28
+
:::
29
+
30
+
:::col
31
+
`parameter`
32
+
:::
33
+
::::
34
+
:::::
35
+
36
+
:::::columns border="1" zebra="1"
37
+
::::row
38
+
:::col align="center"
39
+
Constructor
40
+
:::
41
+
::::
42
+
43
+
::::row
44
+
:::col
45
+
```php
46
+
use Symfony\Component\Validator\Constraint;
47
+
48
+
/**
49
+
* Assertions constructor.
50
+
*
51
+
* @param Constraint[] $assertions
52
+
* @param string $constructorArgs
53
+
*/
54
+
public function __construct(
55
+
array $assertions,
56
+
public string $constructorArgs = ''
57
+
)
58
+
{
59
+
// ...
60
+
}
61
+
```
62
+
:::
63
+
::::
64
+
:::::
65
+
::::::
66
+
67
+
# Input parameter validation
68
+
69
+
Instead of checking whether the parameters passed to your API method meet the business logic requirements, you can use the powerful [Symfony Validation](https://symfony.com/doc/current/validation.html) mechanism: you specify the requirements for each parameter, and the RPC API Server validates the input itself and, if it does not match, returns an error to the client (see [error handling](/docs/api/json-rpc-bundle/error_handling) for details).
70
+
71
+
To use this feature, add the `#[RPC\Assertions]` attribute to the parameter you want to validate. It is a container-adapter that passes your expectations about the parameter's content to the RPC server.
72
+
73
+
`RPC\Assertions` accepts any class that extends Symfony Constraint, including your own implementations. [List of constraints already available in Symfony](https://symfony.com/doc/current/validation.html#supported-constraints).
74
+
75
+
```php
76
+
namespace App\Api\Procedures;
77
+
78
+
use Symfony\Component\Validator\Constraints as Assert;
79
+
use Ufo\JsonRpcBundle\ApiMethod\Interfaces\IRpcService;
80
+
use Ufo\RpcObject\RPC;
81
+
82
+
class ExampleApi implements IRpcService
83
+
{
84
+
public function sendEmail(
85
+
#[RPC\Assertions([
86
+
new Assert\Email(),
87
+
])]
88
+
string $email,
89
+
#[RPC\Assertions([
90
+
new Assert\NotBlank(),
91
+
new Assert\Length(max: 100),
92
+
])]
93
+
string $subject,
94
+
#[RPC\Assertions([
95
+
new Assert\NotBlank(),
96
+
new Assert\Length(min: 10),
97
+
])]
98
+
string $text
99
+
): bool
100
+
{
101
+
// some logic send email
102
+
return true;
103
+
}
104
+
}
105
+
```
106
+
107
+
## Validation error
108
+
109
+
All violations across all parameters are returned as a single `-32602` error (`ConstraintsImposedException`). Messages for each parameter are in `error.data`. Missing required parameters, parameters of the wrong type and values from which a DTO could not be created are returned the same way (since version 10.1).
110
+
111
+
```json
112
+
{
113
+
"jsonrpc": "2.0",
114
+
"id": 1,
115
+
"error": {
116
+
"code": -32602,
117
+
"message": "Invalid Data for call method: ExampleApi.sendEmail",
118
+
"data": {
119
+
"email": "This value is not a valid email address.",
120
+
"text": "Required parameter \"text\" not passed"
121
+
}
122
+
}
123
+
}
124
+
```
125
+
126
+
Errors inside DTO collections are bound to the specific element (`data[param][key]`).
127
+
128
+
## Constraints in the documentation
129
+
130
+
Constraints are included in the parameter's JSON Schema in the [documentation](/docs/api/json-rpc-bundle/documentation) (for example, `Length` ā `minLength`/`maxLength`, `Choice` with an enum callback ā `enum`). If `docs.validations.symfony_asserts` is enabled in the [configuration](/docs/api/json-rpc-bundle/config), the list of Symfony constraints (`x-ufo-assertions`) is also added to the parameter.
131
+
132
+
Built-in schema generators exist for `All`, `Choice`, `Collection`, `Date`, `Email`, `EqualTo`, `GreaterThan`, `GreaterThanOrEqual`, `Length`, `NotBlank`, `NotNull`, `Optional`, `Range`, `Regex`, `Uuid`; other constraints are checked but not reflected in the schema.
133
+
134
+
For custom constraints you can add a schema generator: a service tagged `rpc.constraint` that implements `Ufo\JsonRpcBundle\Validations\JsonSchema\Generate\Interfaces\IConstraintGenerator`.