intro-upgrade-from-v1.md 18.4 KB
Newer Older
Qiang Xue committed
1 2
Upgrading from Version 1.1
==========================
Qiang Xue committed
3

4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
There are many differences between Yii version 2.0 and 1.1, because Yii is completely rewritten for 2.0.
As a result, upgrading from version 1.1 is not as trivial as upgrading between minor versions. In this chapter,
we will summarize the major differences between the two versions.

Please note that Yii 2.0 introduces many new features which are not covered in this summary. It is highly recommended
that you read through the whole definitive guide to learn about these features. Chances could be that
some features you previously have to develop by yourself are already part of the core code now.


Installation
------------

Yii 2.0 fully embraces [Composer](https://getcomposer.org/), a de facto PHP package manager. Installation
of the core framework as well as extensions are all installed through Composer. Please refer to
the [Starting from Basic App](start-basic.md) chapter to learn how to install Yii 2.0. If you want to
create new extensions or turn your existing 1.1 extensions into 2.0, please refer to
the [Creating Extensions](extend-creating-extensions.md) chapter.
Qiang Xue committed
21

22

Qiang Xue committed
23 24 25 26 27 28
PHP Requirements
----------------

Yii 2.0 requires PHP 5.4 or above, which is a huge improvement over PHP 5.2 as required by Yii 1.1.
As a result, there are many differences at language level that you should pay attention to.
Below is a summary of the major changes regarding PHP:
29 30 31

- [Namespaces](http://php.net/manual/en/language.namespaces.php).
- [Anonymous functions](http://php.net/manual/en/functions.anonymous.php).
Qiang Xue committed
32 33 34
- Short array syntax `[...elements...]` is used instead of `array(...elements...)`.
- Short echo tags `<?=` are used in view files. This is safe to use starting from PHP 5.4.
- [SPL classes and interfaces](http://php.net/manual/en/book.spl.php).
35 36 37
- [Late Static Bindings](http://php.net/manual/en/language.oop5.late-static-bindings.php).
- [Date and Time](http://php.net/manual/en/book.datetime.php).
- [Traits](http://php.net/manual/en/language.oop5.traits.php).
Qiang Xue committed
38 39 40
- [intl](http://php.net/manual/en/book.intl.php). Yii 2.0 makes use of the `intl` PHP extension
  to support internationalization features.

Qiang Xue committed
41

Qiang Xue committed
42 43 44 45 46 47 48
Namespace
---------

The most obvious change in Yii 2.0 is the use of namespaces. Almost every core class
is namespaced, e.g., `yii\web\Request`. The "C" prefix is no longer used in class names.
The naming of the namespaces follows the directory structure. For example, `yii\web\Request`
indicates the corresponding class file is `web/Request.php` under the Yii framework folder.
ploaiza committed
49
You can use any core class without explicitly including that class file, thanks to the Yii
Qiang Xue committed
50 51 52
class loader.


Qiang Xue committed
53 54 55
Component and Object
--------------------

56
Yii 2.0 breaks the `CComponent` class in 1.1 into two classes: [[yii\base\Object]] and [[yii\base\Component]].
57
The [[yii\base\Object|Object]] class is a lightweight base class that allows defining [object properties](concept-properties.md)
58
via getters and setters. The [[yii\base\Component|Component]] class extends from [[yii\base\Object|Object]] and supports
59
[events](concept-events.md) and [behaviors](concept-behaviors.md).
Qiang Xue committed
60 61

If your class does not need the event or behavior feature, you should consider using
Qiang Xue committed
62
[[yii\base\Object|Object]] as the base class. This is usually the case for classes that represent basic
Qiang Xue committed
63 64 65 66 67 68
data structures.


Object Configuration
--------------------

69 70
The [[yii\base\Object|Object]] class introduces a uniform way of configuring objects. Any descendant class
of [[yii\base\Object|Object]] should declare its constructor (if needed) in the following way so that
71
it can be properly configured:
Qiang Xue committed
72

73
```php
Qiang Xue committed
74
class MyClass extends \yii\base\Object
Qiang Xue committed
75
{
Alexander Makarov committed
76
    public function __construct($param1, $param2, $config = [])
Qiang Xue committed
77
    {
78 79
        // ... initialization before configuration is applied

Qiang Xue committed
80 81 82 83 84 85
        parent::__construct($config);
    }

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

        // ... initialization after configuration is applied
Qiang Xue committed
88 89
    }
}
90
```
Alexander Makarov committed
91

92 93
In the above, the last parameter of the constructor must take a configuration array
which contains name-value pairs for initializing the properties at the end of the constructor.
94
You can override the [[yii\base\Object::init()|init()]] method to do initialization work that should be done after
95
the configuration is applied.
Qiang Xue committed
96

97 98
By following this convention, you will be able to create and configure a new object
using a configuration array like the following:
Qiang Xue committed
99

100
```php
Alexander Makarov committed
101
$object = Yii::createObject([
Qiang Xue committed
102 103 104
    'class' => 'MyClass',
    'property1' => 'abc',
    'property2' => 'cde',
Qiang Xue committed
105
], [$param1, $param2]);
106
```
Alexander Makarov committed
107

Qiang Xue committed
108
More details about configurations can be found in the [Object Configurations](concept-configurations.md) chapter.
109

Qiang Xue committed
110 111 112 113 114

Events
------

There is no longer the need to define an `on`-method in order to define an event in Yii 2.0.
Qiang Xue committed
115 116
Instead, you can use whatever event names. You can trigger an event by calling
the [[yii\base\Component::trigger()|trigger()]] method:
Qiang Xue committed
117

118
```php
Qiang Xue committed
119 120
$event = new \yii\base\Event;
$component->trigger($eventName, $event);
121
```
Qiang Xue committed
122

Qiang Xue committed
123
And to attach a handler to an event, you can use the [[yii\base\Component::on()|on()]] method:
124 125

```php
Qiang Xue committed
126 127 128
$component->on($eventName, $handler);
// To detach the handler, use:
// $component->off($eventName, $handler);
129 130
```

131
There are many enhancements to the event features. For more details, please refer to the [Events](concept-events.md) chapter.
Qiang Xue committed
132

133

Qiang Xue committed
134 135
Path Aliases
------------
136

Qiang Xue committed
137 138
Yii 2.0 expands the usage of path aliases to both file/directory paths and URLs. It also requires
an alias name to start with a `@` character so that it can be differentiated from normal file/directory paths and URLs.
139
For example, the alias `@yii` refers to the Yii installation directory. Path aliases are
Qiang Xue committed
140
supported in most places in the Yii core code. For example, [[yii\caching\FileCache::cachePath]] can take
141 142 143
both a path alias and a normal directory path.

Path alias is also closely related with class namespaces. It is recommended that a path
ploaiza committed
144
alias be defined for each root namespace so that you can use Yii the class autoloader without
145 146
any further configuration. For example, because `@yii` refers to the Yii installation directory,
a class like `yii\web\Request` can be autoloaded by Yii. If you use a third party library
147
such as Zend Framework, you may define a path alias `@Zend` which refers to its installation
ploaiza committed
148
directory and Yii will be able to autoload any class in this library.
149

150
More on path aliases can be found in the [Path Aliases](concept-aliases.md) chapter.
151

152

Qiang Xue committed
153 154
Views
-----
Qiang Xue committed
155

156 157 158 159
The most significant change about views is that `$this` in a view no longer refers to
the current controller or widget. Instead, it refers to a *view* object which is a new concept
introduced in 2.0. The *view* object is of class [[yii\web\View]] which represents the view part
of the MVC pattern. In you want to access the controller or widget in a view, you should use `$this->context`.
Qiang Xue committed
160

161 162 163
To render a partial view within another view, you should use `$this->render()` now.
And you have to echo it explicitly because the `render()` method will return the rendering
result rather than directly displaying it. For example,
164 165 166 167 168

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

169 170 171 172 173
Besides using PHP as the primary template language, Yii 2.0 is also equipped with official
support for two popular template engines: Smarty and Twig. The Prado template engine is no longer supported.
To use these template engines, you need to configure the `view` application component by setting the
[[yii\base\View::$renderers|View::$renderers]] property. Please refer to the [Template Engines](tutorial-template-engines.md)
chapter for more details.
174

Qiang Xue committed
175 176 177 178

Models
------

179 180
Yii 2.0 uses [[yii\base\Model]] as the base model class which is similar to `CModel` in 1.1.
The class `CFormModel` is dropped. Instead, you should extend [[yii\base\Model]] to create a form model class.
181

182 183 184
Yii 2.0 introduces a new method called [[yii\base\Model::scenarios()|scenarios()]] to declare
supported scenarios and under which scenario an attribute needs to be validated and can be considered as safe or not.
For example,
185

186
```php
187 188
public function scenarios()
{
Alexander Makarov committed
189 190 191 192
    return [
        'backend' => ['email', 'role'],
        'frontend' => ['email', '!name'],
    ];
193
}
194
```
Alexander Makarov committed
195

196 197 198
In the above, two scenarios are declared: `backend` and `frontend`. For the `backend` scenario, both of the
`email` and `role` attributes are safe and can be massively assigned; for the `frontend` scenario,
`email` can be massively assigned while `role` cannot. Both `email` and `role` should be validated.
199

200 201
The [[yii\base\Model::rules()|rules()]] method is still used to declare validation rules. Note that because
of the introduction of [[yii\base\Model::scenarios()|scenarios()]], there is no more `unsafe` validator.
202

Paul K committed
203
In most cases, you do not need to override [[yii\base\Model::scenarios()|scenarios()]]
204 205
if the [[yii\base\Model::rules()|rules()]] method fully specifies the scenarios and there is no need to declare
`unsafe` attributes.
206

207
To learn more details about models, please refer to the [Models](basic-models.md) chapter.
208

209

Qiang Xue committed
210 211 212
Controllers
-----------

213 214
Yii 2.0 uses [[yii\web\Controller]] as the base controller class which is similar to `CWebController` in 1.1.
And [[yii\base\Action]] is the base class for action classes.
215

216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231
The most obvious change when you write code in a controller action is that you should return the content
that you want to render instead of echoing it. For example,

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

Please refer to the [Controllers](structure-controllers.md) chapter for more details about controllers.
232

233

234 235 236
Widgets
-------

237 238 239
Yii 2.0 uses [[yii\base\Widget]] as the base widget class which is similar to `CWidget` in 1.1.

To get better IDE support, Yii 2.0 introduces a new syntax for using widgets. The static methods
Qiang Xue committed
240
[[yii\base\Widget::begin()|begin()]], [[yii\base\Widget::end()|end()]] and [[yii\base\Widget::widget()|widget()]]
241
are introduced and can be used as follows,
242 243

```php
Qiang Xue committed
244 245 246
use yii\widgets\Menu;
use yii\widgets\ActiveForm;

247
// Note that you have to "echo" the result to display it
Qiang Xue committed
248
echo Menu::widget(['items' => $items]);
249

250
// Passing an array to initialize the object properties
Qiang Xue committed
251
$form = ActiveForm::begin([
252 253
    'options' => ['class' => 'form-horizontal'],
    'fieldConfig' => ['inputOptions' => ['class' => 'input-xlarge']],
Alexander Makarov committed
254
]);
Qiang Xue committed
255 256
... form input fields here ...
ActiveForm::end();
257 258
```

Qiang Xue committed
259
Please refer to the [Widgets](structure-widgets.md) chapter for more details.
260

261

Qiang Xue committed
262 263 264
Themes
------

265 266
Themes work completely different in 2.0. They are now based on a path mapping mechanism which maps a source
view file path to a themed view file path. For example, if the path map for a theme is
Alexander Makarov committed
267
`['/web/views' => '/web/themes/basic']`, then the themed version for a view file
268 269
`/web/views/site/index.php` will be `/web/themes/basic/site/index.php`. For this reason, themes can now
be applied to any view file, even if a view rendered outside of the context of a controller or a widget.
270

271
Also, there is no more `CThemeManager`. Instead, `theme` is a configurable property of the `view`
272 273
application component.

274
Please refer to the [Theming](tutorial-theming.md) chapter for more details.
275

276

Qiang Xue committed
277 278 279
Console Applications
--------------------

280 281
Console applications are now organized as controllers, like Web applications. Console controllers
should extend from [[yii\console\Controller]] which is similar to `CConsoleCommand` in 1.1.
282

283 284 285 286
To run a console command, use `yii <route>`, where `<route>` stands for a controller route
(e.g. `sitemap/index`). Additional anonymous arguments are passed as the parameters to the
corresponding controller action method, while named arguments are parsed according to
the declarations in [[yii\console\Controller::options()]].
287 288 289

Yii 2.0 supports automatic generation of command help information from comment blocks.

290
Please refer to the [Console Commands](tutorial-console.md) chapter for more details.
291

292

Qiang Xue committed
293 294 295
I18N
----

296
Yii 2.0 removes date formatter and number formatter in favor of the PECL intl PHP module.
Qiang Xue committed
297

298
Message translation is now performed via the `i18n` application component.
299
The component manages a set of message sources, which allows you to use different message
300 301 302
sources based on message categories.

Please refer to the [Internationalization](tutorial-i18n.md) chapter for more details.
303 304 305 306 307


Action Filters
--------------

308
Action filters are implemented via behaviors now. You should extend from [[yii\base\ActionFilter]] to
309
define a new filter. To use a filter, you should attach the filter class to the controller
310
as a behavior. For example, to use the [[yii\filters\AccessControl]] filter, you should have the following
311 312
code in a controller:

313
```php
314 315
public function behaviors()
{
Alexander Makarov committed
316 317
    return [
        'access' => [
318
            'class' => 'yii\filters\AccessControl',
Alexander Makarov committed
319 320
            'rules' => [
                ['allow' => true, 'actions' => ['admin'], 'roles' => ['@']],
321 322 323
            ],
        ],
    ];
324
}
325
```
Alexander Makarov committed
326

327
Please refer to the [Filtering](runtime-filtering.md) chapter for more details.
Qiang Xue committed
328 329 330 331 332


Assets
------

333
Yii 2.0 introduces a new concept called *asset bundle* which replaces the script package concept in 1.1.
334 335

An asset bundle is a collection of asset files (e.g. JavaScript files, CSS files, image files, etc.)
336 337
under a directory. Each asset bundle is represented as a class extending [[yii\web\AssetBundle]].
By registering an asset bundle via [[yii\web\AssetBundle::register()]], you will be able to make
338
the assets in that bundle accessible via Web, and the page registering the bundle will automatically
339
contain the references to the JavaScript and CSS files specified in that bundle.
340

341
Please refer to the [Managing Assets](output-assets.md) chapter for more details.
342

343 344 345

Helpers
-------
Qiang Xue committed
346

347
Yii 2.0 introduces many commonly used static helper classes, such as
348

349 350 351 352 353 354
* [[yii\helpers\Html]]
* [[yii\helpers\ArrayHelper]]
* [[yii\helpers\StringHelper]]
* [[yii\helpers\FileHelper]]
* [[yii\helpers\Json]]
* [[yii\helpers\Security]]
355

356 357 358

Forms
-----
Qiang Xue committed
359

360
Yii 2.0 introduces the *field* concept for building a form using [[yii\widgets\ActiveForm]]. A field
Qiang Xue committed
361
is a container consisting of a label, an input, an error message, and/or a hint text.
362 363
It is represented as an [[yii\widgets\ActiveField|ActiveField]] object.
Using fields, you can build a form more cleanly than before:
364

365
```php
366
<?php $form = yii\widgets\ActiveForm::begin(); ?>
367 368 369 370 371
    <?= $form->field($model, 'username') ?>
    <?= $form->field($model, 'password')->passwordInput() ?>
    <div class="form-group">
        <?= Html::submitButton('Login') ?>
    </div>
372
<?php yii\widgets\ActiveForm::end(); ?>
373
```
Alexander Makarov committed
374

375

Qiang Xue committed
376 377 378
Query Builder
-------------

379
In 1.1, query building is scattered among several classes, including `CDbCommand`,
380 381 382
`CDbCriteria`, and `CDbCommandBuilder`. Yii 2.0 represents a DB query in terms of a [[yii\db\Query|Query]] object
which can be turned into a SQL statement with the help of [[yii\db\QueryBuilder|QueryBuilder]] behind the scene.
For example:
383

384
```php
385
$query = new \yii\db\Query();
386
$query->select('id, name')
387
      ->from('user')
388 389 390 391 392
      ->limit(10);

$command = $query->createCommand();
$sql = $command->sql;
$rows = $command->queryAll();
393
```
Alexander Makarov committed
394

395
Best of all, such query building methods can also be used when working with [Active Record](db-active-record.md).
Qiang Xue committed
396

397
Please refer to the [Query Builder](db-query-builder.md) chapter for more details.
Qiang Xue committed
398

399

400 401
Active Record
-------------
402

403 404
Yii 2.0 introduces a lot of changes to [Active Record](db-active-record.md). Two most obvious ones are:
query building and relational query handling.
405

406 407 408
The `CDbCriteria` class in 1.1 is replaced by [[yii\db\ActiveQuery]] which extends from [[yii\db\Query]] and thus
inherits all query building methods. You call [[yii\db\ActiveRecord::find()]] to start building a query.
For example,
409

410
```php
411 412
// to retrieve all *active* customers and order them by their ID:
$customers = Customer::find()
413 414 415
    ->where(['status' => $active])
    ->orderBy('id')
    ->all();
416
```
Alexander Makarov committed
417

418 419 420
To declare a relation, you simply define a getter method that returns an [[yii\db\ActiveQuery|ActiveQuery]] object.
The property name defined by the getter represents the relation name. For example, the following code declares
an `orders` relation (in 1.1, you would have to declare relations in a central place `relations()`):
421

422
```php
423 424 425 426 427 428 429
class Customer extends \yii\db\ActiveRecord
{
    public function getOrders()
    {
        return $this->hasMany('Order', ['customer_id' => 'id']);
    }
}
430
```
431

432 433
You can use `$customer->orders` to access the customer's orders. You can also use the following code
to perform on-the-fly relational query with customized query conditions:
434

435 436 437
```php
$orders = $customer->getOrders()->andWhere('status=1')->all();
```
438

439 440 441 442
When eager loading a relation, Yii 2.0 does it differently from 1.1. In particular, in 1.1 a JOIN query
would be created to bring both the primary and the relational records; in 2.0, two SQL statements are executed
without using JOIN: the first statement brings back the primary records and the second brings back the relational
records by filtering with the primary keys of the primary records.
443

444 445 446
Instead of returning [[yii\db\ActiveRecord|ActiveRecord]] objects, you may chain the [[yii\db\ActiveQuery::asArray()|asArray()]]
method when building a query to return large number of records. This will cause the query result to be returned
as arrays, which can significantly reduce the needed CPU time and memory if large number of records . For example,
447

448
```php
449
$customers = Customer::find()->asArray()->all();
450
```
Alexander Makarov committed
451

452 453
There are many other changes and enhancements to Active Record. Please refer to
the [Active Record](db-active-record.md) chapter for more details.
454 455


456 457
User and IdentityInterface
--------------------------
Qiang Xue committed
458

459 460 461
The `CWebUser` class in 1.1 is now replaced by [[yii\web\User]], and there is no more
`CUserIdentity` class. Instead, you should implement the [[yii\web\IdentityInterface]] which
is much more straightforward to implement. The advanced application template provides such an example.
462 463


Qiang Xue committed
464 465 466
URL Management
--------------

467 468 469 470 471
URL management is similar to 1.1. A major enhancement is that it now supports optional
parameters. For example, if you have rule declared as follows, then it will match
both `post/popular` and `post/1/popular`. In 1.1, you would have to use two rules to achieve
the same goal.

472
```php
Alexander Makarov committed
473
[
474 475 476
    'pattern' => 'post/<page:\d+>/<tag>',
    'route' => 'post/index',
    'defaults' => ['page' => 1],
Alexander Makarov committed
477
]
478
```
Alexander Makarov committed
479

480
More details in the [Url manager docs](url.md).
481

482 483 484 485

Using Yii 1.1 and 2.x together
------------------------------

486 487 488
If you have legacy Yii 1.1 code and you want to use it together with Yii 2.0, please refer to
the [Using Yii 1.1 and 2.0 Together](extend-using-v1-v2.md) chapter.