yii2/docs/guide-pt-BR/intro-upgrade-from-v1.md

Atualizando a partir da Versão 1.1

Existem muitas diferenças entre as versões 1.1 e 2.0 do Yii, uma vez que o framework foi completamente reescrito no 2.0. Por causa disso, atualizar a partir da versão 1.1 não é tão trivial quanto atualizar de versões menores. Neste guia você encontrará as principais diferenças entre as duas versões.

Se você nunca usou o Yii 1.1 antes, você pode pular com segurança esta seção e ir diretamente para "Instalando o Yii".

Por favor perceba que o Yii 2.0 introduz mais novas funcionalidades do que as que são abordadas neste resumo. Recomenda-se fortemente que você leia completamente o guia definitivo para aprender todas elas. É possível que algumas das funcionalidades que antes você tinha que desenvolver por conta própria agora sejam partes do código principal.

Instalação

O Yii 2.0 adota plenamente o Composer, o gerenciador de pacotes PHP. Tanto a instalação do núcleo do framework quanto das extensões são gerenciados através do Composer. Por favor consulte a seção Instalando o Yii para aprender como instalar o Yii 2.0. Se você quiser criar novas extensões, ou tornar compatíveis as suas extensões existentes do 1.1 com o 2.0, por favor consulte a seção Criando Extensões do guia.

Requisitos do PHP

O Yii 2.0 requer o PHP 5.4 ou superior, que é uma grande melhoria sobre a versão 5.2 do PHP, que era exigida pelo Yii 1.1. Como resultado, existem muitas diferenças a nível de linguagem às quais você deveria prestar atenção. Segue abaixo um resumo das principais mudanças no que diz respeito ao PHP:

• Namespaces.
• Funções anônimas.
• A sintaxe curta de arrays [...elementos...] é utilizada ao invés de array(...elementos...).
• Tags curtas de echo <?= são usadas nos arquivos de view (visão). É seguro utilizá-las a partir do PHP 5.4.
• Classes e interfaces da SPL.
• Late Static Bindings.
• Date e Time.
• Traits.
• intl. O Yii 2.0 utiliza a extensão intl do PHP para suportar as funcionalidades de internacionalização.

Namespace

A mudança mais óbvia no Yii 2.0 é o uso de namespaces. Praticamente todas as classes do core possuem namespace, por exemplo, yii\web\Request. O prefixo "C" não é mais utilizado nos nomes de classes. O esquema de nomenclatura agora segue a estrutura de diretórios. Por exemplo, yii\web\Request indica que o arquivo da classe correspondente é web/Request.php sob a pasta do Yii Framework.

(Você pode utilizar qualquer classe do core sem explicitamente incluir o arquivo dessa classe, graças ao carregador de classes do Yii).

Component e Object

O Yii 2.0 divide a classe CComponent do 1.1 em duas classes: yii\base\Object e yii\base\Component. A classe yii\base\Object é uma classe base leve que permite a definição das propriedades de objetos via getters e setters. A classe yii\base\Component estende de yii\base\Object e suporta eventos e behaviors (comportamentos).

Se a sua classe não precisa da funcionalidade de eventos e behaviors, você deveria considerar utilizar yii\base\Object como classe base. Esse geralmente é o caso de classes que representam estruturas básicas de dados.

Configuração de Objetos

A classe yii\base\Object introduz uma maneira uniforme de configurar objetos. Qualquer classe descendente de yii\base\Object deveria declarar seu construtor (se necessário) da seguinte maneira, para que ela seja configurada adequadamente:

class MinhaClasse extends \yii\base\Object
{
    public function __construct($param1, $param2, $config = [])
    {
        // ... inicialização antes da configuração ser aplicada

        parent::__construct($config);
    }

    public function init()
    {
        parent::init();

        // ... inicialização depois da configuração ser aplicada
    }
}

No código acima, o último parâmetro do construtor deve receber um array de configuração que contém pares de nome-valor para a inicialização das propriedades no final do construtor. Você pode sobrescrever o método yii\base\Object::init() para fazer o trabalho de inicialização que deve ser feito após a configuração ter sido aplicada.

Seguindo esta convenção, você poderá criar e configurar novos objetos usando um array de configuração:

$object = Yii::createObject([
    'class' => 'MinhaClasse',
    'property1' => 'abc',
    'property2' => 'cde',
], [$param1, $param2]);

Mais detalhes sobre configurações podem ser encontradas na seção Configurações de Objetos.

Eventos

No Yii 1, os eventos eram criados definindo-se um método on-alguma-coisa (por exemplo, onBeforeSave). No Yii 2, agora você pode usar qualquer nome de evento. Você dispara um evento chamando o método yii\base\Component::trigger():

$evento = new \yii\base\Event;
$componente->trigger($nomeDoEvento, $evento);

Para anexar um handler a um evento, use o método yii\base\Component::on():

$componente->on($nomeDoEvento, $handler);
// Para desanexar o handler, utilize:
// $componente->off($nomeDoEvento, $handler);

Existem muitas melhorias das funcionalidades de eventos. Para mais detalhes, por favor consulte a seção Eventos.

Path Aliases

O Yii 2.0 expande o uso de path aliases (apelidos de caminhos) para caminhos de arquivos e diretórios e URLs. O Yii 2.0 agora também requer que um nome de alias comece com o caractere @, para diferenciar aliases de caminhos e URLs normais de arquivos e diretórios. Por exemplo, o alias @yii se refere ao diretório de instalação do Yii. Os path aliases são suportados na maior porte do código do core do Yii. Por exemplo, o método yii\caching\FileCache::cachePath pode receber tanto um path alias quanto um caminho de diretório normal.

Um path alias também está intimamente relacionado a um namespace de classe. Recomenda-se que um path alias seja definido para cada namespace raiz, desta forma permitindo que você use o auto-carregamento de classes do Yii sem qualquer configuração adicional. Por exemplo, como @yii se refere ao diretório de instalação do Yii, uma classe como yii\web\Request pode ser carregada automaticamente. Se você utilizar uma biblioteca de terceiros, tal como o Zend Framework, você pode definir um path alias @Zend que se refere ao diretório de instalação desse framework. Uma vez que você tenha feito isso, o Yii também poderá carregar automaticamente qualquer classe nessa biblioteca do Zend Framework.

Você pode encontrar mais sobre path aliases na seção Path Aliases.

Views (Visões)

A mudança mais significante das views no Yii 2 é que a variável especial $this em uma view não se refere mais ao controller (controlador) ou widget atual. Ao invés disso, $this agora se refere a um objeto view, um novo conceito introduzido no 2.0. O objeto view é do tipo yii\web\View, que representa a parte da visão do padrão MVC. Se você quiser acessar o controlador (controller) ou o widget em uma visão, você pode utilizar $this->context.

Para renderizar uma visão parcial (partial view) dentro de outra view, você usa $this->render(), e não $this->renderPartial(). Agora a chamada de render também precisa ser explicitamente imprimida com echo, uma vez que o métood render() retorna o resultado da renderização ao invés de exibi-lo diretamente. Por exemplo:

echo $this->render('_item', ['item' => $item]);

Além de utilizar o PHP como linguagem de template principal, o Yii 2.0 também é equipado com suporte oficial a duas populares engines de template: Smarty e Twig. A engine de template do Prado não é mais suportada. Para utilizar essas engines de template, você precisa configurar o componente de aplicação view definindo a propriedade yii\base\View::$renderers. Por favor consulte a seção Template Engines para mais detalhes.

Models (Modelos)

O Yii 2.0 usa a yii\base\Model como modelo base, semelhante à CModel no 1.1. A classe CFormModel foi removida inteiramente. Ao invés dela, no Yii 2 você deve estender a classe yii\base\Model parar criar uma classe de modelo de formulário.

O Yii 2.0 introduz um novo método chamado de yii\base\Model::scenarios() para declarar os cenários suportados, e para indicar sob qual cenário um atributo precisa ser validado, pode ser considerado safe (seguro) ou não, etc. Por exemplo:

public function scenarios()
{
    return [
        'backend' => ['email', 'role'],
        'frontend' => ['email', '!name'],
    ];
}

No código acima, dois cenários são declarados: backend e frontend. Para o cenário backend, os atributos email e role são seguros (safe), e podem ser atribuídos em massa. Para o cenário frontend, email pode ser atribuído em massa enquanto role não. Tanto email quanto role devem ser validados utilizando-se rules (regras).

O método yii\base\Model::rules() ainda é usado para declarar regras de validação. Perceba que devido à introdução do método yii\base\Model::scenarios(), não existe mais o validador unsafe (inseguro).

Na maioria dos casos, você não precisa sobrescrever yii\base\Model::scenarios() se o método yii\base\Model::rules() especifica completamente os cenários que existirão, e se não houver necessidade para declarar atributos unsafe.

Para aprender mais sobre modelos, por favor consulte a seção Models (Modelos).

Controllers (Controladores)

O Yii 2.0 utiliza a yii\web\Controller como classe base dos controllers (controladores), de maneira semelhante à CWebController no Yii 1.1. A yii\base\Action é a classe base para classes de actions (ações).

O impacto mais óbvio destas mudanças em seu código é que uma action de um controller deve sempre retornar o conteúdo que você quer renderizar ao invés de dar echo nele:

public function actionView($id)
{
    $model = \app\models\Post::findOne($id);
    if ($model) {
        return $this->render('view', ['model' => $model]);
    } else {
        throw new \yii\web\NotFoundHttpException;
    }
}

Por favor consulte a seção Controllers (Controladores) para mais detalhes sobre controllers.

Widgets

O Yii 2.0 usa yii\base\Widget como a classe base dos widgets, de maneira semelhante à CWidget no Yii 1.1.

Para obter um melhor suporte ao framework nas IDEs, o Yii 2.0 introduz uma nova sintaxe para utilização de widgets. Os métodos estáticos yii\base\Widget::begin(), yii\base\Widget::end() e yii\base\Widget::widget() foram introduzidos, para serem utilizados do seguinte modo:

use yii\widgets\Menu;
use yii\widgets\ActiveForm;

// Perceba que você tem que dar um "echo" no resultado para exibi-lo
echo Menu::widget(['items' => $items]);

// Passando um array para inicializar as propriedades do objeto
$form = ActiveForm::begin([
    'options' => ['class' => 'form-horizontal'],
    'fieldConfig' => ['inputOptions' => ['class' => 'input-xlarge']],
]);
... campos de entrada do form aqui ...
ActiveForm::end();

Por favor consulte a seção Widgets para mais detalhes.

Temas

Os temas funcionam de maneira completamente diferente no 2.0. Agora eles se baseiam em um mecanismo de mapeamento de caminhos que mapeia um caminho de arquivo de view (visão) fonte a um caminho de arquivo de view com o tema. Por exemplo, se o mapa de caminho de um tema é ['/web/views' => '/web/themes/basic'], então a versão com tema deste arquivo de view /web/views/site/index.php será /web/themes/basic/site/index.php. Por esse motivo, os temas agora podem ser aplicados a qualquer arquivo de view, até mesmo uma view renderizada fora do contexto de um controller ou widget.

Além disso, não há mais um componente CThemeManager. Ao invés disso, theme é uma propriedade configurável do componente de aplicação view.

Por favor consulte a seção Temas para mais detalhes.

Aplicações de Console

As aplicações de console agora são organizadas como controllers (controladores), assim como as aplicações web. Os controllers de console devem estender de yii\console\Controller, de maneira semelhante à CConsoleCommand no 1.1.

Para rodar um comando do console, use yii <rota>, onde <rota> representa a rota de um controller (por exemplo, sitemap/index). Argumentos anônimos adicionais são passados como os parâmetros correspondentes ao método da ação do controller, enquanto argumentos com nome são parseados de acordo com as declarações em yii\console\Controller::options().

O Yii 2.0 suporta a geração automática de informação de ajuda do comando a partir de blocos de comentários.

Por favor consulte a seção Comandos de Console para mais detalhes.

I18N

O Yii 2.0 remove os formatters de data e número em favor do módulo intl do PECL do PHP.

A tradução de mensagens agora é realizaada pelo componente de aplicação i18n. Este componente gerencia um conjunto de fontes de mensagens, que lhe permite usar diferentes fontes de mensagens baseadas nas categorias das mensagens.

Por favor consulte a seção Internacionalização para mais detalhes.

Action Filters (Filtros de Ação)

Agora os action filters (filtros de ação) são implementados via behaviors. Para definir um novo filtro personalizado, estenda de yii\base\ActionFilter. Para usar um filtro, anexe a classe do filtro ao controller (controlador) como um behavior. Por exemplo, para usar o filtro yii\filters\AccessControl, você teria o seguinte código em um controller:

public function behaviors()
{
    return [
        'access' => [
            'class' => 'yii\filters\AccessControl',
            'rules' => [
                ['allow' => true, 'actions' => ['admin'], 'roles' => ['@']],
            ],
        ],
    ];
}

Por favor consulte a seção Filtering para mais detalhes.

Assets

O Yii 2.0 introduz um novo conceito chamado de asset bundle (pacote de assets) que substitui o conceito de script packages (pacotes de script) encontrado no Yii 1.1.

Um asset bundle é uma coleção de arquivos de assets (por exemplo, arquivos JavaScript, arquivos CSS, arquivos de imagens, etc.) dentro de um diretório. Cada asset bundle é representado por uma classe que estende yii\web\AssetBundle. Ao registrar um asset bundle via yii\web\AssetBundle::register(), você torna os assets deste pacote acessíveis via Web. Ao contrário do Yii 1, a página que registra o bundle automaticamente conterá as referências aos arquivos JavaScript e CSS especificados naquele bundle.

Por favor consulte a seção Gerenciando Assets para mais detalhes.

Helpers

O Yii 2.0 introduz muitas classes de helper estáticas comumente usadas, incluindo:

• yii\helpers\Html
• yii\helpers\ArrayHelper
• yii\helpers\StringHelper
• yii\helpers\FileHelper
• yii\helpers\Json

Por favor consulte a seção Visão Geral dos helpers para mais detalhes.

Forms

O Yii 2.0 introduz o conceito de campos (fields) para a construção de formulários usando yii\widgets\ActiveForm. Um field é um container consistindo de um label, um input, uma mensagem de erro, e/ou um texto de ajuda. Um field é representado como um objeto yii\widgets\ActiveField. Usando fields você pode construir um formulário de maneira mais limpa do que antes:

<?php $form = yii\widgets\ActiveForm::begin(); ?>
    <?= $form->field($model, 'username') ?>
    <?= $form->field($model, 'password')->passwordInput() ?>
    <div class="form-group">
        <?= Html::submitButton('Login') ?>
    </div>
<?php yii\widgets\ActiveForm::end(); ?>

Por favor consulte a seção Criando um Formulário para mais detalhes.

Query Builder (Construtor de Consultas)

No 1.1, a construção de consultas estava espalhada po diversas classes, incluindo a CDbCommand, a CDbCriteria e a CDbCommandBuilder. O Yii 2.0 representa uma consulta do banco de dados em termos de um objeto yii\db\Query que pode ser convertido em uma instrução SQL com a ajuda do yii\db\QueryBuilder que está por de trás dos panos.

Por exemplo:

$query = new \yii\db\Query();
$query->select('id, name')
      ->from('user')
      ->limit(10);

$command = $query->createCommand();
$sql = $command->sql;
$rows = $command->queryAll();

E o melhor de tudo, estes métodos de construção de consultas também podem ser utilizados ao trabalhar com o Active Record.

Por favor consulte a seção Query Builder para mais detalhes.

Active Record

O Yii 2.0 introduz várias mudanças ao Active Record. As dias mais óbvias envolvem a construção de consultas e o manuseio de consultas relacionais.

A classe CDbCriteria do 1.1 foi substituída pela yii\db\ActiveQuery do Yii 2. Essa classe estende de yii\db\Query, e assim herda todos os métodos de construção de consultas. Você chama yii\db\ActiveRecord::find() para começar a construir uma consulta:

// Para obter todos os clientes *ativos* e ordená-los pelo ID:
$customers = Customer::find()
    ->where(['status' => $active])
    ->orderBy('id')
    ->all();

Para declarar um relacionamento, simplesmente defina um método getter que retorne um objeto yii\db\ActiveQuery. O nome da propriedade definida pelo getter representa o nome do relacionamento. Por exemplo, o código a seguir declara um relacionamento orders (no 1.1, você teria que declarar as relações em um local central, relations()):

class Customer extends \yii\db\ActiveRecord
{
    public function getOrders()
    {
        return $this->hasMany('Order', ['customer_id' => 'id']);
    }
}

Agora você pode usar $customer->orders pra acessar os pedidos (orders) de um cliente (customer) a partir da tabela relacionada. Você também pode usar o código a seguir para realizar uma consulta relacional on-the-fly:

$orders = $customer->getOrders()->andWhere('status=1')->all();

Ao fazer o eager loading (carregamento na inicialização) de um relacionamento, o Yii 2.0 faz isso de maneira diferente do 1.1. Em particular, no 1.1 uma consulta JOIN seria criada para selecionar tanto o registro primário quanto os de relacionamentos. No Yii 2.0, duas instruções SQL são executadas sem usar JOIN: a primeira instrução retorna os registros principais e a segunda retorna os registros de relacionamentos filtrando pelas chaves primários dos registros principais.

Ao invés de retornar objetos yii\db\ActiveRecord, você pode encadear o método yii\db\ActiveQuery::asArray() ao construir uma consulta para retornar um grande número de registros. Isso fará com que o resultado da consulta retorne como arrays, o que pode reduzir significativamente o tempo de CPU e memória necessários para um grande número de registros. Por exemplo,

$customers = Customer::find()->asArray()->all();

Outra mudança é que você não pode mais definir valores padrão de atributos através de propriedades públicas. Se você precisar disso, você deve defini-las no método init na classe do seu registro.

public function init()
{
    parent::init();
    $this->status = self::STATUS_NEW;
}

Havia alguns problemas ao sobrescrever o construtor de uma classe ActiveRecord no 1.1. Estes não ocorrem mais na versão 2.0. Perceba que ao adicionar parâmetros ao construtor você pode ter que sobrescrever o método yii\db\ActiveRecord::instantiate().

Existem muitas outras mudanças e melhorias no Active Record. Por favor consulte a seção Active Record para mais detalhes.

User e IdentityInterface

A classe CWebUser do 1.1 agora foi substituída pela yii\web\User, e não há mais a classe CUserIdentity. Ao invés disso, você deve implementar a interface yii\web\IdentityInterface que é muito mais simples de usar. O template de aplicação avançado dá um exemplo disso.

Por favor consulte as seções Autenticação, Autorização, e Modelo de Aplicação Avançada para mais detalhes.

Gerenciamento de URLs

O gerenciamento de URLs no Yii 2 é semelhante ao do 1.1. A principal melhoria é que o gerenciamento de URL agora suporta parâmetros opcionais. Por exemplo, se você tiver uma regra declarada como a seguir, então ela corresponderá tanto post/popular quanto post/1/popular. No 1.1, você teria que usar duas regrar para este mesmo fim.

[
    'pattern' => 'post/<page:\d+>/<tag>',
    'route' => 'post/index',
    'defaults' => ['page' => 1],
]

Por favor consulte a seção documentação do url manager para mais detalhes.

Utilizando o Yii 1.1 e o 2.x juntos

Se você tem código legado do Yii 1.1 que você quer manter para utilizar com o Yii 2.0, por favor consulte a seção Usando Yii 1.1 e 2.0 juntos.