You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
130 lines
7.0 KiB
130 lines
7.0 KiB
9 years ago
|
Controllers (Controladores)
|
||
|
===========
|
||
|
|
||
|
Depois de criar as classes de recursos e especificar como os dados de recursos devem ser formatados, a próxima coisa a fazer é criar ações do controller para expor os recursos para os usuários finais através das APIs RESTful.
|
||
|
|
||
|
Yii fornece duas classes básicas de controller para simplificar seu trabalho de criar ações RESTful: [[yii\rest\Controller]] e [[yii\rest\ActiveController]]. A diferença entre os dois controllers é que o último fornece um conjunto padrão de ações que são especificamente concebidos para lidar com recursos do [Active Record](db-active-record.md). Então, se você estiver usando [Active Record](db-active-record.md) e está confortável com as ações fornecidas, você pode considerar estender suas classes de controller de [[yii\rest\ActiveController]], que permitirá a você criar poderosas APIs RESTful com um mínimo de código.
|
||
|
|
||
|
Ambos [[yii\rest\Controller]] e [[yii\rest\ActiveController]] fornecem os seguintes recursos, algumas das quais serão descritas em detalhes nas próximas seções:
|
||
|
|
||
|
* Validação de Método HTTP;
|
||
|
* [Negociação de conteúdo e formatação de dados](rest-response-formatting.md);
|
||
|
* [Autenticação](rest-authentication.md);
|
||
|
* [limitação de taxa](rest-rate-limiting.md).
|
||
|
|
||
|
[[yii\rest\ActiveController]] oferece também os seguintes recursos:
|
||
|
|
||
|
* Um conjunto de ações comumente necessárias: `index`, `view`, `create`, `update`, `delete`, `options`;
|
||
|
* Autorização do usuário em relação à ação solicitada e recursos.
|
||
|
|
||
|
|
||
|
## Criando Classes Controller <span id="creating-controller"></span>
|
||
|
|
||
|
Ao criar uma nova classe de controller, uma convenção em nomear a classe é usar o nome do tipo de recurso no singular. Por exemplo, para disponibilizar as informações do usuário, o controlador pode ser nomeado como `UserController`. Criar uma nova ação é semelhante à criação de uma ação de uma aplicação Web. A única diferença é que em vez de renderizar o resultado usando uma view e chamando o método `render()`, para ações RESTful você retorna diretamente os dados. O [[yii\rest\Controller::serializer|serializer]] e o [[yii\web\Response|response object]] vão converter os dados originais para o formato solicitado. Por exemplo,
|
||
|
|
||
|
```php
|
||
|
public function actionView($id)
|
||
|
{
|
||
|
return User::findOne($id);
|
||
|
}
|
||
|
```
|
||
|
|
||
|
|
||
|
## Filtros <span id="filters"></span>
|
||
|
|
||
|
A maioria dos recursos da API RESTful fornecidos por [[yii\rest\Controller]] são implementadas nos termos de [filters](structure-filters.md).
|
||
|
Em particular, os seguintes filtros serão executados na ordem em que estão listados:
|
||
|
|
||
|
* [[yii\filters\ContentNegotiator|contentNegotiator]]: suporta a negociação de conteúdo, a ser explicado na seção [Formatação de Resposta](rest-response-formatting.md);
|
||
|
* [[yii\filters\VerbFilter|verbFilter]]: suporta validação de métodos HTTP;
|
||
|
* [[yii\filters\AuthMethod|authenticator]]: suporta autenticação de usuários, que será explicado na seção [Autenticação](rest-authentication.md);
|
||
|
* [[yii\filters\RateLimiter|rateLimiter]]: suporta limitação de taxa, que será explicado na seção
|
||
|
[Limitação de taxa](rest-rate-limiting.md).
|
||
|
|
||
|
Estes filtros são declarados no método [[yii\rest\Controller::behaviors()|behaviors()]].
|
||
|
Você pode sobrescrever esse método para configurar alguns filtros, desativar outros, ou adicionar seus próprios filtros. Por exemplo, se você precisar somente de autenticação básica de HTTP, pode-se utilizar o seguinte código:
|
||
|
|
||
|
```php
|
||
|
use yii\filters\auth\HttpBasicAuth;
|
||
|
|
||
|
public function behaviors()
|
||
|
{
|
||
|
$behaviors = parent::behaviors();
|
||
|
$behaviors['authenticator'] = [
|
||
|
'class' => HttpBasicAuth::className(),
|
||
|
];
|
||
|
return $behaviors;
|
||
|
}
|
||
|
```
|
||
|
|
||
|
|
||
|
## Estendendo `ActiveController` <span id="extending-active-controller"></span>
|
||
|
|
||
|
Se a sua classe controller estende de [[yii\rest\ActiveController]], você deve configurar a propriedade [[yii\rest\ActiveController::modelClass||modelClass]] para ser o nome da classe de recurso que você pretende servir através deste controller. A classe deve estender de [[yii\db\ActiveRecord]].
|
||
|
|
||
|
|
||
|
### Customizando Ações <span id="customizing-actions"></span>
|
||
|
|
||
|
Por padrão, [[yii\rest\ActiveController]] fornece as seguintes ações:
|
||
|
|
||
|
* [[yii\rest\IndexAction|index]]: recursos de lista página por página;
|
||
|
* [[yii\rest\ViewAction|view]]: retorna os detalhes de um recurso especificado;
|
||
|
* [[yii\rest\CreateAction|create]]: cria um novo recurso;
|
||
|
* [[yii\rest\UpdateAction|update]]: atualiza um recurso existente;
|
||
|
* [[yii\rest\DeleteAction|delete]]: excluir o recurso especificado;
|
||
|
* [[yii\rest\OptionsAction|options]]: retorna os métodos HTTP suportados.
|
||
|
|
||
|
Todas essas ações são declarados através do método [[yii\rest\ActiveController::actions()|actions()]]. Você pode configurar essas ações ou desativar alguns delas, sobrescrevendo o método `actions()`, como mostrado abaixo,
|
||
|
|
||
|
```php
|
||
|
public function actions()
|
||
|
{
|
||
|
$actions = parent::actions();
|
||
|
|
||
|
// desabilita as ações "delete" e "create"
|
||
|
unset($actions['delete'], $actions['create']);
|
||
|
|
||
|
// customiza a preparação do data provider com o método "prepareDataProvider()"
|
||
|
$actions['index']['prepareDataProvider'] = [$this, 'prepareDataProvider'];
|
||
|
|
||
|
return $actions;
|
||
|
}
|
||
|
|
||
|
public function prepareDataProvider()
|
||
|
{
|
||
|
// preparar e retornar um data provider para a ação "index"
|
||
|
}
|
||
|
```
|
||
|
|
||
|
Por favor, consulte as referências de classe para classes de ação individual para saber as opções de configuração que estão disponíveis.
|
||
|
|
||
|
|
||
|
### Executando Verificação de Acesso <span id="performing-access-check"></span>
|
||
|
|
||
|
Ao disponibilizar recursos por meio de APIs RESTful, muitas vezes você precisa verificar se o usuário atual tem permissão para acessar e manipular o(s) recurso(s) solicitado(s). Com [[yii\rest\ActiveController]], isso pode ser feito sobrescrevendo o método [[yii\rest\ActiveController::checkAccess()|checkAccess()]] conforme abaixo,
|
||
|
|
||
|
```php
|
||
|
/**
|
||
|
* verifica os privilégios do usuário corrente.
|
||
|
*
|
||
|
* Este método deve ser sobrescrito para verificar se o usuário atual tem o privilégio
|
||
|
* para executar a ação especificada diante do modelo de dados especificado.
|
||
|
* se o usuário não tiver acesso, uma [[ForbiddenHttpException]] deve ser lançada.
|
||
|
*
|
||
|
* @param string $action the ID of the action to be executed
|
||
|
* @param \yii\base\Model $model o model a ser acessado. Se null, isso significa que nenhum model específico está sendo acessado.
|
||
|
* @param array $params additional parameters
|
||
|
* @throws ForbiddenHttpException if the user does not have access
|
||
|
*/
|
||
|
public function checkAccess($action, $model = null, $params = [])
|
||
|
{
|
||
|
// verifica se o usuário pode acessar $action and $model
|
||
|
// lança a ForbiddenHttpException se o acesso for negado
|
||
|
}
|
||
|
```
|
||
|
|
||
|
O método `checkAccess()` será chamado pelas ações padrões do [[yii\rest\ActiveController]]. Se você criar novas ações e também deseja executar verificação de acesso, você deve chamar esse método explicitamente nas novas ações.
|
||
|
|
||
|
> Dica: Você pode implementar `checkAccess()` usando o [Role-Based Access Control (RBAC) component](security-authorization.md).
|
||
|
|