UPGRADE.md 6.87 KB
Newer Older
1 2 3 4 5 6 7 8 9
Upgrading Instructions for Yii Framework v2
===========================================

!!!IMPORTANT!!!

The following upgrading instructions are cumulative. That is,
if you want to upgrade from version A to version C and there is
version B between A and C, you need to following the instructions
for both A and B.
10 11 12 13 14 15 16


Upgrade from Yii 2.0 Beta
-------------------------

* If you used `clearAll()` or `clearAllAssignments()` of `yii\rbac\DbManager`, you should replace
  them with `removeAll()` and `removeAllAssignments()` respectively.
17

18 19 20
* If you created RBAC rule classes, you should modify their `execute()` method by adding `$user`
  as the first parameter: `execute($user, $item, $params)`. The `$user` parameter represents
  the ID of the user currently being access checked. Previously, this is passed via `$params['user']`.
21 22 23

* If you override `yii\grid\DataColumn::getDataCellValue()` with visibility `protected` you have
  to change visibility to `public` as visibility of the base method has changed.
24 25 26 27 28 29 30 31

* If you have classes implementing `yii\web\IdentityInterface` (very common), you should modify
  the signature of `findIdentityByAccessToken()` as
  `public static function findIdentityByAccessToken($token, $type = null)`. The new `$type` parameter
  will contain the type information about the access token. For example, if you use
  `yii\filters\auth\HttpBearerAuth` authentication method, the value of this parameter will be
  `yii\filters\auth\HttpBearerAuth`. This allows you to differentiate access tokens taken by
  different authentication methods.
32 33 34 35

* If you are sharing the same cache across different applications, you should configure
  the `keyPrefix` property of the cache component to use some unique string.
  Previously, this property was automatically assigned with a unique string.
36

Qiang Xue committed
37 38 39
* If you are using `dropDownList()`, `listBox()`, `activeDropDownList()`, or `activeListBox()`
  of `yii\helpers\Html`, and your list options use multiple blank spaces to format and align
  option label texts, you need to specify the option `encodeSpaces` to be true.
40 41 42 43 44

* If you are using `yii\grid\GridView` and have configured a data column to use a PHP callable
  to return cell values (via `yii\grid\DataColumn::value`), you may need to adjust the signature
  of the callable to be `function ($model, $key, $index, $widget)`. The `$key` parameter was newly added
  in this release.
45

46 47 48 49
* `yii\console\controllers\AssetController` is now using hashes instead of timestamps. Replace all `{ts}` with `{hash}`.

* The database table of the `yii\log\DbTarget` now needs a `prefix` column to store context information.
  You can add it with `ALTER TABLE log ADD COLUMN prefix TEXT AFTER log_time;`.
50

Qiang Xue committed
51
* The `fileinfo` PHP extension is now required by Yii. If you use  `yii\helpers\FileHelper::getMimeType()`, make sure
52 53 54 55
  you have enabled this extension. This extension is [builtin](http://www.php.net/manual/en/fileinfo.installation.php) in php above `5.3`.

* Please update your main layout file by adding this line in the `<head>` section: `<?= Html::csrfMetaTags() ?>`.
  This change is needed because `yii\web\View` no longer automatically generates CSRF meta tags due to issue #3358.
56

Qiang Xue committed
57
* If your model code is using the `file` validation rule, you should rename its `types` option to `extensions`.
Carsten Brandt committed
58 59

* `MailEvent` class has been moved to the `yii\mail` namespace. You have to adjust all references that may exist in your code.
60

61 62
* The behavior and signature of `ActiveRecord::afterSave()` has changed. `ActiveRecord::$isNewRecord` will now always be
  false in afterSave and also dirty attributes are not available. This change has been made to have a more consistent and
63
  expected behavior. The changed attributes are now available in the new parameter of afterSave() `$changedAttributes`.
Carsten Brandt committed
64
  `$changedAttributes` contains the old values of attributes that had changed and were saved.
65 66 67

* `ActiveRecord::updateAttributes()` has been changed to not trigger events and not respect optimistic locking anymore to
  differentiate it more from calling `update(false)` and to ensure it can be used in `afterSave()` without triggering infinite
68 69
  loops.

70 71 72
* If you are developing RESTful APIs and using an authentication method such as `yii\filters\auth\HttpBasicAuth`,
  you should explicitly configure `yii\web\User::enableSession` in the application configuration to be false to avoid
  starting a session when authentication is performed. Previously this was done automatically by authentication method.
73 74 75

* `mail` component was renamed to `mailer`, `yii\log\EmailTarget::$mail` was renamed to `yii\log\EmailTarget::$mailer`.
  Please update all references in the code and config files.
76

77 78 79 80 81 82
* `\yii\rbac\PhpManager` now stores data in three separate files instead of one. In order to convert old file to
new ones save the following code as `convert.php` that should be placed in the same directory your `rbac.php` is in: 

```php
<?php
$oldFile = 'rbac.php';
Alexander Makarov committed
83 84 85
$itemsFile = 'items.php';
$assignmentsFile = 'assignments.php';
$rulesFile = 'rules.php';
86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122

$oldData = include $oldFile;

function saveToFile($data, $fileName) {
    $out = var_export($data, true);
    $out = "<?php\nreturn " . $out . ";";
    $out = str_replace(['array (', ')'], ['[', ']'], $out);
    file_put_contents($fileName, $out);
}

$items = [];
$assignments = [];
if (isset($oldData['items'])) {
    foreach ($oldData['items'] as $name => $data) {
        if (isset($data['assignments'])) {
            foreach ($data['assignments'] as $userId => $assignmentData) {
                $assignments[$userId] = $assignmentData['roleName'];
            }
            unset($data['assignments']);
        }
        $items[$name] = $data;
    }
}

$rules = [];
if (isset($oldData['rules'])) {
    $rules = $oldData['rules'];
}

saveToFile($items, $itemsFile);
saveToFile($assignments, $assignmentsFile);
saveToFile($rules, $rulesFile);

echo "Done!\n";
```

Run it once, delete `rbac.php`. If you've configured `authFile` property, remove the line from config and instead
Alexander Makarov committed
123
configure `itemFile`, `assignmentFile` and `ruleFile`.
124

125 126
* Static helper `yii\helpers\Security` has been converted into an application component. You should change all usage of
  its methods to a new syntax, for example: instead of `yii\helpers\Security::hashData()` use `Yii::$app->getSecurity()->hashData()`.
127 128
  Default encryption and hash parameters has been upgraded. If you need to decrypt/validate data that was encrypted/hashed
  before, use the following configuration of the 'security' component:
129 130 131 132 133 134 135
  ```
  return [
      'components' => [
          'security' => [
              'cryptBlockSize' => 16,
              'cryptKeySize' => 24,
              'derivationIterations' => 1000,
136 137 138
              'deriveKeyStrategy' => 'hmac', // for PHP version < 5.5.0
              //'deriveKeyStrategy' => 'pbkdf2', // for PHP version >= 5.5.0
              'useDeriveKeyUniqueSalt' => false,
139
              'autoGenerateSecretKey' => true,
140 141 142 143 144
          ],
          // ...
      ],
      // ...
  ];
145
  ```