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.
Upgrade from Yii 2.0 Beta
If you used
clearAll()
orclearAllAssignments()
ofyii\rbac\DbManager
, you should replace them withremoveAll()
andremoveAllAssignments()
respectively.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']
.If you override
yii\grid\DataColumn::getDataCellValue()
with visibilityprotected
you have to change visibility topublic
as visibility of the base method has changed.If you have classes implementing
yii\web\IdentityInterface
(very common), you should modify the signature offindIdentityByAccessToken()
aspublic static function findIdentityByAccessToken($token, $type = null)
. The new$type
parameter will contain the type information about the access token. For example, if you useyii\filters\auth\HttpBearerAuth
authentication method, the value of this parameter will beyii\filters\auth\HttpBearerAuth
. This allows you to differentiate access tokens taken by different authentication methods.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.If you are using
dropDownList()
,listBox()
,activeDropDownList()
, oractiveListBox()
ofyii\helpers\Html
, and your list options use multiple blank spaces to format and align option label texts, you need to specify the optionencodeSpaces
to be true.If you are using
yii\grid\GridView
and have configured a data column to use a PHP callable to return cell values (viayii\grid\DataColumn::value
), you may need to adjust the signature of the callable to befunction ($model, $key, $index, $widget)
. The$key
parameter was newly added in this release.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 aprefix
column to store context information. You can add it withALTER TABLE log ADD COLUMN prefix TEXT AFTER log_time;
.The
fileinfo
PHP extension is now required by Yii. If you useyii\helpers\FileHelper::getMimeType()
, make sure you have enabled this extension. This extension is builtin in php above5.3
.Please update your main layout file by adding this line in the
<head>
section:<?= Html::csrfMetaTags() ?>
. This change is needed becauseyii\web\View
no longer automatically generates CSRF meta tags due to issue #3358.If your model code is using the
file
validation rule, you should rename itstypes
option toextensions
.MailEvent
class has been moved to theyii\mail
namespace. You have to adjust all references that may exist in your code.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 expected behavior. The changed attributes are now available in the new parameter of afterSave()$changedAttributes
.$changedAttributes
contains the old values of attributes that had changed and were saved.ActiveRecord::updateAttributes()
has been changed to not trigger events and not respect optimistic locking anymore to differentiate it more from callingupdate(false)
and to ensure it can be used inafterSave()
without triggering infinite loops.If you are developing RESTful APIs and using an authentication method such as
yii\filters\auth\HttpBasicAuth
, you should explicitly configureyii\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.mail
component was renamed tomailer
,yii\log\EmailTarget::$mail
was renamed toyii\log\EmailTarget::$mailer
. Please update all references in the code and config files.yii\caching\GroupDependency
was renamed toTagDependency
. You should create such a dependency using the codenew \yii\caching\TagDependency(['tags' => 'TagName'])
, whereTagName
is similar to the group name that you previously used.If you are using the constant
YII_PATH
in your code, you should rename it toYII2_PATH
now.You must explicitly configure
yii\web\Request::cookieValidationKey
with a secret key. Previously this is done automatically. To do so, modify your application configuration like the following:
return [
// ...
'components' => [
'request' => [
'cookieValidationKey' => 'your secret key here',
],
],
];
Note: If you are using the
Advanced Application Template
you should not add this configuration tocommon/config
orconsole/config
because the console application doesn't have to deal with CSRF and uses its own request that doesn't havecookieValidationKey
property.
-
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 asconvert.php
that should be placed in the same directory yourrbac.php
is in:
<?php
$oldFile = 'rbac.php';
$itemsFile = 'items.php';
$assignmentsFile = 'assignments.php';
$rulesFile = 'rules.php';
$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
configure itemFile
, assignmentFile
and ruleFile
.
- 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 ofyii\helpers\Security::hashData()
useYii::$app->getSecurity()->hashData()
. 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:
return [
'components' => [
'security' => [
'cryptBlockSize' => 16,
'cryptKeySize' => 24,
'derivationIterations' => 1000,
'deriveKeyStrategy' => 'hmac', // for PHP version < 5.5.0
//'deriveKeyStrategy' => 'pbkdf2', // for PHP version >= 5.5.0
'useDeriveKeyUniqueSalt' => false,
],
// ...
],
// ...
];
- If you are using query caching, you should modify your relevant code as follows, as
beginCache()
andendCache()
are replaced bycache()
:
$db->cache(function ($db) {
// ... SQL queries that need to use query caching
}, $duration, $dependency);
Due to significant changes to security you need to upgrade your code to use
\yii\base\Security
component instead of helper. If you have any data encrypted it should be re-encrypted. In order to do so you can use old security helper as explained by @docsolver at github.[[yii\helpers\Url::to()]] will no longer prefix base URL to relative URLs. For example,
Url::to('images/logo.png')
will returnimages/logo.png
directly. If you want a relative URL to be prefix with base URL, you should make use of the alias@web
. For example,Url::to('@web/images/logo.png')
will return/BaseUrl/images/logo.png
.-
The following properties are now taking
false
instead ofnull
for "don't use" case:-
yii\bootstrap\NavBar::$brandLabel
. -
yii\bootstrap\NavBar::$brandUrl
. -
yii\bootstrap\Modal::$closeButton
. -
yii\bootstrap\Modal::$toggleButton
. -
yii\bootstrap\Alert::$closeButton
. -
yii\widgets\LinkPager::$nextPageLabel
. -
yii\widgets\LinkPager::$prevPageLabel
. -
yii\widgets\LinkPager::$firstPageLabel
. -
yii\widgets\LinkPager::$lastPageLabel
.
-
The format of the Faker fixture template is changed. For an example, please refer to the file
apps/advanced/common/tests/templates/fixtures/user.php
.-
The signature of all file downloading methods in
yii\web\Response
is changed, as summarized below:sendFile($filePath, $attachmentName = null, $options = [])
sendContentAsFile($content, $attachmentName, $options = [])
sendStreamAsFile($handle, $attachmentName, $options = [])
xSendFile($filePath, $attachmentName = null, $options = [])