docs/guide-pt-BR/runtime-routing.md - translate [ci skip]

10 years ago · 745715f45f
1 changed files with 752 additions and 0 deletions
--- a/docs/guide-pt-BR/runtime-routing.md
+++ b/docs/guide-pt-BR/runtime-routing.md
@ -0,0 +1,752 @@
+Roteamento e Criação de URL
+===========================
+
+Quando uma aplicação Yii começa a processar uma URL requerida, o primeiro passo 
+necessário é obter a rota pela análise da URL. A rota é usada para instanciar o 
+[controlador (controller) da ação](structure-controllers.md) correspondente para 
+manipular a requisição. Todo este processo é chamado de *roteamento*.
+ 
+O processo inverso do roteamento é chamada de *criação de URL*, onde é criado uma 
+URL a partir de uma determinada rota e seus parâmetros. Quando a URL criada for 
+exigida em outro momento, o processo de roteamento pode resolve-la de volta para 
+a rota original e seus parâmetros.
+
+O ponto central responsável pelo roteamento e pela criação de URL é o 
+[[yii\web\UrlManager|gerenciador de URL]], na qual é registrado como o 
+[componente da aplicação](structure-application-components.md) `urlManager`. O 
+[[yii\web\UrlManager|gerenciador de URL]] fornece o método 
+[[yii\web\UrlManager::parseRequest()|parseRequest()]] para analisar um requisição 
+de entrada a fim de obter uma rota e seus parâmetros associados; e o método 
+[[yii\web\UrlManager::createUrl()|createUrl()]] para criar uma URL a partir de 
+uma rota e seus parâmetros associados.
+
+Ao configurar o componente `urlManager` na configuração da aplicação, poderá 
+fazer com que sua aplicação reconheça de forma arbitrária diversos formatos de 
+URL sem modificar o código existente da aplicação. Por exemplo, você pode usar o 
+código a seguir para criar uma URL a partir da ação `post/view`:
+
+```php
+use yii\helpers\Url;
+
+// Url::to() chama UrlManager::createUrl() para criar uma URL
+$url = Url::to(['post/view', 'id' => 100]);
+```
+
+Dependendo da configuração da propriedade `urlManager`, a URL criada pode ser 
+parecida com um dos formatos a seguir (ou até mesmo com outro formato). E se a 
+URL criada for requerida, ainda será analisada a fim de obter a rota e os valores 
+dos parâmetros originais.
+
+```
+/index.php?r=post/view&id=100
+/index.php/post/100
+/posts/100
+```
+
+
+## Formatos de URL <span id="url-formats"></span>
+
+O [[yii\web\UrlManager|gerenciador de URL]] suporta dois formatos de URL: o 
+formato de URL padrão e o formato de URL amigável (pretty URL).
+
+O formato de URL padrão usa um parâmetro chamado `r` para representar a rota e 
+os demais parâmetros representam os parâmetros associados a rota. Por exemplo, a 
+URL `/index.php?r=post/view&id=100` representa a rota `post/view` e o parâmetro 
+`id` com o valor 100. O formato de URL padrão não exige qualquer tipo de 
+configuração no [[yii\web\UrlManager|gerenciador de URL]] e trabalha em qualquer 
+servidor Web.
+
+O formato de URL amigável (pretty URL) usa um caminho adicional após o nome do 
+script de entrada para representar a rota e seus parâmetros. Por exemplo, o 
+caminho adicional na URL `/index.php/post/100` é `/post/100`, onde pode 
+representar, em uma adequada [[yii\web\UrlManager::rules|regra de URL]], a rota 
+`post/view` e o parâmetro `id` com o valor 100. Para usar o formato de URL 
+amigável (pretty URL), você precisará escrever um conjunto de 
+[[yii\web\UrlManager::rules|regras de URLs]] de acordo com a necessidade sobre 
+como as URLs devem parecer.
+ 
+Você pode alterar entre os dois formatos de URLs, alternando a propriedade 
+[[yii\web\UrlManager::enablePrettyUrl|enablePrettyUrl]] do 
+[[yii\web\UrlManager|gerenciador de URL]] sem alterar qualquer código na aplicação.
+
+
+## Roteamento <span id="routing"></span>
+
+O roteamento envolve duas etapas. Na primeira etapa, a requisição de entrada é 
+transformada em uma rota e seus parâmetros. Na segunda etapa, a 
+[ação do controller (controlador)](structure-controllers.md) correspondente a 
+rota analisada será criada para processar a requisição.
+
+Ao utilizar o formato de URL padrão, a análise de uma requisição para obter uma 
+rota é tão simples como pegar o valor via `GET` do parâmetro `r`.
+
+Ao utilizar o formato de URL amigável (pretty URL), o 
+[[yii\web\UrlManager|gerenciado de URL]] examinará as 
+[[yii\web\UrlManager::rules|regras de URLs]] registradas para encontrar alguma 
+correspondência que poderá resolver a requisição em uma rota. Se tal regra não 
+for encontrada, uma exceção [[yii\web\NotFoundHttpException]] será lançada.
+
+Uma vez que a requisição analisada apresentar uma rota, é hora de criar a ação 
+do controller (controlador) identificado pela rota.
+A rota é dividida em várias partes pelo separador barra (“/”). Por exemplo, a 
+rota `site/index` será dividida em duas partes: `site` e `index`. Cada parte é 
+um ID que pode referenciar a um módulo, um controller (controlador) ou uma ação.
+A partir da primeira parte da rota, a aplicação executará as seguintes etapas para 
+criar o módulo (se existir), o controller (controlador) e a ação:
+
+1. Define a aplicação como o módulo atual.
+2. Verifica se o [[yii\base\Module::controllerMap|mapa do controller (controlador)]] 
+   do módulo contém o ID atual. Caso exista, um objeto do controller (controlador) 
+   será criado de acordo com a configuração do controller (controlador) encontrado 
+   no mapa e a etapa 3 e 4 não serão executadas.   
+3. Verifica se o ID referência a um módulo listado na propriedade 
+   [[yii\base\Module::modules|modules]] do módulo atual. Caso exista, um módulo 
+   será criado de acordo com as configurações encontradas na lista e a etapa 2 
+   será executada como etapa seguinte do processo, no âmbito de usar o contexto 
+   do módulo recém-criado.
+4. Trata o ID como um ID do controller (controlador) e cria um objeto do controller 
+   (controlador). Siga para a próxima etapa, como parte restante do processo.
+5. O controller (controlador) procura o ID atual em seu 
+   [[yii\base\Controller::actions()|mapa de ações]]. Caso exista, será criado uma 
+   ação de acordo com a configuração encontrada no mapa. Caso contrário, o 
+   controller (controlador) tentará criar uma ação inline que é definida por um 
+   método da ação correspondente ao ID atual.
+
+Nas etapas acima, se ocorrer qualquer erro, uma exceção [[yii\web\NotFoundHttpException]] 
+será lançada, indicando a falha no processo de roteamento.
+
+
+### Rota Padrão <span id="default-route"></span>
+
+Quando uma requisição analisada apresentar uma rota vazia, a assim chamada 
+*rota padrão* será usada em seu lugar. A rota padrão é `site/index` é utilizada 
+como padrão, que referencia a ação `index` do controller (controlador) `site`.
+Você pode personalizar esta configuração pela propriedade 
+[[yii\web\Application::defaultRoute|defaultRoute]] na configuração da aplicação 
+como mostrado a seguir:
+
+```php
+[
+    // ...
+    'defaultRoute' => 'main/index',
+];
+```
+
+
+### Rota `catchAll` <span id="catchall-route"></span>
+
+Às vezes você pode querer colocar sua aplicação Web em modo de manutenção 
+temporariamente e exibir uma mesma página com informações para todas as requisições. 
+Existem muitas maneiras de atingir este objetivo. Mas uma das maneiras mais simples 
+é apenas configurar a propriedade [[yii\web\Application::catchAll]] na configuração 
+da aplicação como mostrado a seguir:
+
+```php
+[
+    // ...
+    'catchAll' => ['site/offline'],
+];
+```
+
+Na configuração acima, a ação `site/offline` será utilizado para lidar com todas 
+as requisições recebidas.
+
+A propriedade `catchAll` deve receber um array, o primeiro elemento especifica a 
+rota e o restante dos elementos (pares de nomes e seus valores) especificam os 
+parâmetros a serem [associados a ação](structure-controllers.md#action-parameters).
+
+
+## Criando URLs <span id="creating-urls"></span>
+
+O Yii fornece um método de ajuda [[yii\helpers\Url::to()]] para criar vários tipos 
+de URLs a partir de determinadas rotas e seus parâmetros. Por exemplo,
+
+```php
+use yii\helpers\Url;
+
+// cria uma URL para uma rota: /index.php?r=post/index
+echo Url::to(['post/index']);
+
+// cria uma URL para uma rota com parâmetros: /index.php?r=post/view&id=100
+echo Url::to(['post/view', 'id' => 100]);
+
+// cria uma URL ancorada: /index.php?r=post/view&id=100#content
+echo Url::to(['post/view', 'id' => 100, '#' => 'content']);
+
+// cria uma URL absoluta: http://www.example.com/index.php?r=post/index
+echo Url::to(['post/index'], true);
+
+// cria uma URL absoluta usando https: https://www.example.com/index.php?r=post/index
+echo Url::to(['post/index'], 'https');
+```
+
+Observe que nos exemplos acima, assumimos o formato de URL padrão. Se o formato 
+de URL amigável (pretty URL) estiver habilitado, as URLs criadas serão diferentes 
+de acordo com as [[yii\web\UrlManager::rules|regra de URL]] em uso. 
+
+A rota passada para o método [[yii\helpers\Url::to()]] é sensível ao contexto. 
+Ele pode ser tanto uma rota *relativa* quanto uma rota *absoluta* que será 
+normalizada de acordo com as regras a seguir:
+
+- Se a rota for uma string vazia, a requisição atual [[yii\web\Controller::route|route]] será usada;
+- Se a rota não contivér barras (“/”), ele será considerado um ID da ação do 
+  controller (controlador) atual e será antecedido pelo valor da propriedade 
+  [[\yii\web\Controller::uniqueId|uniqueId]] do controller (controlador) atual;
+- Se a rota não contivér uma barra (“/”) inicial, será considerado como uma rota
+  relativa ao módulo atual e será antecedido pelo valor da propriedade 
+  [[\yii\base\Module::uniqueId|uniqueId]] do módulo atual.
+
+A partir da versão 2.0.2, você pode especificar uma rota usando 
+[alias](concept-aliases.md). Se for este o caso, a alias será a primeira a ser 
+convertida em uma rota real e em seguida será transformada em uma rota absoluta 
+de acordo com as regras informadas anteriormente.
+
+Por exemplo, assumindo que o módulo atual é `admin` e o controller (controlador) 
+atual é `post`,
+
+```php
+use yii\helpers\Url;
+
+// rota atual requerida: /index.php?r=admin/post/index
+echo Url::to(['']);
+
+// uma rota relativa com apenas o ID da ação: /index.php?r=admin/post/index
+echo Url::to(['index']);
+
+// uma rota relativa: /index.php?r=admin/post/index
+echo Url::to(['post/index']);
+
+// uma rota absoluta: /index.php?r=post/index
+echo Url::to(['/post/index']);
+
+// /index.php?r=post/index     assumindo que a alias "@posts" foi definida como "/post/index"
+echo Url::to(['@posts']);
+```
+
+O método [[yii\helpers\Url::to()]] é implementado através das chamadas dos métodos 
+[[yii\web\UrlManager::createUrl()|createUrl()]] e 
+[[yii\web\UrlManager::createAbsoluteUrl()|createAbsoluteUrl()]] do 
+[[yii\web\UrlManager|gerenciador de URL]].
+Nas próximas subseções, iremos explicar como configurar o 
+[[yii\web\UrlManager|gerenciador de URL]] para personalizar os formatos das URLs criadas.
+
+O método [[yii\helpers\Url::to()]] também suporta a criação de URLs NÃO relacionadas 
+a uma rota em particular. Neste caso, ao invés de passar um array como seu primeiro 
+parâmetro, você pode passar uma string. Por exemplo,
+ 
+```php
+use yii\helpers\Url;
+
+// rota atual requerida: /index.php?r=admin/post/index
+echo Url::to();
+
+// uma alias da URL: http://example.com
+Yii::setAlias('@example', 'http://example.com/');
+echo Url::to('@example');
+
+// uma URL absoluta: http://example.com/images/logo.gif
+echo Url::to('/images/logo.gif', true);
+```
+
+Além do método `to()`, a classe auxiliar [[yii\helpers\Url]] também fornece uma 
+série de métodos referentes a criação de URLs. Por exemplo,
+
+```php
+use yii\helpers\Url;
+
+// URL da página inicial: /index.php?r=site/index
+echo Url::home();
+
+// URL base, útil se a aplicação for implementada em uma subpasta da pasta raiz do servidor Web
+echo Url::base();
+
+// A URL canônica da requisição atual
+// Veja mais detalhes em https://en.wikipedia.org/wiki/Canonical_link_element
+echo Url::canonical();
+
+// Obtêm a URL da requisição anterior para reutilizá-la em requisições futuras
+Url::remember();
+echo Url::previous();
+``` 
+
+
+## Usando URLs Amigáveis (Pretty URLs) <span id="using-pretty-urls"></span>
+
+Para utilizar as URLs amigáveis (pretty URLs), configure o componente `urlManager` 
+na configuração da aplicação conforme o exemplo a seguir:
+
+```php
+[
+    'components' => [
+        'urlManager' => [
+            'enablePrettyUrl' => true,
+            'showScriptName' => false,
+            'enableStrictParsing' => false,
+            'rules' => [
+                // ...
+            ],
+        ],
+    ],
+]
+```
+
+A propriedade [[yii\web\UrlManager::enablePrettyUrl|enablePrettyUrl]] é obrigatória 
+para habilitar o formato de URL amigável (pretty URL).
+O restante das propriedades são opcionais. No entanto, a configuração utilizada 
+acima é a mais utilizada.
+
+* [[yii\web\UrlManager::showScriptName|showScriptName]]: esta propriedade determina
+  se o script de entrada deve ser incluído ou não nas URLs criadas. Por exemplo, 
+  ao invés de criar uma URL `/index.php/post/100`, definindo esta propriedade 
+  como `false`, a URL `/post/100` será gerada.
+* [[yii\web\UrlManager::enableStrictParsing|enableStrictParsing]]: esta propriedade 
+  habilita uma análise rigorosa (strict parsing) da requisição. Caso a análise 
+  rigorosa estiver habilitada, a URL da requisição deve corresponder pelo menos 
+  a uma das regras definidas pela propriedade [[yii\web\UrlManager::rules|rules]] 
+  a fim de ser tratado como uma requisição válida, caso contrário a exceção 
+  [[yii\web\NotFoundHttpException]] será lançada. Caso a análise rigorosa estiver 
+  desabilitada, as regras definidas pela propriedade 
+  [[yii\web\UrlManager::rules|rules]] NÃO serão verificadas e as informações 
+  obtidas pela URL serão tratadas como a rota da requisição.
+* [[yii\web\UrlManager::rules|rules]]: esta propriedade contém uma lista de 
+  regras especificando como serão analisadas e criadas as URLs. Esta é a principal 
+  propriedade que você deve trabalhar para criar URLs cujos formatos satisfaçam 
+  a sua exigência em particular.
+
+> Observação: A fim de esconder o nome do script de entrada nas URLs criadas, 
+  além de definir a propriedade [[yii\web\UrlManager::showScriptName|showScriptName]] 
+  como `false`, você também pode precisar configurar o seu servidor Web para 
+  identificar corretamente o script PHP quando uma URL da requisição não 
+  especificar um explicitamente. Caso você estejam utilizando um servidor Web 
+  com Apache, você pode consultar a configuração recomendada, conforme descrito 
+  na seção [Installation](start-installation.md#recommended-apache-configuration).
+
+
+### Regras de URLs <span id="url-rules"></span>
+
+Uma regra de URL é uma instância de [[yii\web\UrlRule]] ou de classes que as estendam. 
+Cada regra de URL consiste de um padrão usado para combinar as partes do caminho 
+das URLs, como uma rota e alguns parâmetros. Uma regra de URL pode ser usado para 
+analisar uma URL da requisição somente se o padrão corresponder com a esta URL. 
+Uma regra de URL pode ser usada para criar uma URL para corresponder a uma 
+determinada rota e seus parâmetros.
+
+Quando uma formato de URL amigável (pretty URL) estiver habilitada, o 
+[[yii\web\UrlManager|gerenciador de URL]] utilizará as regras de URLs declaradas 
+na propriedade [[yii\web\UrlManager::rules|rules]] para analisar as requisições 
+e para criar URLs. Em particular, para analisar uma requisição, o 
+[[yii\web\UrlManager|gerenciador de URL]] verificará as regras na ordem em que 
+foram declaradas e só enxergará a *primeira* regra que corresponda a URL da 
+requisição. A regra que foi correspondida é então utilizada para obter a rota e 
+seus parâmetros a partir de sua análise. A mesma coisa acontece na criação de
+URLs, o [[yii\web\UrlManager|gerenciador de URL]] enxergará apenas a primeira 
+regra que corresponda a rota e seus parâmetros para serem utilizados na criação 
+de uma URL.
+
+Você pode configurar a propriedade [[yii\web\UrlManager::rules]] com um array 
+composto de pares de chave-valor, onde a chave é o padrão da regra e o valor 
+serão as rotas. Cada par de padrão-rota define uma regra de URL. Por exemplo, 
+as [[yii\web\UrlManager::rules|regras]] a seguir configuram duas regras de URL.
+A primeira regra corresponde a uma URL chamada `posts` sendo mapeado para utilizar 
+a rota `post/index`.
+A segunda regra corresponde a uma URL que combine com expressão regular 
+`post/(\d+)` seguido de um parâmetro chamado `id` sendo mapeado para utilizar a
+rota `post/view`.
+
+```php
+[
+    'posts' => 'post/index', 
+    'post/<id:\d+>' => 'post/view',
+]
+```
+
+> Informação: O padrão em uma regra é usado para identificar o caminho de uma URL. 
+  Por exemplo, o caminho da URL `/index.php/post/100?source=ad` é `post/100` 
+  (as barras (“/”) iniciais e finais serão ignoradas) combinando com o padrão `post/(\d+)`.
+
+Além de declarar regras de URL como pares de padrão-rota, você também pode declarar 
+como array. Cada array é utilizado para configurar um único objeto da regra de URL. 
+Isto se faz necessário quando você deseja configurar outras propriedades de uma 
+regra de URL. Por exemplo,
+
+```php
+[
+    // ...outras regras de URL...
+    
+    [
+        'pattern' => 'posts',
+        'route' => 'post/index',
+        'suffix' => '.json',
+    ],
+]
+```
+
+Por padrão, se você não especificar a opção `class` na configuração de uma regra, 
+será utilizado a classe [[yii\web\UrlRule]].
+
+
+### Parâmetros Nomeados <span id="named-parameters"></span>
+
+Uma regra de URL pode ser associado a alguns parâmetros nomeados que são 
+especificados no padrão `<ParamName:RegExp>`, onde o `ParamName` especifica o 
+nome do parâmetro e o `RegExp` especifica uma expressão regular opcional usada 
+para corresponder ao valor do parâmetro. Se o `RegExp` são for especificado, 
+significará que o valor do parâmetro será uma string sem barras (“/”).
+
+> Observação: Você apenas pode especificar expressões regulares para os parâmetros. 
+  As demais partes de um padrão serão considerados como um texto simples.
+
+Quando esta regra for utilizada para analisar uma URL, os parâmetros associados 
+serão preenchidos com os valores que foram correspondidos pela regra e estes 
+parâmetros serão disponibilizados logo a seguir no `$_GET` pelo componente da 
+aplicação `request`.
+
+Vamos utilizar alguns exemplos para demonstrar como os parâmetros nomeados 
+funcionam. Supondo que declaramos as três regras a seguir:
+
+```php
+[
+    'posts/<year:\d{4}>/<category>' => 'post/index',
+    'posts' => 'post/index',
+    'post/<id:\d+>' => 'post/view',
+]
+```
+
+Quando as regras forem utilizadas para analisar as URLs:
+
+- `/index.php/posts` obterá a rota `post/index` usando a segunda regra;
+- `/index.php/posts/2014/php` obterá a rota `post/index`, o parâmetro `year` 
+  cujo o valor é 2014 e o parâmetro `category` cujo valor é `php` usando a primeira regra;
+- `/index.php/post/100` obterá a rota `post/view` e o parâmetro `id` cujo valor  
+  é 100 usando a terceira regra;
+- `/index.php/posts/php` causará uma exceção [[yii\web\NotFoundHttpException]] 
+  quando a propriedade [[yii\web\UrlManager::enableStrictParsing]] for `true`, 
+  por não ter correspondido a nenhum dos padrões. Se a propriedade 
+  [[yii\web\UrlManager::enableStrictParsing]] for `false` (o valor padrão), o 
+  caminho `posts/php` será retornado como uma rota.
+ 
+E quando as regras fores utilizadas para criar as URLs:
+
+- `Url::to(['post/index'])` cria `/index.php/posts` usando a segunda regra;
+- `Url::to(['post/index', 'year' => 2014, 'category' => 'php'])` cria `/index.php/posts/2014/php` usando a primeira regra;
+- `Url::to(['post/view', 'id' => 100])` cria `/index.php/post/100` usando a terceira regra;
+- `Url::to(['post/view', 'id' => 100, 'source' => 'ad'])` cria `/index.php/post/100?source=ad` usando a terceira regra.
+  Pela razão do parâmetro `source` não foi especificado na regra, ele será acrescentado como uma query string na criação da URL.
+- `Url::to(['post/index', 'category' => 'php'])` cria `/index.php/post/index?category=php` usando nenhuma das regras.
+  Observe que, se nenhuma das regras forem aplicadas, a URL será criada simplesmente 
+  como a rota sendo o caminho e todos os parâmetros como query string.
+
+
+### Parametrizando Rotas <span id="parameterizing-routes"></span>
+
+Você pode incorporar nomes de parâmetros na rota de uma regra de URL. Isto permite 
+que uma regra de URL seja utilizada para combinar diversas rotas. Por exemplo, a 
+regra a seguir incorpora os parâmetros `controller` e `action` nas rotas.
+
+```php
+[
+    '<controller:(post|comment)>/<id:\d+>/<action:(create|update|delete)>' => '<controller>/<action>',
+    '<controller:(post|comment)>/<id:\d+>' => '<controller>/view',
+    '<controller:(post|comment)>s' => '<controller>/index',
+]
+```
+
+Para analisar uma URL `/index.php/comment/100/create`, a primeira regra será 
+aplicada, na qual foi definida o parâmetro `controller` para ser `comment` e o 
+parâmetro `action` para ser `create`. Sendo assim, a rota `<controller>/<action>` 
+é resolvida como `comment/create`.
+ 
+De forma similar, para criar uma URL com a rota `comment/index`, a terceira regra 
+será aplicada, criando um URL `/index.php/comments`.
+
+> Informação: Pela parametrização de rotas, é possível reduzir significativamente 
+  o número de regras de URL, que também pode melhorar o desempenho do 
+  [[yii\web\UrlManager|gerenciador de URL]]. 
+  
+Por padrão, todos os parâmetros declarados nas regras são obrigatórios. Se uma
+URL da requisição não contiver um dos parâmetros em particular, ou se a URL está 
+sendo criado sem um dos parâmetros em particular, a regra não será aplicada. Para 
+fazer com que algum parâmetro em particular seja opcional, você pode configurar 
+a propriedade [[yii\web\UrlRule::defaults|defaults]] da regra. Os parâmetros
+listados nesta propriedade são opcionais e serão utilizados quando os mesmos não 
+forem fornecidos.
+
+A declaração da regra a seguir, ambos os parâmetros `page` e `tag` são opcionais 
+e utilizarão o valor 1 e a string vazia, respectivamente, quando não forem fornecidos.
+
+```php
+[
+    // ...outras regras...
+    [
+        'pattern' => 'posts/<page:\d+>/<tag>',
+        'route' => 'post/index',
+        'defaults' => ['page' => 1, 'tag' => ''],
+    ],
+]
+```
+
+A regra anterior pode ser usado para analisar ou criar qualquer uma das seguintes URLs:
+
+* `/index.php/posts`: `page` é 1, `tag` é ''.
+* `/index.php/posts/2`: `page` é 2, `tag` is ''.
+* `/index.php/posts/2/news`: `page` é 2, `tag` é `'news'`.
+* `/index.php/posts/news`: `page` é 1, `tag` é `'news'`.
+
+Sem o uso dos parâmetros opcionais, você deveria criar 4 regras para alcançar o 
+mesmo resultado.
+
+
+### Regras com Domínios <span id="rules-with-server-names"></span>
+
+É possível incluir domínios nos padrões das regras de URL. Isto é útil quando sua
+aplicação se comporta de forma diferente em diferentes domínios. Por exemplo, a 
+regra a seguir obtém a rota `admin/user/login` pela análise da URL 
+`http://admin.example.com/login` e a rota `site/login` pela análise da URL 
+`http://www.example.com/login`.
+
+```php
+[
+    'http://admin.example.com/login' => 'admin/user/login',
+    'http://www.example.com/login' => 'site/login',
+]
+```
+
+Você também pode incorporar parâmetros nos domínios para extrair informações 
+dinamicamente a partir deles. Por exemplo, a regra a seguir obtém a rota 
+`post/index` e o parâmetro `language=en` pela análise da URL `http://en.example.com/posts`
+
+```php
+[
+    'http://<language:\w+>.example.com/posts' => 'post/index',
+]
+```
+
+> Observação: Regras com domínios NÃO devem ser incluídos com subpastas do script 
+  de entrada em seus padrões. Por exemplo, se a aplicação estiver sob 
+  `http://www.example.com/sandbox/blog`, você deve usar o padrão 
+  `http://www.example.com/posts` ao invés de `http://www.example.com/sandbox/blog/posts`. 
+  Isto permite que sua aplicação seja implantado sob qualquer diretório sem a 
+  necessidade de alterar o código da aplicação.
+
+
+### Sufixos da URL <span id="url-suffixes"></span>
+
+Você pode querer adicionar sufixos nas URLs para diversos fins. Por exemplo, 
+você pode adicionar o `.html` nas URLs para que se pareçam com páginas estáticas. 
+Você também pode adicionar o `.json` nas URLs para indicar o tipo de conteúdo 
+esperado na resposta. Você pode alcançar este objetivo configurando a propriedade 
+[[yii\web\UrlManager::suffix]] na configuração da aplicação conforme o exemplo a seguir:
+
+```php
+[
+    'components' => [
+        'urlManager' => [
+            'enablePrettyUrl' => true,
+            'showScriptName' => false,
+            'enableStrictParsing' => true,
+            'suffix' => '.html',
+            'rules' => [
+                // ...
+            ],
+        ],
+    ],
+]
+```
+
+A configuração anterior permitirá que o [[yii\web\UrlManager|gerenciador de URL]] 
+reconheçam as URLs solicitadas e que também criem URLs com o prefixo `.html`.
+
+> Dica: Você pode definir `/` como o sufixo para que todas as URLs terminem com barra.
+
+> Observação: Ao configurar um sufixo da URL e a URL da requisição não conter um, 
+  será considerado como uma URL não válida. Isto é uma prática recomendada no 
+  SEO (otimização para mecanismos de pesquisa, do *inglês search engine optimization*).
+
+Ás vezes você poder querer utilizar diferentes sufixos para diferentes URLs.
+Isto pode ser alcançado pela configuração da propriedade 
+[[yii\web\UrlRule::suffix|suffix]] individualmente para cada regra de URL. 
+Quando uma regra de URL possuir esta propriedade definida, sobrescreverá o 
+sufixo que foi definido da camada do [[yii\web\UrlManager|gerenciador de URL]]. 
+Por exemplo, a configuração a seguir contém uma regra de URL personalizada que 
+usa o `.json` como sufixo ao invés do sufixo `.html` definido globalmente.
+
+```php
+[
+    'components' => [
+        'urlManager' => [
+            'enablePrettyUrl' => true,
+            'showScriptName' => false,
+            'enableStrictParsing' => true,
+            'suffix' => '.html',
+            'rules' => [
+                // ...
+                [
+                    'pattern' => 'posts',
+                    'route' => 'post/index',
+                    'suffix' => '.json',
+                ],
+            ],
+        ],
+    ],
+]
+```
+
+
+### Métodos HTTP <span id="http-methods"></span>
+
+Ao implementar RESTful API, é necessário que sejam obtidas rotas diferentes pela 
+análise de uma mesma URL de acordo com o método HTTP utilizado. Isto pode ser 
+alcançado facilmente adicionando o prefixo do método HTTP suportado, separando 
+os nomes dos métodos por vírgulas. Por exemplo, a regra a seguir possui o mesmo 
+padrão `post/<id:\d+>` com suporte a diferentes métodos HTTP. A análise de uma
+requisição `PUT post/100` obterá a rota `post/create`, enquanto a requisição 
+`GET post/100` obterá a rota `post/view`.
+
+```php
+[
+    'PUT,POST post/<id:\d+>' => 'post/create',
+    'DELETE post/<id:\d+>' => 'post/delete',
+    'post/<id:\d+>' => 'post/view',
+]
+```
+
+> Observação: Se uma regra de URL contiver método(s) HTTP, esta regra só será 
+utilizada para análises de URLs. A regra será ignorada quando o 
+[[yii\web\UrlManager|gerenciador de URL]] for chamado para criar URLs.
+
+> Dica: Para simplificar o roteamento do RESTful APIs, o Yii fornece uma classe 
+especial [[yii\rest\UrlRule]] de regras que é muito diferente. Esta classe 
+suporta muitos recursos como a pluralização automática de IDs do controller 
+(controlador). Para mais detalhes, por favor, consulte a seção 
+[Routing](rest-routing.md) sobre o desenvolvimento de RESTful APIs.
+
+
+### Regras Personalizadas <span id="customizing-rules"></span>
+
+Nos exemplo anteriores, as regras de URL são declaradas principalmente no formato
+de pares de padrão-rota. Este é um formato de atalho bastante utilizado. Em 
+alguns cenários, você pode querer personalizar uma regra de URL configurando 
+outras propriedades, tais como o [[yii\web\UrlRule::suffix]]. Isto pode ser 
+feito utilizando um array de configuração para especificar uma regra. O exemplo 
+a seguir foi retirado da subseção [Sufixos da URL](#url-suffixes),
+
+```php
+[
+    // ...outras regras de URL...
+    
+    [
+        'pattern' => 'posts',
+        'route' => 'post/index',
+        'suffix' => '.json',
+    ],
+]
+```
+
+> Informações: Por padrão, se você não especificar a opção `class` na configuração 
+  de uma regra, será usado como padrão a classe [[yii\web\UrlRule]].
+  
+
+### Adicionando Regras Dinamicamente <span id="adding-rules"></span>
+
+As regras de URL podem ser adicionadas dinamicamente ao [[yii\web\UrlManager|gerenciador de URL]]. 
+Esta técnica muitas vezes se faz necessária em [módulos](structure-modules.md) que 
+são redistribuídos e que desejam gerenciar as suas próprias regras de URL. Para 
+que estas regras sejam adicionadas dinamicamente e terem efeito durante o processo 
+de roteamento, você pode adiciona-los durante a [inicialização (bootstrapping)](runtime-bootstrapping.md). 
+Para os módulos, significa que deve implementar a interface [[yii\base\BootstrapInterface]] 
+e adicionar as regras no método [[yii\base\BootstrapInterface::bootstrap()|bootstrap()]] 
+conforme o exemplo a seguir:
+
+```php
+public function bootstrap($app)
+{
+    $app->getUrlManager()->addRules([
+        // declare as regras aqui
+    ], false);
+}
+```
+
+Observe que você também deve listar estes módulos no [[yii\web\Application::bootstrap]]
+para que eles sejam usados no processo de [inicialização (bootstrapping)](runtime-bootstrapping.md)
+
+
+### Criando Classes de Regras <span id="creating-rules"></span>
+
+Apesar do fato que a classe padrão [[yii\web\UrlRule]] é flexível o suficiente 
+para a maior parte dos projetos, há situações em que você terá que criar a sua 
+própria classe de regra. Por exemplo, em um site de venda de carros, você pode 
+querer dar suporte a um formato de URL como `/Manufacturer/Model`, que tanto o 
+`Manufacturer` quanto o `Model` devem coincidir com os dados armazenados em uma 
+tabela do banco de dados. A classe de regra padrão não vai funcionar nesta 
+situação pois vão se basear em padrões estaticamente declarados.
+
+Podemos criar uma classe de regra de URL para resolver este formato.
+
+```php
+namespace app\components;
+
+use yii\web\UrlRuleInterface;
+use yii\base\Object;
+
+class CarUrlRule extends Object implements UrlRuleInterface
+{
+
+    public function createUrl($manager, $route, $params)
+    {
+        if ($route === 'car/index') {
+            if (isset($params['manufacturer'], $params['model'])) {
+                return $params['manufacturer'] . '/' . $params['model'];
+            } elseif (isset($params['manufacturer'])) {
+                return $params['manufacturer'];
+            }
+        }
+        return false;  // esta regra não se aplica
+    }
+
+    public function parseRequest($manager, $request)
+    {
+        $pathInfo = $request->getPathInfo();
+        if (preg_match('%^(\w+)(/(\w+))?$%', $pathInfo, $matches)) {
+            // checa o $matches[1] e $matches[3] para verificar
+            // se coincidem com um *fabricante* e um *modelo* no banco de dados.
+            // Caso coincida, define o $params['manufacturer'] e/ou $params['model']
+            // e retorna ['car/index', $params]
+        }
+        return false;  // esta regra não se aplica
+    }
+}
+```
+
+E utilize esta nova classe de regra na configuração [[yii\web\UrlManager::rules]]:
+
+```php
+[
+    // ...outras regras...
+    
+    [
+        'class' => 'app\components\CarUrlRule', 
+        // ...configurar outras propriedades...
+    ],
+]
+```
+
+
+## Considerando Performance <span id="performance-consideration"></span>
+
+Ao desenvolver uma aplicação Web complexa, é importante otimizar as regras de URL 
+para que leve menos tempo na análise de requisições e criação de URLs.
+
+Utilizando rotas parametrizadas, você reduz o número de regras de URL, na qual 
+pode melhorar significativamente o desempenho.
+
+Na análise e criação de URLs, o [[yii\web\UrlManager|gerenciador de URL]] examina 
+as regras de URL na ordem em que foram declaradas.
+Portanto, você pode considerar ajustar a ordem destas regras, fazendo com que as
+regras mais específicas e/ou mais comuns sejam colocadas antes que os menos.
+
+Se algumas regras de URL compartilharem o mesmo prefixo em seus padrões ou rotas, 
+você pode considerar utilizar o [[yii\web\GroupUrlRule]] para que sejam examinados 
+de forma mais eficiente pelo [[yii\web\UrlManager|gerenciador de URL]] como um 
+grupo. Normalmente é o caso de aplicações compostos por módulos, onde cada módulo
+possui o seu próprio conjunto de regras de URL utilizando o ID do módulo como 
+prefixo comum.