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. 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.

2. 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(). Por exemplo:

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

3. 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(); ?>

4. 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.

5. 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.

6. Controle ¶

Um controle, fornece um conjunto de ações que podem ser requisitadas pelos usuários. Para utilizar um 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.

7. 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
        );
    }
}

8. 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.

9. Módulo ¶

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

10. 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.