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

Carsten Brandt committed
4 5 6
There are many differences between versions 1.1 and 2.0 of 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.
7

8 9
If you have not used Yii 1.1 before, you can safely skip this section and turn directly to "[Getting started](start-installation.md)".

Larry Ullman committed
10 11 12
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.
13 14 15 16 17


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

Larry Ullman committed
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
20
the [Installing Yii](start-installation.md) section to learn how to install Yii 2.0. If you want to
Larry Ullman committed
21 22
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
23

24

Qiang Xue committed
25 26 27
PHP Requirements
----------------

Larry Ullman committed
28 29
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
30
Below is a summary of the major changes regarding PHP:
31 32 33

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

Qiang Xue committed
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.
Larry Ullman committed
49 50 51 52 53
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
54 55


Qiang Xue committed
56 57 58
Component and Object
--------------------

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

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


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

72 73
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
74
it can be properly configured:
Qiang Xue committed
75

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

Qiang Xue committed
83 84 85 86 87 88
        parent::__construct($config);
    }

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

        // ... initialization after configuration is applied
Qiang Xue committed
91 92
    }
}
93
```
Alexander Makarov committed
94

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

Larry Ullman committed
100 101
By following this convention, you will be able to create and configure new objects
using a configuration array:
Qiang Xue committed
102

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

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

Qiang Xue committed
113 114 115 116

Events
------

Larry Ullman committed
117
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
118
the [[yii\base\Component::trigger()|trigger()]] method:
Qiang Xue committed
119

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

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

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

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

135

Qiang Xue committed
136 137
Path Aliases
------------
138

Larry Ullman committed
139 140
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.
141
For example, the alias `@yii` refers to the Yii installation directory. Path aliases are
Qiang Xue committed
142
supported in most places in the Yii core code. For example, [[yii\caching\FileCache::cachePath]] can take
143 144
both a path alias and a normal directory path.

Larry Ullman committed
145 146
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
147
any further configuration. For example, because `@yii` refers to the Yii installation directory,
Larry Ullman committed
148 149 150
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.
151

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

154

Qiang Xue committed
155 156
Views
-----
Qiang Xue committed
157

Larry Ullman committed
158 159 160
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
161
of the MVC pattern. If you want to access the controller or widget in a view, you can use `$this->context`.
Qiang Xue committed
162

Larry Ullman committed
163 164
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:
165 166 167 168 169

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

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)
Larry Ullman committed
174
section for more details.
175

Qiang Xue committed
176 177 178 179

Models
------

Larry Ullman committed
180 181
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.
182

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

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

Larry Ullman committed
196 197 198
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.
199

Larry Ullman committed
200
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.
201

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

Kevin LEVRON committed
206
To learn more details about models, please refer to the [Models](structure-models.md) section.
207

208

Qiang Xue committed
209 210 211
Controllers
-----------

Larry Ullman committed
212 213
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.
214

Larry Ullman committed
215 216
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:
217 218 219 220 221 222 223 224 225 226 227 228 229

```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
230
Please refer to the [Controllers](structure-controllers.md) section for more details about controllers.
231

232

233 234 235
Widgets
-------

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

Larry Ullman committed
238 239 240
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:
241 242

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

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

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

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

260

Qiang Xue committed
261 262 263
Themes
------

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

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

Kevin LEVRON committed
273
Please refer to the [Theming](output-theming.md) section for more details.
274

275

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

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

282 283 284 285
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()]].
286 287 288

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

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

291

Qiang Xue committed
292 293 294
I18N
----

Larry Ullman committed
295
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
296

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

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


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

307 308
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
309 310
code in a controller:

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

Kevin LEVRON committed
325
Please refer to the [Filtering](structure-filters.md) section for more details.
Qiang Xue committed
326 327 328 329 330


Assets
------

331
Yii 2.0 introduces a new concept called *asset bundle* that replaces the script package concept found in Yii 1.1.
332 333

An asset bundle is a collection of asset files (e.g. JavaScript files, CSS files, image files, etc.)
334 335 336
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
337
contain the references to the JavaScript and CSS files specified in that bundle.
338

339
Please refer to the [Managing Assets](structure-assets.md) section for more details.
340

341 342 343

Helpers
-------
Qiang Xue committed
344

345
Yii 2.0 introduces many commonly used static helper classes, including.
346

347 348 349 350 351
* [[yii\helpers\Html]]
* [[yii\helpers\ArrayHelper]]
* [[yii\helpers\StringHelper]]
* [[yii\helpers\FileHelper]]
* [[yii\helpers\Json]]
352

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

Forms
-----
Qiang Xue committed
357

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

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

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

375

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

379
In 1.1, query building was scattered among several classes, including `CDbCommand`,
380
`CDbCriteria`, and `CDbCommandBuilder`. Yii 2.0 represents a DB query in terms of a [[yii\db\Query|Query]] object
381
that can be turned into a SQL statement with the help of [[yii\db\QueryBuilder|QueryBuilder]] behind the scene.
382
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) section for more details.
Qiang Xue committed
398

399

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

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

Larry Ullman committed
406 407
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:
408

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

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

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

Larry Ullman committed
431 432
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:
433

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

438
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
439
would be created to select both the primary and the relational records. In Yii 2.0, two SQL statements are executed
440 441
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.
442

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

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

451 452 453 454 455 456 457 458 459 460 461
Another change is that you can't define attribute default values through public properties anymore.
If you need those, you should set them in the init method of your record class.

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

Qiang Xue committed
462
There were some problems with overriding the constructor of an ActiveRecord class in 1.1. These are not present in
463 464
version 2.0 anymore. Note that when adding parameters to the constructor you might have to override [[yii\db\ActiveRecord::instantiate()]].

465
There are many other changes and enhancements to Active Record. Please refer to
466
the [Active Record](db-active-record.md) section for more details.
467 468


Qiang Xue committed
469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500
Active Record Behaviors
-----------------------

In 2.0, we have dropped the base behavior class `CActiveRecordBehavior`. If you want to create an Active Record Behavior,
you will have to extend directly from `yii\base\Behavior`. If the behavior class needs to respond to some events
of the owner, you have to override the `events()` method like the following,

```php
namespace app\components;

use yii\db\ActiveRecord;
use yii\base\Behavior;

class MyBehavior extends Behavior
{
    // ...

    public function events()
    {
        return [
            ActiveRecord::EVENT_BEFORE_VALIDATE => 'beforeValidate',
        ];
    }

    public function beforeValidate($event)
    {
        // ...
    }
}
```


501 502
User and IdentityInterface
--------------------------
Qiang Xue committed
503

504 505
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
506 507 508
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.
509 510


Qiang Xue committed
511 512 513
URL Management
--------------

Carsten Brandt committed
514 515
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
516
both `post/popular` and `post/1/popular`. In 1.1, you would have had to use two rules to achieve
517 518
the same goal.

519
```php
Alexander Makarov committed
520
[
521 522 523
    'pattern' => 'post/<page:\d+>/<tag>',
    'route' => 'post/index',
    'defaults' => ['page' => 1],
Alexander Makarov committed
524
]
525
```
Alexander Makarov committed
526

Kevin LEVRON committed
527
Please refer to the [Url manager docs](runtime-url-handling.md) section for more details.
528 529 530 531

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

Larry Ullman committed
532
If you have legacy Yii 1.1 code that you want to use together with Yii 2.0, please refer to
Alexander Makarov committed
533
the [Using Yii 1.1 and 2.0 Together](tutorial-yii-integration.md) section.
534