translation into brazilian portuguese (#37)

LICENSE.md

@@ -1,17 +1,17 @@
-Copyright © 2008 by Yii Software (https://www.yiiframework.com/)
+Copyright © 2008 by Yii Software (<https://www.yiiframework.com/>)
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 
- * Redistributions of source code must retain the above copyright
+* Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
+* Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in
    the documentation and/or other materials provided with the
    distribution.
- * Neither the name of Yii Software nor the names of its
+* Neither the name of Yii Software nor the names of its
    contributors may be used to endorse or promote products derived
    from this software without specific prior written permission.
 

README.md

@@ -18,6 +18,7 @@
 The package provides [Yii Hydrator](https://github.com/yiisoft/hydrator) attributes
 to get data from [PSR-7 HTTP request](https://www.php-fig.org/psr/psr-7/) and adds extra abilities to middlewares
 processed by [Yii Middleware Dispatcher](https://github.com/yiisoft/middleware-dispatcher):
+
 - maps data from PSR-7 HTTP request to PHP DTO representing user input;
 - uses Yii Hydrator parameter attributes for resolving middleware parameters.
 
@@ -78,15 +79,20 @@ For other available options, see the [guide](docs/guide/en).
 
 ## Documentation
 
-- [Guide](docs/guide/en)
-- [Internals](docs/internals.md)
+- [English](docs/guide/en/README.md)
+- [Português - Brasil](docs/guide/pt-BR/readme.md)
 
-## License
+Testing:
 
-The Yii Input HTTP is free software. It is released under the terms of the BSD License.
-Please see [`LICENSE`](./LICENSE.md) for more information.
+- [English](docs/guide/en/testing.md)
+- [Português - Brasil:](docs/guide/pt-BR/testing.md)
 
-Maintained by [Yii Software](https://www.yiiframework.com/).
+- [Internals](docs/internals.md)
+
+## Support
+
+If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.
+You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
 
 ## Support the project
 
@@ -99,3 +105,10 @@ Maintained by [Yii Software](https://www.yiiframework.com/).
 [![Telegram](https://img.shields.io/badge/telegram-join-1DA1F2?style=flat&logo=telegram)](https://t.me/yii3en)
 [![Facebook](https://img.shields.io/badge/facebook-join-1DA1F2?style=flat&logo=facebook&logoColor=ffffff)](https://www.facebook.com/groups/yiitalk)
 [![Slack](https://img.shields.io/badge/slack-join-1DA1F2?style=flat&logo=slack)](https://yiiframework.com/go/slack)
+
+## License
+
+The Yii Input HTTP is free software. It is released under the terms of the BSD License.
+Please see [`LICENSE`](./LICENSE.md) for more information.
+
+Maintained by [Yii Software](https://www.yiiframework.com/).

docs/guide/en/hydrator-attributes.md

@@ -4,12 +4,12 @@ This package provides some additional attributes for [hydrator](https://github.c
 
 ## Parameter attributes
 
-These attributes are used for a single DTO parameter: 
+These attributes are used for a single DTO parameter:
 
 - `#[Query]` - maps with request's query parameter.
 - `#[Body]` - maps with request's body parameter.
 - `#[Request]` - maps with request's attribute. This is useful when middleware prior writes the value.
-- `#[UploadedFiles]` - maps with request's uploaded files. 
+- `#[UploadedFiles]` - maps with request's uploaded files.
 
 The usage of all available parameters is shown below in the single example:
 
@@ -112,13 +112,13 @@ final class CreateUserInput
 }
 ```
 
-`SearchInput` will be mapped from query parameters, while `CreateUserInput` will be mapped from parsed request body.                   
+`SearchInput` will be mapped from query parameters, while `CreateUserInput` will be mapped from parsed request body.
 
-### Customization
+### Customizing parameter names
 
-Similar to parameter attributes, the names of request's parameters can be customized. Here it's done via a map where 
-keys are DTO properties' names and values according to request's parameter names, which are expected. Besides that, you 
-can narrow down the scope where exactly to parse the request parameters from. Also, it's possible to throw the exception
+Similar to parameter attributes, the names of request's parameters can be customized. Here it's done via a map where
+keys are DTO properties' names and values according to request's parameter names, which are expected. Besides that, you
+can narrow down the scope where exactly to parse the request parameters from. Also, it's possible to throw an exception
 when there are some parameters present in the selected request's scope that were not specified in the map.
 
 ```php
@@ -143,7 +143,7 @@ final class SearchInput
 In the above example:
 
 - The query string expected in the format such as - `?search[q]=input&search[c]=package`. `input` value is mapped to
-`$query` property, while `package` value - to `$category` property. 
-- If the query string contains extra parameters within the selected scope, the exception will be thrown - 
-`?search[q]=input&search[c]=package&search[s]=desc`. Extra parameters outside the scope are allowed though - 
+`$query` property, while `package` value - to `$category` property.
+- If the query string contains extra parameters within the selected scope, the exception will be thrown -
+`?search[q]=input&search[c]=package&search[s]=desc`. Extra parameters outside the scope are allowed though -
 `?search[q]=input&search[c]=package&user=john`.

docs/guide/en/parameters-resolvers.md

@@ -1,7 +1,7 @@
 # Parameters' resolvers
 
 This package offers multiple
-[custom implementations of parameters' resolver](https://github.com/yiisoft/middleware-dispatcher?tab=readme-ov-file#creating-your-own-implementation-of-parameters-resolver) 
+[custom implementations of parameters' resolver](https://github.com/yiisoft/middleware-dispatcher?tab=readme-ov-file#creating-your-own-implementation-of-parameters-resolver)
 from [Yii Middleware Dispatcher](https://github.com/yiisoft/middleware-dispatcher) package:
 
 - [`HydratorAttributeParametersResolver`](#hydratorattributeparametersresolver)
@@ -85,11 +85,11 @@ $resolver = new HydratorAttributeParametersResolver(
 $dispatcher = new MiddlewareDispatcher(new MiddlewareFactory($container, $resolver), $eventDispatcher);
 ```
 
-More info about dependencies from [Yii Hydrator](https://github.com/yiisoft/hydrator) package can be found in its docs 
+More info about dependencies from [Yii Hydrator](https://github.com/yiisoft/hydrator) package can be found in its docs
 and guide:
- 
+
 - [attribute resolver factory](https://github.com/yiisoft/hydrator/blob/master/docs/guide/en/attribute-resolver-factory.md)
-- [type casting](https://github.com/yiisoft/hydrator/blob/master/docs/guide/en/typecasting.md) 
+- [type casting](https://github.com/yiisoft/hydrator/blob/master/docs/guide/en/typecasting.md)
 - [hydrator](https://github.com/yiisoft/hydrator)
 
 Using within a group of resolvers:
@@ -153,7 +153,7 @@ final class UpdatePostController
 
 The used DTO is [request input](request-input.md) with [hydrator attribute](hydrator-attributes.md) applied.
 
-> As an alternative, [Yii Validating Hydrator](https://github.com/yiisoft/hydrator-validator) can be used instead for 
+> As an alternative, [Yii Validating Hydrator](https://github.com/yiisoft/hydrator-validator) can be used instead for
 > automatic validation of request input DTO.
 
 ### Adding to middleware dispatcher

docs/guide/en/request-input.md

@@ -36,13 +36,13 @@ final class UpdatePostInput implements RequestInputInterface
 
 For more available options, see [Hydrator attributes](hydrator-attributes.md) section.
 
-The main concept of request input is to ease automatic filling with according 
+The main concept of request input is to ease automatic filling with according
 [resolver](parameters-resolvers.md#requestinputparametersresolver).
 It's possible to use hydrator directly too, though.
 
 ## Combining with validation
 
-If you need validation features additionally, extend the DTO from `AbstractInput` class which also implements 
+If you need validation features additionally, extend the DTO from `AbstractInput` class which also implements
 `ValidatedInputInterface`. This way you can use validation attributes for properties:
 
 ```php
@@ -86,5 +86,5 @@ $isValid = $result->isValid();
 $errorMessagesMap = $result->getErrorMessagesIndexedByPath();
 ```
 
-More thorough guide for working with the validation result is available in the 
-[validator guide](https://github.com/yiisoft/validator/blob/1.x/docs/guide/en/result.md). 
+More thorough guide for working with the validation result is available in the
+[validator guide](https://github.com/yiisoft/validator/blob/1.x/docs/guide/en/result.md).

docs/guide/pt-BR/README.md

@@ -0,0 +1,5 @@
+# Yii Input HTTP
+
+- [Hydrator attributes](hydrator-attributes.md)
+- [Request input](request-input.md)
+- [Parameters' resolvers](parameters-resolvers.md)

docs/guide/pt-BR/hydrator-attributes.md

@@ -0,0 +1,149 @@
+# Atributos do Hydrator
+
+Este pacote fornece alguns atributos adicionais para [hydrator](https://github.com/yiisoft/hydrator).
+
+## Atributos de parâmetro
+
+Esses atributos são usados para um único parâmetro DTO:
+
+- `#[Query]` - mapeia com o parâmetro de consulta da solicitação.
+- `#[Body]` - mapeia com o parâmetro body da solicitação.
+- `#[Request]` - mapeia com o atributo da solicitação. Isso é útil quando o middleware grava o valor antes.
+- `#[UploadedFiles]` - mapeia com os arquivos carregados da solicitação.
+
+O uso de todos os parâmetros disponíveis é mostrado abaixo no exemplo:
+
+```php
+use Yiisoft\Input\Http\Attribute\Parameter\Body;
+use Yiisoft\Input\Http\Attribute\Parameter\Query;
+use Yiisoft\Input\Http\Attribute\Parameter\Request;use \Yiisoft\Input\Http\Attribute\Parameter\UploadedFiles;
+
+final class UpdatePostInput
+{
+    public function __construct(
+        #[Query]
+        private string $id,
+        #[Body]        
+        private string $title,
+        #[Body]        
+        private string $content,
+        #[UploadedFiles]        
+        private $uploads,
+        #[Request]
+        private string $clientInfo = '';
+    ) {
+    }
+
+    // getters       
+} 
+```
+
+Aqui:
+
+- O ID do post será mapeado a partir do parâmetro de consulta da solicitação;
+- Título e conteúdo serão mapeados a partir do corpo da solicitação;
+- Os uploads serão mapeados a partir dos arquivos carregados da solicitação;
+- As informações do cliente serão mapeadas a partir do atributo da solicitação.
+
+### Personalização
+
+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
+ao anexar o atributo:
+
+```php
+use Yiisoft\Input\Http\Attribute\Parameter\Body;
+use Yiisoft\Input\Http\Attribute\Parameter\Query;
+use Yiisoft\Input\Http\Attribute\Parameter\Request;
+use Yiisoft\Input\Http\Attribute\Parameter\UploadedFiles;
+
+final class UpdatePostInput
+{
+    public function __construct(
+        #[Query('post_id')]
+        private string $id,
+        #[Body('post_title')]        
+        private string $title,
+        #[Body('post_content')]        
+        private string $content,
+        #[UploadedFiles('post_uploads')]        
+        private $uploads,
+        #[Request('clientData')]
+        private string $clientInfo = '';
+    ) {
+    }   
+} 
+```
+
+## Atributos de dados
+
+Eles são mais organizados quando a fonte dos valores é comum:
+
+- `#[FromQuery]` - mapeia com parâmetros de consulta da solicitação.
+- `#[FromBody]` - mapeia com os parâmetros do corpo da solicitação.
+
+A diferença aqui é que esses atributos estão vinculados à classe como um todo, e não a um atributo individual:
+
+```php
+use Yiisoft\Input\Http\Attribute\Data\FromBody;
+use Yiisoft\Input\Http\Attribute\Data\FromQuery; 
+
+#[FromQuery]
+final class SearchInput
+{
+    public function __construct(
+        private string $query,
+        private string $category,
+    ) {
+    }
+
+    // getters
+}
+
+#[FromBody]
+final class CreateUserInput
+{
+    public function __construct(
+        private string $username,
+        private string $email,
+    ) {
+    }
+
+    // getters
+}
+```
+
+`SearchInput` será mapeado a partir dos parâmetros de consulta, enquanto `CreateUserInput` será mapeado a partir do corpo da solicitação analisado.
+
+### Personalização dos nomes dos parâmetros
+
+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
+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ê
+pode restringir o escopo de onde exatamente analisar os parâmetros da solicitação. Além disso, é possível lançar uma exceção
+quando existem alguns parâmetros presentes no escopo da solicitação selecionada que não foram especificados no mapa.
+
+```php
+use Yiisoft\Input\Http\Attribute\Data\FromBody;
+use Yiisoft\Input\Http\Attribute\Data\FromQuery; 
+
+#[FromQuery(
+    'search', // Use an array for bigger level of nesting, for example, `['client', 'search']`. 
+    ['query' => 'q', 'category' => 'c'], 
+    strict: true,
+)]
+final class SearchInput
+{
+    public function __construct(
+        private string $query,
+        private string $category,
+    ) {
+    }
+}
+```
+
+No exemplo acima:
+
+- A string de consulta esperada no formato como - `?search[q]=input&search[c]=package`. O valor `input` é mapeado para a
+propriedade `$query`, enquanto o valor `package` - para a propriedade `$category`.
+- Se a string de consulta contiver parâmetros extras dentro do escopo selecionado, a exceção será lançada -
+`?search[q]=input&search[c]=pacote&search[s]=desc`. Parâmetros extras fora do escopo são permitidos -
+`?search[q]=input&search[c]=pacote&user=john`.