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

Larry Ullman committed
4 5
There are many differences between versions 1.1 and 2.0 of the Yii as the framework was completely rewritten for 2.0.
As a result, upgrading from version 1.1 is not as trivial as upgrading between minor versions. In this guide you'll find the major differences between the two versions.
6

Larry Ullman committed
7 8 9
Please note that Yii 2.0 introduces more new features than are covered in this summary. It is highly recommended
that you read through the whole definitive guide to learn about them all. Chances are that
some features you previously had to develop for yourself are now part of the core code.
10 11 12 13 14


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

Larry Ullman committed
15 16 17 18 19
Yii 2.0 fully embraces [Composer](https://getcomposer.org/), the de facto PHP package manager. Installation
of the core framework, as well as extensions, are handled through Composer. Please refer to
the [Starting from Basic App](start-basic.md) section 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-compatible extensions, please refer to
the [Creating Extensions](extend-creating-extensions.md) section of the guide.
Qiang Xue committed
20

21

Qiang Xue committed
22 23 24
PHP Requirements
----------------

Larry Ullman committed
25 26
Yii 2.0 requires PHP 5.4 or above, which is a huge improvement over PHP version 5.2 that is required by Yii 1.1.
As a result, there are many differences on the language level that you should pay attention to.
Qiang Xue committed
27
Below is a summary of the major changes regarding PHP:
28 29 30

- [Namespaces](http://php.net/manual/en/language.namespaces.php).
- [Anonymous functions](http://php.net/manual/en/functions.anonymous.php).
Qiang Xue committed
31 32 33
- 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).
34 35 36
- [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
37 38 39
- [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
40

Qiang Xue committed
41 42 43 44 45
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.
Larry Ullman committed
46 47 48 49 50
The naming scheme now follows the directory structure. For example, `yii\web\Request`
indicates that the corresponding class file is `web/Request.php` under the Yii framework folder.

(You can use any core class without explicitly including that class file, thanks to the Yii
class loader.)
Qiang Xue committed
51 52


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
In the above, the last parameter of the constructor must take a configuration array
Larry Ullman committed
93
that 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
Larry Ullman committed
95
the configuration has been applied.
Qiang Xue committed
96

Larry Ullman committed
97 98
By following this convention, you will be able to create and configure new objects
using a configuration array:
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

Larry Ullman committed
108
More details about configurations can be found in the [Object Configurations](concept-configurations.md) section.
109

Qiang Xue committed
110 111 112 113

Events
------

Larry Ullman committed
114
In Yii 1, events were created by defining an `on`-method (e.g., `onBeforeSave`). In Yii 2, you can now use any event name. You trigger an event by calling
Qiang Xue committed
115
the [[yii\base\Component::trigger()|trigger()]] method:
Qiang Xue committed
116

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

Larry Ullman committed
122
To attach a handler to an event, use the [[yii\base\Component::on()|on()]] method:
123 124

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

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

132

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

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

Larry Ullman committed
142 143
A path alias is also closely related to a class namespace. It is recommended that a path
alias be defined for each root namespace, thereby allowing you to use Yii the class autoloader without
144
any further configuration. For example, because `@yii` refers to the Yii installation directory,
Larry Ullman committed
145 146 147
a class like `yii\web\Request` can be autoloaded. If you use a third party library,
such as the Zend Framework, you may define a path alias `@Zend` that refers to that framework's installation
directory. Once you've done that, Yii will be able to autoload any class in that Zend Framework library, too.
148

Larry Ullman committed
149
More on path aliases can be found in the [Path Aliases](concept-aliases.md) section.
150

151

Qiang Xue committed
152 153
Views
-----
Qiang Xue committed
154

Larry Ullman committed
155 156 157 158
The most significant change about views in Yii 2 is that the special variable `$this` in a view no longer refers to
the current controller or widget. Instead, `$this` now refers to a *view* object, a new concept
introduced in 2.0. The *view* object is of type [[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 can use `$this->context`.
Qiang Xue committed
159

Larry Ullman committed
160 161
To render a partial view within another view, you use `$this->render()`, not `$this->renderPartial()`. The call to `render` also now has to be explicitly echoed, as the `render()` method returns the rendering
result, rather than directly displaying it. For example:
162 163 164 165 166

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

167 168 169 170
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)
Larry Ullman committed
171
section for more details.
172

Qiang Xue committed
173 174 175 176

Models
------

Larry Ullman committed
177 178
Yii 2.0 uses [[yii\base\Model]] as the base model, similar to `CModel` in 1.1.
The class `CFormModel` has been dropped entirely. Instead, in Yii 2 you should extend [[yii\base\Model]] to create a form model class.
179

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

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

Larry Ullman committed
193 194 195
In the above, two scenarios are declared: `backend` and `frontend`. For the `backend` scenario, both 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 using rules.
196

Larry Ullman committed
197
The [[yii\base\Model::rules()|rules()]] method is still used to declare the validation rules. Note that due to the introduction of [[yii\base\Model::scenarios()|scenarios()]], there is no longer an `unsafe` validator.
198

Paul K committed
199
In most cases, you do not need to override [[yii\base\Model::scenarios()|scenarios()]]
Larry Ullman committed
200
if the [[yii\base\Model::rules()|rules()]] method fully specifies the scenarios that will exist, and if there is no need to declare
201
`unsafe` attributes.
202

Larry Ullman committed
203
To learn more details about models, please refer to the [Models](basic-models.md) section.
204

205

Qiang Xue committed
206 207 208
Controllers
-----------

Larry Ullman committed
209 210
Yii 2.0 uses [[yii\web\Controller]] as the base controller class, similar to `CWebController` in Yii 1.1.
[[yii\base\Action]] is the base class for action classes.
211

Larry Ullman committed
212 213
The most obvious impact of these changes on your code is that a controller action should return the content
that you want to render instead of echoing it:
214 215 216 217 218 219 220 221 222 223 224 225 226

```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;
    }
}
```

Larry Ullman committed
227
Please refer to the [Controllers](structure-controllers.md) section for more details about controllers.
228

229

230 231 232
Widgets
-------

Larry Ullman committed
233
Yii 2.0 uses [[yii\base\Widget]] as the base widget class, similar to `CWidget` in Yii 1.1.
234

Larry Ullman committed
235 236 237
To get better support for the framework in IDEs, Yii 2.0 introduces a new syntax for using widgets. The static methods
[[yii\base\Widget::begin()|begin()]], [[yii\base\Widget::end()|end()]], and [[yii\base\Widget::widget()|widget()]]
have been introduced, to be used like so:
238 239

```php
Qiang Xue committed
240 241 242
use yii\widgets\Menu;
use yii\widgets\ActiveForm;

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

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

Larry Ullman committed
255
Please refer to the [Widgets](structure-widgets.md) section for more details.
256

257

Qiang Xue committed
258 259 260
Themes
------

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

Larry Ullman committed
267
Also, there is no more `CThemeManager` component. Instead, `theme` is a configurable property of the `view`
268 269
application component.

Larry Ullman committed
270
Please refer to the [Theming](tutorial-theming.md) section for more details.
271

272

Qiang Xue committed
273 274 275
Console Applications
--------------------

276
Console applications are now organized as controllers, like Web applications. Console controllers
Larry Ullman committed
277
should extend from [[yii\console\Controller]], similar to `CConsoleCommand` in 1.1.
278

279 280 281 282
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()]].
283 284 285

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

286
Please refer to the [Console Commands](tutorial-console.md) section for more details.
287

288

Qiang Xue committed
289 290 291
I18N
----

Larry Ullman committed
292
Yii 2.0 removes the built-in date formatter and number formatter pieces in favor of the [PECL intl PHP module](http://pecl.php.net/package/intl).
Qiang Xue committed
293

294
Message translation is now performed via the `i18n` application component.
Larry Ullman committed
295
This component manages a set of message sources, which allows you to use different message
296 297
sources based on message categories.

Larry Ullman committed
298
Please refer to the [Internationalization](tutorial-i18n.md) section for more details.
299 300 301 302 303


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

304 305
Action filters are implemented via behaviors now. To define a new, custom filter, extend from [[yii\base\ActionFilter]]. To use a filter, attach the filter class to the controller
as a behavior. For example, to use the [[yii\filters\AccessControl]] filter, you would have the following
306 307
code in a controller:

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

322
Please refer to the [Filtering](runtime-filtering.md) section for more details.
Qiang Xue committed
323 324 325 326 327


Assets
------

328
Yii 2.0 introduces a new concept called *asset bundle* that replaces the script package concept found in Yii 1.1.
329 330

An asset bundle is a collection of asset files (e.g. JavaScript files, CSS files, image files, etc.)
331 332 333
within 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 make
the assets in that bundle accessible via the Web. Unlike in Yii 1, the page registering the bundle will automatically
334
contain the references to the JavaScript and CSS files specified in that bundle.
335

336
Please refer to the [Managing Assets](output-assets.md) section for more details.
337

338 339 340

Helpers
-------
Qiang Xue committed
341

342
Yii 2.0 introduces many commonly used static helper classes, including.
343

344 345 346 347 348 349
* [[yii\helpers\Html]]
* [[yii\helpers\ArrayHelper]]
* [[yii\helpers\StringHelper]]
* [[yii\helpers\FileHelper]]
* [[yii\helpers\Json]]
* [[yii\helpers\Security]]
350

351
Please refer to the [Helper Overview](helper-overview.md) section for more details.
352 353 354

Forms
-----
Qiang Xue committed
355

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

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

371 372
Please refer to the [Creating Forms](input-forms.md) section for more details.

373

Qiang Xue committed
374 375 376
Query Builder
-------------

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

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

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

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

395
Please refer to the [Query Builder](db-query-builder.md) section for more details.
Qiang Xue committed
396

397

398 399
Active Record
-------------
400

Larry Ullman committed
401
Yii 2.0 introduces a lot of changes to [Active Record](db-active-record.md). The two most obvious ones involve
402
query building and relational query handling.
403

Larry Ullman committed
404 405
The `CDbCriteria` class in 1.1 is replaced by [[yii\db\ActiveQuery]] in Yii 2. That class extends from [[yii\db\Query]], and thus
inherits all query building methods. You call [[yii\db\ActiveRecord::find()]] to start building a query:
406

407
```php
Larry Ullman committed
408
// To retrieve all *active* customers and order them by their ID:
409
$customers = Customer::find()
410 411 412
    ->where(['status' => $active])
    ->orderBy('id')
    ->all();
413
```
Alexander Makarov committed
414

Larry Ullman committed
415
To declare a relation, simply define a getter method that returns an [[yii\db\ActiveQuery|ActiveQuery]] object.
416 417
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()`):
418

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

Larry Ullman committed
429 430
Now you can use `$customer->orders` to access a customer's orders from the related table. You can also use the following code
to perform an on-the-fly relational query with a customized query condition:
431

432 433 434
```php
$orders = $customer->getOrders()->andWhere('status=1')->all();
```
435

436
When eager loading a relation, Yii 2.0 does it differently from 1.1. In particular, in 1.1 a JOIN query
Larry Ullman committed
437
would be created to select both the primary and the relational records. In Yii 2.0, two SQL statements are executed
438 439
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.
440

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

445
```php
446
$customers = Customer::find()->asArray()->all();
447
```
Alexander Makarov committed
448

449
There are many other changes and enhancements to Active Record. Please refer to
450
the [Active Record](db-active-record.md) section for more details.
451 452


453 454
User and IdentityInterface
--------------------------
Qiang Xue committed
455

456 457
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
Larry Ullman committed
458 459 460
is much more straightforward to use. The advanced application template provides such an example.

Please refer to the [Authentication](security-authentication.md), [Authorization](security-authorization.md), and [Advanced Application Technique](tutorial-advanced-app.md) sections for more details.
461 462


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

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

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

Larry Ullman committed
479
Please refer to the [Url manager docs](url.md) section for more details.
480 481 482 483

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

Larry Ullman committed
484
If you have legacy Yii 1.1 code that you want to use together with Yii 2.0, please refer to
485
the [Using Yii 1.1 and 2.0 Together](extend-using-v1-v2.md) section.
486