diff --git a/docs/guide-pt-BR/runtime-requests.md b/docs/guide-pt-BR/runtime-requests.md new file mode 100644 index 00000000000..a40349c3d4b --- /dev/null +++ b/docs/guide-pt-BR/runtime-requests.md @@ -0,0 +1,162 @@ +Requisições +=========== + +As requisições realizadas na aplicação são representadas pelo objeto [[yii\web\Request]] +que fornece informações como os parâmetros da requisição, cabeçalhos HTTP, cookies +e etc. Em uma determinada requisição, você pode acessar o objeto da requisição +correspondente através do [componente da aplicação](structure-application-components.md) +`request`, que é uma instância de [[yii\web\Request]], por padrão. Nesta seção, +descreveremos como você pode usar este componente em sua aplicação. + + +## Parâmetros da Requisição + +Para obter os parâmetros da requisição, você pode chamar os métodos +[[yii\web\Request::get()|get()]] e [[yii\web\Request::post()|post()]] do +componente `request`. Estes métodos retornam os valores de `$_GET` e `$_POST`, +respectivamente. Por exemplo, + +```php +$request = Yii::$app->request; + +$get = $request->get(); +// equivalente à: $get = $_GET; + +$id = $request->get('id'); +// equivalente à: $id = isset($_GET['id']) ? $_GET['id'] : null; + +$id = $request->get('id', 1); +// equivalente à: $id = isset($_GET['id']) ? $_GET['id'] : 1; + +$post = $request->post(); +// equivalente à: $post = $_POST; + +$name = $request->post('name'); +// equivalente à: $name = isset($_POST['name']) ? $_POST['name'] : null; + +$name = $request->post('name', ''); +// equivalente à: $name = isset($_POST['name']) ? $_POST['name'] : ''; +``` + +> Informação: Ao invés de acessar diretamente o `$_GET` e o `$_POST` para recuperar + os parâmetros da requisição, é recomendável que os utilizem através do componente + `request`, como mostrado nos exemplos acima. Isto permite que você escreva testes + de forma mais simples, utilizando um componente da requisição que retornem valores + pré-determinados. + +Ao implementar o [RESTful APIs](rest-quick-start.md), muitas vezes você precisará +recuperar os parâmetros que foram enviados pelos [métodos de requisição](#request-methods) +PUT, PATCH ou outro. Você pode recuperá-los chamando o método [[yii\web\Request::getBodyParam()]]. +Por exemplo, + +```php +$request = Yii::$app->request; + +// retorna todos os parâmetros +$params = $request->bodyParams; + +// retorna o parâmetro "id" +$param = $request->getBodyParam('id'); +``` + +> Informação: Tirando os parâmetros `GET`, os parâmetros `POST`, `PUT`, `PATCH` + e etc são enviados no corpo da requisição. O componente `request` analisará + estes parâmetros quando você acessá-los através dos métodos descritos acima. + Você pode personalizar a forma como estes parâmetros são analisados pela + configuração da propriedade [[yii\web\Request::parsers]]. + + +## Métodos da Requisição + +Você pode obter o método HTTP usado pela requisição atual através da expressão +`Yii::$app->request->method`. Um conjunto de propriedades booleanas também são +fornecidos para que você consiga verificar se o método atual é o correto. +Por exemplo, + +```php +$request = Yii::$app->request; + +if ($request->isAjax) { /* a requisição é uma requisição Ajax */ } +if ($request->isGet) { /* o método da requisição é GET */ } +if ($request->isPost) { /* o método da requisição é POST */ } +if ($request->isPut) { /* o método da requisição é PUT */ } +``` + +## URLs da Requisição + +O componente `request` fornece muitas formas de inspecionar a atual URL da requisição. +Assumindo que a URL da requisição seja `http://example.com/admin/index.php/product?id=100`, +você pode obter várias partes desta URL através das propriedades explicadas a seguir: + +* [[yii\web\Request::url|url]]: retorna `/admin/index.php/product?id=100`, que é + a URL sem as informações de protocolo e de domínio. +* [[yii\web\Request::absoluteUrl|absoluteUrl]]: retorna `http://example.com/admin/index.php/product?id=100`, + que é a URL completa, incluindo as informações de protocolo e de domínio. +* [[yii\web\Request::hostInfo|hostInfo]]: retorna `http://example.com`, que são + as informações de protocolo e de domínio da URL. +* [[yii\web\Request::pathInfo|pathInfo]]: retorna `/product`, que é a informação + depois do script de entrada e antes da interrogação (da query string). +* [[yii\web\Request::queryString|queryString]]: retorna `id=100`, que é a + informação depois da interrogação. +* [[yii\web\Request::baseUrl|baseUrl]]: retorna `/admin`, que é a informação + depois do domínio e antes do script de entrada. +* [[yii\web\Request::scriptUrl|scriptUrl]]: retorna `/admin/index.php`, que é a + informação depois do domínio até o script de entrada, inclusive. +* [[yii\web\Request::serverName|serverName]]: retorna `example.com`, que é o + domínio da URL. +* [[yii\web\Request::serverPort|serverPort]]: retorna 80, que é a porta usada + pelo servidor Web. + + +## Cabeçalho HTTP + +Você pode obter as informações do cabeçalho HTTP através da +[[yii\web\HeaderCollection|coleção de cabeçalho]] retornado pela propriedade +[[yii\web\Request::headers]]. Por exemplo, + +```php +// $headers é um objeto de yii\web\HeaderCollection +$headers = Yii::$app->request->headers; + +// retorna o valor do cabeçalho Accept +$accept = $headers->get('Accept'); + +if ($headers->has('User-Agent')) { /* existe o cabeçalho User-Agent */ } +``` + +O componente `request` também fornece suporte para fácil acesso de alguns +cabeçalhos mais utilizados, incluindo: + +* [[yii\web\Request::userAgent|userAgent]]: retorna o valor do cabeçalho `User-Agent`. +* [[yii\web\Request::contentType|contentType]]: retorna o valor do cabeçalho + `Content-Type` que indica o tipo MIME dos dados do corpo da requisição. +* [[yii\web\Request::acceptableContentTypes|acceptableContentTypes]]: retorna os + tipos MIME acessíveis pelos usuários. Os tipos retornados são ordenados pela + sua pontuação de qualidade. Tipos com mais pontuação aparecerão nas primeiras posições. +* [[yii\web\Request::acceptableLanguages|acceptableLanguages]]: retorna os idiomas + acessíveis pelos usuários. Os idiomas retornados são ordenados pelo nível de + preferência. O primeiro elemento representa o idioma de maior preferência. + +Se a sua aplicação suportar diversos idiomas e quiser exibir páginas no idioma +de maior preferência do usuário, você pode usar o método de negociação +[[yii\web\Request::getPreferredLanguage()]]. Este método pega uma lista de +idiomas suportadas pela sua aplicação e compara com +[[yii\web\Request::acceptableLanguages|acceptableLanguages]], para retornar o +idioma mais adequado. + +> Dica: Você também pode utilizar o filtro [[yii\filters\ContentNegotiator|ContentNegotiator]] + para determinar dinamicamente qual tipo de conteúdo e idioma que deve ser utilizado + na resposta. O filtro implementa negociação de conteúdo em cima das propriedades + e métodos descritos acima. + + +## Informações do Cliente + +Você pode obter o nome do domínio ou endereço IP da máquina do cliente através +das propriedades [[yii\web\Request::userHost|userHost]] e +[[yii\web\Request::userIP|userIP]], respectivamente. Por exemplo, + +```php +$userHost = Yii::$app->request->userHost; +$userIP = Yii::$app->request->userIP; +``` diff --git a/docs/internals-pt-BR/translation-workflow.md b/docs/internals-pt-BR/translation-workflow.md index 4a3f6d4462e..7cd957bdd89 100644 --- a/docs/internals-pt-BR/translation-workflow.md +++ b/docs/internals-pt-BR/translation-workflow.md @@ -113,4 +113,5 @@ Regras e Observações - template - query string - case-sensitive -- case-insensitive \ No newline at end of file +- case-insensitive +- callback \ No newline at end of file