intro-upgrade-from-v1.md 17.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 29
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
30
You can use any core class without explicitly including that class file, thanks to the Yii
Qiang Xue committed
31 32 33
class loader.


Qiang Xue committed
34 35 36
Component and Object
--------------------

37
Yii 2.0 breaks the `CComponent` class in 1.1 into two classes: [[yii\base\Object]] and [[yii\base\Component]].
Qiang Xue committed
38
The [[yii\base\Object|Object]] class is a lightweight base class that allows defining [object properties](basic-properties.md)
39
via getters and setters. The [[yii\base\Component|Component]] class extends from [[yii\base\Object|Object]] and supports
Qiang Xue committed
40
[events](basic-events.md) and [behaviors](basic-behaviors.md).
Qiang Xue committed
41 42

If your class does not need the event or behavior feature, you should consider using
Qiang Xue committed
43
[[yii\base\Object|Object]] as the base class. This is usually the case for classes that represent basic
Qiang Xue committed
44 45 46 47 48 49
data structures.


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

50 51
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
52
it can be properly configured:
Qiang Xue committed
53

54
```php
Qiang Xue committed
55
class MyClass extends \yii\base\Object
Qiang Xue committed
56
{
Alexander Makarov committed
57
    public function __construct($param1, $param2, $config = [])
Qiang Xue committed
58
    {
59 60
        // ... initialization before configuration is applied

Qiang Xue committed
61 62 63 64 65 66
        parent::__construct($config);
    }

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

        // ... initialization after configuration is applied
Qiang Xue committed
69 70
    }
}
71
```
Alexander Makarov committed
72

73 74
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.
75
You can override the [[yii\base\Object::init()|init()]] method to do initialization work that should be done after
76
the configuration is applied.
Qiang Xue committed
77

78 79
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
80

81
```php
Alexander Makarov committed
82
$object = Yii::createObject([
Qiang Xue committed
83 84 85
    'class' => 'MyClass',
    'property1' => 'abc',
    'property2' => 'cde',
Qiang Xue committed
86
], [$param1, $param2]);
87
```
Alexander Makarov committed
88

Qiang Xue committed
89
More details about configurations can be found in the [Object Configurations](basic-configs.md) chapter.
90

Qiang Xue committed
91 92 93 94 95

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
96 97
Instead, you can use whatever event names. You can trigger an event by calling
the [[yii\base\Component::trigger()|trigger()]] method:
Qiang Xue committed
98

99
```php
Qiang Xue committed
100 101
$event = new \yii\base\Event;
$component->trigger($eventName, $event);
102
```
Qiang Xue committed
103

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

```php
Qiang Xue committed
107 108 109
$component->on($eventName, $handler);
// To detach the handler, use:
// $component->off($eventName, $handler);
110 111
```

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

114

Qiang Xue committed
115 116
Path Aliases
------------
117

Qiang Xue committed
118 119
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.
120
For example, the alias `@yii` refers to the Yii installation directory. Path aliases are
Qiang Xue committed
121
supported in most places in the Yii core code. For example, [[yii\caching\FileCache::cachePath]] can take
122 123 124
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
125
alias be defined for each root namespace so that you can use Yii the class autoloader without
126 127
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
128
such as Zend Framework, you may define a path alias `@Zend` which refers to its installation
ploaiza committed
129
directory and Yii will be able to autoload any class in this library.
130

Qiang Xue committed
131
More on path aliases can be found in the [Path Aliases](basic-aliases.md) chapter.
132

133

Qiang Xue committed
134 135
Views
-----
Qiang Xue committed
136

137 138 139 140
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
141

142 143 144
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,
145 146 147 148 149

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

150 151 152 153 154
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.
155

Qiang Xue committed
156 157 158 159

Models
------

160 161
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.
162

163 164 165
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,
166

167
```php
168 169
public function scenarios()
{
Alexander Makarov committed
170 171 172 173
    return [
        'backend' => ['email', 'role'],
        'frontend' => ['email', '!name'],
    ];
174
}
175
```
Alexander Makarov committed
176

177 178 179
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.
180

181 182
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.
183

184 185 186
In most cases, you do not need to overwrite [[yii\base\Model::scenarios()|scenarios()]]
if the [[yii\base\Model::rules()|rules()]] method fully specifies the scenarios and there is no need to declare
`unsafe` attributes.
187

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

190

Qiang Xue committed
191 192 193
Controllers
-----------

194 195
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.
196

197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212
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.
213

214

215 216 217
Widgets
-------

218 219 220
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
221
[[yii\base\Widget::begin()|begin()]], [[yii\base\Widget::end()|end()]] and [[yii\base\Widget::widget()|widget()]]
222
are introduced and can be used as follows,
223 224

```php
Qiang Xue committed
225 226 227
use yii\widgets\Menu;
use yii\widgets\ActiveForm;

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

231
// Passing an array to initialize the object properties
Qiang Xue committed
232
$form = ActiveForm::begin([
233 234
    'options' => ['class' => 'form-horizontal'],
    'fieldConfig' => ['inputOptions' => ['class' => 'input-xlarge']],
Alexander Makarov committed
235
]);
Qiang Xue committed
236 237
... form input fields here ...
ActiveForm::end();
238 239
```

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

242

Qiang Xue committed
243 244 245
Themes
------

246 247
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
248
`['/web/views' => '/web/themes/basic']`, then the themed version for a view file
249 250
`/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.
251

252
Also, there is no more `CThemeManager`. Instead, `theme` is a configurable property of the `view`
253 254
application component.

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

257

Qiang Xue committed
258 259 260
Console Applications
--------------------

261 262
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.
263

264 265 266 267
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()]].
268 269 270

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

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

273

Qiang Xue committed
274 275 276
I18N
----

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

279
Message translation is still supported, but managed via the `i18n` application component.
280
The component manages a set of message sources, which allows you to use different message
281 282 283
sources based on message categories.

Please refer to the [Internationalization](tutorial-i18n.md) chapter for more details.
284 285 286 287 288


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

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

294
```php
295 296
public function behaviors()
{
Alexander Makarov committed
297 298
    return [
        'access' => [
299
            'class' => 'yii\filters\AccessControl',
Alexander Makarov committed
300 301
            'rules' => [
                ['allow' => true, 'actions' => ['admin'], 'roles' => ['@']],
302 303 304
            ],
        ],
    ];
305
}
306
```
Alexander Makarov committed
307

308
Please refer to the [Filtering](runtime-filtering.md) chapter for more details.
Qiang Xue committed
309 310 311 312 313


Assets
------

314
Yii 2.0 introduces a new concept called *asset bundle* which replaces the script package concept in 1.1.
315 316

An asset bundle is a collection of asset files (e.g. JavaScript files, CSS files, image files, etc.)
317 318
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
319
the assets in that bundle accessible via Web, and the page registering the bundle will automatically
320
contain the references to the JavaScript and CSS files specified in that bundle.
321

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

324 325 326

Helpers
-------
Qiang Xue committed
327

328
Yii 2.0 introduces many commonly used static helper classes, such as
329

330 331 332 333 334 335
* [[yii\helpers\Html]]
* [[yii\helpers\ArrayHelper]]
* [[yii\helpers\StringHelper]]
* [[yii\helpers\FileHelper]]
* [[yii\helpers\Json]]
* [[yii\helpers\Security]]
336

337 338 339

Forms
-----
Qiang Xue committed
340

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

346
```php
347
<?php $form = yii\widgets\ActiveForm::begin(); ?>
348 349 350 351 352
    <?= $form->field($model, 'username') ?>
    <?= $form->field($model, 'password')->passwordInput() ?>
    <div class="form-group">
        <?= Html::submitButton('Login') ?>
    </div>
353
<?php yii\widgets\ActiveForm::end(); ?>
354
```
Alexander Makarov committed
355

356

Qiang Xue committed
357 358 359
Query Builder
-------------

360
In 1.1, query building is scattered among several classes, including `CDbCommand`,
361 362 363
`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:
364

365
```php
366
$query = new \yii\db\Query();
367
$query->select('id, name')
368
      ->from('user')
369 370 371 372 373
      ->limit(10);

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

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

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

380

381 382
Active Record
-------------
383

384 385
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.
386

387 388 389
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,
390

391
```php
392 393
// to retrieve all *active* customers and order them by their ID:
$customers = Customer::find()
394 395 396
    ->where(['status' => $active])
    ->orderBy('id')
    ->all();
397
```
Alexander Makarov committed
398

399 400 401
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()`):
402

403
```php
404 405 406 407 408 409 410
class Customer extends \yii\db\ActiveRecord
{
    public function getOrders()
    {
        return $this->hasMany('Order', ['customer_id' => 'id']);
    }
}
411
```
412

413 414
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:
415

416 417 418
```php
$orders = $customer->getOrders()->andWhere('status=1')->all();
```
419

420 421 422 423
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.
424

425 426 427
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,
428

429
```php
430
$customers = Customer::find()->asArray()->all();
431
```
Alexander Makarov committed
432

433 434
There are many other changes and enhancements to Active Record. Please refer to
the [Active Record](db-active-record.md) chapter for more details.
435 436


437 438
User and IdentityInterface
--------------------------
Qiang Xue committed
439

440 441 442
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.
443 444


Qiang Xue committed
445 446 447
URL Management
--------------

448 449 450 451 452
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.

453
```php
Alexander Makarov committed
454
[
455 456 457
    'pattern' => 'post/<page:\d+>/<tag>',
    'route' => 'post/index',
    'defaults' => ['page' => 1],
Alexander Makarov committed
458
]
459
```
Alexander Makarov committed
460

461
More details in the [Url manager docs](url.md).
462

463 464 465 466

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

467 468 469
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.