Usando Extensões

A utilização de uma extensão normalmente envolve os seguintes passos:

1. Faça o download da extensão no repositório do Yii.
2. Descompacte a extensão no diretório extensions/xyz, dentro do diretório base da aplicação, onde xyz é o nome da extensão.
3. Importe, configure e utilize a extensão.

Cada extensão tem um nome que a identifica unicamente. Dada uma extensão chamada xyz, podemos sempre utilizar o path alias ext.xyz para localizar seu diretório base, que contém todos os arquivos de xyz.

Nota: O path alias ext está disponível a partir da versão 1.0.8. Nas versões anteriores, precisávamos utilizar application.extensions para nos referir ao diretório base das extensões. Nos exemplos a seguir, vamos assumir que ext está definido, Caso você utilize a versão 1.0.7, ou anterior, substitua o path alias por aaplication.extensions.

Extensões diferentes tem requisitos diferentes para importação, configuração e utilização. Abaixo, resumimos os tipos mais comuns de utilização de extensões, de acordo com as categorias descritas na visão geral.

1. Extensões Zii ¶

Antes de descrever a utilização de extensões de terceiros, gostariamos de apresentar a biblioteca de extensões Zii. Trata-se de um conjunto de extensões criadas pelo time de desenvolvedores do Yii e é incluída em todos os lançamentos do framework, a partir da versão 1.1.0. Essa biblioteca está hospedada no Google Code, no projeto chamado zii.

Ao utilizar uma das extensões da Zii, você deve utilizar um path alias para fazer referências às classes correspondentes, no formato zii.caminho.para.NomeDaClasse. O alias zii é definido pelo framework e aponta para o diretório raiz da biblioteca Zii. Por exemplo, para utilizar a extensão CGridView, devemos utilizar o seguinte código em uma view:

$this->widget('zii.widgets.grid.CGridView', array(
    'dataProvider'=>$dataProvider,
));

2. Componente de Aplicação ¶

Para utilizar um componente de aplicação, primeiro precisamos alterar a configuração da aplicação adicionando uma nova entrada na propriedade components, como no código abaixo:

return array(
    // 'preload'=>array('xyz',...),
    'components'=>array(
        'xyz'=>array(
            'class'=>'ext.xyz.XyzClass',
            'property1'=>'value1',
            'property2'=>'value2',
        ),
        // configurações de outros componentes
    ),
);

Dessa forma, podemos acessar o componente em qualquer lugar utilizando Yii::app()->xyz. O componente será criado somente quando for acessado pela primeira vez, a não ser que ele tenha sido adicionado na propriedade preload.

3. Comportamento ¶

Comportamentos podem ser utilizados em todos os tipos de componentes. O processo é realizado em dois passos. No primeiro, um comportamento é atribuído a um componente. No segundo, um método do comportamento é executado através do componente. Por exemplo:

// $nome identifica o comportamento dentro do componente
$componente->attachBehavior($nome, $comportamento);
// test() é um método de $comportamento
$componente->test();

Na maioria das vezes, um comportamento é atribuído a um componente através de configurações, em vez de utilizar o método attachBehavior. Por exemplo, para atribuir um comportamento a um componente da aplicação, podemos utilizar a seguinte configuração:

return array(
    'components'=>array(
        'db'=>array(
            'class'=>'CDbConnection',
            'behaviors'=>array(
                'xyz'=>array(
                    'class'=>'ext.xyz.XyzComportamento',
                    'propriedade1'=>'valor1',
                    'propriedade2'=>'valor2',
                ),
            ),
        ),
        //....
    ),
);

No exemplo acima, o comportamento xyz é atribuído ao componente db. Essa forma de atribuição é possível porque a classe CApplicationComponent define uma propriedade chamada behaviors. Ao atribuir a ela uma lista de configurações de comportamentos, o componente irá anexa-los quando for inicializado.

Para as classes CController, CFormModel e CActiveModel, que, normalmente, necessitam ser estendidas, a atribuição de comportamentos é feita sobrescrevendo-se o método behaviors(). Qualquer comportamento desclarado nesse método será automaticamente anexo à classe. Por exemplo:

public function behaviors()
{
    return array(
        'xyz'=>array(
            'class'=>'ext.xyz.XyzComportamentos',
            'propriedade1'=>'valor1',
            'propriedade2'=>'valor2',
        ),
    );
}

4. Widget ¶

Widgets são utilizados principalmente nas visões. Dada uma classe widget, chamada XyzClass, pertencente a extensão xyz, podemos utiliza-la da seguinte maneira:

// um widget que não precisa de conteúdo para seu corpo
<?php $this->widget('ext.xyz.XyzClass', array(
    'property1'=>'value1',
    'property2'=>'value2')); ?>
 
// um widget que precisa de conteúdo para o seu corpo
<?php $this->beginWidget('ext.xyz.XyzClass', array(
    'property1'=>'value1',
    'property2'=>'value2')); ?>
 
...conteúdo do corpo do widget...
 
<?php $this->endWidget(); ?>

5. Ação ¶

Ações são utilizadas por um controle para responder à uma requisição específica do usuário. Dada a classe da ação XyzClass, pertencente a extensão xyz, podemos utiliza-la sobrescrevendo o método CController::actions na classe de nosso controle:

class TestController extends CController
{
    public function actions()
    {
        return array(
            'xyz'=>array(
                'class'=>'ext.xyz.XyzClass',
                'property1'=>'value1',
                'property2'=>'value2',
            ),
            // outras ações
        );
    }
}

Dessa forma, a ação pode ser acessada através da rota test/xyz.

6. Filtro ¶

Filtros também são utilizados por um controle. Basicamente eles pré e pós processam a requisição do usuário manuseada por uma ação. Dada a classe do filtro XyzClass, pertencente a extensão xyz, podemos utiliza-la sobrescrevendo o método CController::filters, na classe de nosso controle.

class TestController extends CController
{
    public function filters()
    {
        return array(
            array(
                'ext.xyz.XyzClass',
                'property1'=>'value1',
                'property2'=>'value2',
            ),
            // outros filtros
        );
    }
}

No exemplo acima, podemos utilizar no primeiro elemento do vetor os operadores + e -, para limitar as ações onde o filtro será aplicado. Para mais detalhes, veja a documentação da classe CController.

7. Controle ¶

Um controle, fornece um conjunto de ações que podem ser requisitadas pelos usuários. Para utilizar uma extensão de um controle, precisamos configurar a propriedade CWebApplication::controllerMap na configuração da aplicação:

return array(
    'controllerMap'=>array(
        'xyz'=>array(
            'class'=>'ext.xyz.XyzClass',
            'property1'=>'value1',
            'property2'=>'value2',
        ),
        // outros controles
    ),
);

Dessa forma, uma ação a no controle pode ser acessada pela rota xyz/a.

8. Validador ¶

Um validador é utilizado principalmente na classe de um modelo (que estenda de CFormModel ou CActiveRecord). Dada a classe de um validador chamada XyzClass, pertencente a extensão xyz, podemos utiliza-la sobrescrevendo o método CModel::rules na classe de nosso modelo:

class MyModel extends CActiveRecord // ou CFormModel
{
    public function rules()
    {
        return array(
            array(
                'attr1, attr2',
                'ext.xyz.XyzClass',
                'property1'=>'value1',
                'property2'=>'value2',
            ),
            // outras regras de validação
        );
    }
}

9. Comando de Console ¶

Uma extensão do tipo comando de console, normalmente é utilizada para adicionar comandos à ferramenta yiic. Dado um comando de console XyzClass, pertencente à extensão xyz, podemos utiliza-lo o adicionando nas configurações da aplicação de console:

return array(
    'commandMap'=>array(
        'xyz'=>array(
            'class'=>'ext.xyz.XyzClass',
            'property1'=>'value1',
            'property2'=>'value2',
        ),
        // outros comandos
    ),
);

Dessa forma, podemos utilizar o comando xyz na ferramenta yiic.

Nota: Uma aplicação de console normalmente utiliza um arquivo de configuração diferente do utilizado pela aplicação web. Se uma aplicação foi criada utilizando o comando yiic webapp, o arquivo de configurações para o console estará em protected/config/console.php, enquanto o arquivo de configuração para a aplicação web estará em protected/config/main.php.

10. Módulo ¶

Para utilizar módulos, por favor, veja a seção sobre módulos.

11. Componente Genérico ¶

Para utilizar um componente, primeiro precisamos incluir seu arquivo de classe, utilizando:

Yii::import('ext.xyz.XyzClass');

Feito isso, podemos criar uma instância dessa classe, configurar suas propriedades e chamar seus métodos. Podemos também estendê-lo para criar novas classes.