|
| 1 | +# Atributos do Hydrator |
| 2 | + |
| 3 | +Este pacote fornece alguns atributos adicionais para [hydrator](https://github.com/yiisoft/hydrator). |
| 4 | + |
| 5 | +## Atributos de parâmetro |
| 6 | + |
| 7 | +Esses atributos são usados para um único parâmetro DTO: |
| 8 | + |
| 9 | +- `#[Query]` - mapeia com o parâmetro de consulta da solicitação. |
| 10 | +- `#[Body]` - mapeia com o parâmetro body da solicitação. |
| 11 | +- `#[Request]` - mapeia com o atributo da solicitação. Isso é útil quando o middleware grava o valor antes. |
| 12 | +- `#[UploadedFiles]` - mapeia com os arquivos carregados da solicitação. |
| 13 | + |
| 14 | +O uso de todos os parâmetros disponíveis é mostrado abaixo no exemplo: |
| 15 | + |
| 16 | +```php |
| 17 | +use Yiisoft\Input\Http\Attribute\Parameter\Body; |
| 18 | +use Yiisoft\Input\Http\Attribute\Parameter\Query; |
| 19 | +use Yiisoft\Input\Http\Attribute\Parameter\Request;use \Yiisoft\Input\Http\Attribute\Parameter\UploadedFiles; |
| 20 | + |
| 21 | +final class UpdatePostInput |
| 22 | +{ |
| 23 | + public function __construct( |
| 24 | + #[Query] |
| 25 | + private string $id, |
| 26 | + #[Body] |
| 27 | + private string $title, |
| 28 | + #[Body] |
| 29 | + private string $content, |
| 30 | + #[UploadedFiles] |
| 31 | + private $uploads, |
| 32 | + #[Request] |
| 33 | + private string $clientInfo = ''; |
| 34 | + ) { |
| 35 | + } |
| 36 | + |
| 37 | + // getters |
| 38 | +} |
| 39 | +``` |
| 40 | + |
| 41 | +Aqui: |
| 42 | + |
| 43 | +- O ID do post será mapeado a partir do parâmetro de consulta da solicitação; |
| 44 | +- Título e conteúdo serão mapeados a partir do corpo da solicitação; |
| 45 | +- Os uploads serão mapeados a partir dos arquivos carregados da solicitação; |
| 46 | +- As informações do cliente serão mapeadas a partir do atributo da solicitação. |
| 47 | + |
| 48 | +### Personalização |
| 49 | + |
| 50 | +Por padrão, espera-se que os parâmetros de solicitação tenham o mesmo nome das propriedades DTO. Para mudar isso, passe o nome |
| 51 | +ao anexar o atributo: |
| 52 | + |
| 53 | +```php |
| 54 | +use Yiisoft\Input\Http\Attribute\Parameter\Body; |
| 55 | +use Yiisoft\Input\Http\Attribute\Parameter\Query; |
| 56 | +use Yiisoft\Input\Http\Attribute\Parameter\Request; |
| 57 | +use Yiisoft\Input\Http\Attribute\Parameter\UploadedFiles; |
| 58 | + |
| 59 | +final class UpdatePostInput |
| 60 | +{ |
| 61 | + public function __construct( |
| 62 | + #[Query('post_id')] |
| 63 | + private string $id, |
| 64 | + #[Body('post_title')] |
| 65 | + private string $title, |
| 66 | + #[Body('post_content')] |
| 67 | + private string $content, |
| 68 | + #[UploadedFiles('post_uploads')] |
| 69 | + private $uploads, |
| 70 | + #[Request('clientData')] |
| 71 | + private string $clientInfo = ''; |
| 72 | + ) { |
| 73 | + } |
| 74 | +} |
| 75 | +``` |
| 76 | + |
| 77 | +## Atributos de dados |
| 78 | + |
| 79 | +Eles são mais organizados quando a fonte dos valores é comum: |
| 80 | + |
| 81 | +- `#[FromQuery]` - mapeia com parâmetros de consulta da solicitação. |
| 82 | +- `#[FromBody]` - mapeia com os parâmetros do corpo da solicitação. |
| 83 | + |
| 84 | +A diferença aqui é que esses atributos estão vinculados à classe como um todo, e não a um atributo individual: |
| 85 | + |
| 86 | +```php |
| 87 | +use Yiisoft\Input\Http\Attribute\Data\FromBody; |
| 88 | +use Yiisoft\Input\Http\Attribute\Data\FromQuery; |
| 89 | + |
| 90 | +#[FromQuery] |
| 91 | +final class SearchInput |
| 92 | +{ |
| 93 | + public function __construct( |
| 94 | + private string $query, |
| 95 | + private string $category, |
| 96 | + ) { |
| 97 | + } |
| 98 | + |
| 99 | + // getters |
| 100 | +} |
| 101 | + |
| 102 | +#[FromBody] |
| 103 | +final class CreateUserInput |
| 104 | +{ |
| 105 | + public function __construct( |
| 106 | + private string $username, |
| 107 | + private string $email, |
| 108 | + ) { |
| 109 | + } |
| 110 | + |
| 111 | + // getters |
| 112 | +} |
| 113 | +``` |
| 114 | + |
| 115 | +`SearchInput` será mapeado a partir dos parâmetros de consulta, enquanto `CreateUserInput` será mapeado a partir do corpo da solicitação analisado. |
| 116 | + |
| 117 | +### Personalização dos nomes dos parâmetros |
| 118 | + |
| 119 | +Semelhante aos atributos de parâmetro, os nomes dos parâmetros da solicitação podem ser customizados. Aqui isso é feito através de um mapa onde as |
| 120 | +chaves são nomes e valores de propriedades DTO de acordo com os nomes dos parâmetros da solicitação, que são esperados. Além disso, você |
| 121 | +pode restringir o escopo de onde exatamente analisar os parâmetros da solicitação. Além disso, é possível lançar uma exceção |
| 122 | +quando existem alguns parâmetros presentes no escopo da solicitação selecionada que não foram especificados no mapa. |
| 123 | + |
| 124 | +```php |
| 125 | +use Yiisoft\Input\Http\Attribute\Data\FromBody; |
| 126 | +use Yiisoft\Input\Http\Attribute\Data\FromQuery; |
| 127 | + |
| 128 | +#[FromQuery( |
| 129 | + 'search', // Use an array for bigger level of nesting, for example, `['client', 'search']`. |
| 130 | + ['query' => 'q', 'category' => 'c'], |
| 131 | + strict: true, |
| 132 | +)] |
| 133 | +final class SearchInput |
| 134 | +{ |
| 135 | + public function __construct( |
| 136 | + private string $query, |
| 137 | + private string $category, |
| 138 | + ) { |
| 139 | + } |
| 140 | +} |
| 141 | +``` |
| 142 | + |
| 143 | +No exemplo acima: |
| 144 | + |
| 145 | +- A string de consulta esperada no formato como - `?search[q]=input&search[c]=package`. O valor `input` é mapeado para a |
| 146 | +propriedade `$query`, enquanto o valor `package` - para a propriedade `$category`. |
| 147 | +- Se a string de consulta contiver parâmetros extras dentro do escopo selecionado, a exceção será lançada - |
| 148 | +`?search[q]=input&search[c]=pacote&search[s]=desc`. Parâmetros extras fora do escopo são permitidos - |
| 149 | +`?search[q]=input&search[c]=pacote&user=john`. |
0 commit comments