升级指导

本章节的内容告诉你进行5.1.*版本的升级须知和建议，由于一些必要原因，个别版本的升级并非完全无缝，请尽量按照本升级指导的建议进行调整。

[TOC=2,2]

从5.1.16升级到5.1.17

从5.1.16版本可以无缝升级到5.1.17。

从5.1.15升级到5.1.16

从5.1.15版本可以无缝升级到5.1.16。

不过注意一点，Request对象不再支持对请求变量的设置操作了，如果需要请使用 $request->name 的方式直接设置。

从5.1.14升级到5.1.15

从5.1.14版本可以无缝升级到5.1.15。

从5.1.13升级到5.1.14

从5.1.13版本基本可以无缝升级到5.1.14。

补充一点，如果动态配置设置view_path（在新版中不要动态配置，因为容器中的对象一旦实例化后是不会每次读取动态配置值的，减少依赖，也更方便单元测试），需要改成在控制器中调用：

$this->view->config('view_path','path');

或者使用了view方法输出的话，可以使用

thinkfacadeView::config('view_path','path');

从5.1.12升级到5.1.13

从5.1.12版本可以无缝升级到5.1.13。

从5.1.11升级到5.1.12

从5.1.11版本可以无缝升级到5.1.12。

从5.1.10升级到5.1.11

从5.1.10版本可以无缝升级到5.1.11。

从5.1.9升级到5.1.10

如果数组查询条件中使用了exists查询，必须做出如下调整：

// 错误
$where[] = ['', 'exists', 'select * from user where status = 0'];
// 正确
$where[] = ['', 'exists', Db::raw('select * from user where status = 0')];

建议的方式是使用

$model->whereExists('select * from user where status = 0')->select();

从5.1.8升级到5.1.9

从5.1.8升级到5.1.9的时候，请注意如下事项：

下面方式的数组条件查询不再使用索引数组

// 错误
$where['name'] = ['name', 'like', 'think'];
// 正确
$where[] = ['name', 'like', 'think'];

但对于基本条件查询不受影响

// 正确
$where['name'] = 'think';

但并不支持混合查询：

// 错误
$where['name'] = 'think';
$where[] = ['id', '<=', 10];

如果数组查询条件中使用了exp查询，必须做出如下调整：

// 错误
$where[] = ['id', 'exp', '>score'];
// 正确
$where[] = ['id', 'exp', Db::raw('>score')];

表达式查询方式不受影响。

如果你使用了闭包查询条件，并且使用了默认的查询缓存cache()或者cache(true)，新版本会抛出异常，请使用cache('key')替代，避免因为查询缓存无效而影响业务。

另外可能不影响但推荐使用的建议：

order/field/where方法如果使用字符串参数并涉及到SQL函数的，推荐使用orderRaw/fieldRaw/whereRaw方法，或者对传入的字符串参数使用Db::raw()方法。

从5.1.7升级到5.1.8

从5.1.7版本可以无缝升级到5.1.8。

如果你从5.1.5直接升级的话，可以通过配置 template.auto_rule 参数为2，兼容之前的默认模板渲染规则。

从5.1.6升级到5.1.7

从5.1.6版本可以无缝升级到5.1.7。

从5.1.5升级到5.1.6

从5.1.5升级到5.1.6的过程需要注意如下事项：

路由变量规则调整

路由变量规则的定义不再支持使用模式修饰符和诸如^d+$这种限定符。

例如

Route::rule('hello/:name','hello')
    ->pattern('name','/^w{4}+$/i');

需要调整为

Route::rule('hello/:name','hello')
    ->pattern('name','w{4}+');

路由标识用法调整

原来的

Route::name('路由标识')->rule('rule','route');

需要改成

Route::rule('rule','route')->name('路由标识');

EXP表达式更新

出于安全性考虑，如果使用了EXP表达式更新，请使用exp方法替代数组方式。

默认模板渲染规则改进

由于fetch方法和view函数的默认模板规则调整为操作方法的名称（不含操作后缀）转换为小写+下划线方式，而不是原来的直接把操作名称转小写。

举个例子，你的控制器操作方法名如果是helloWorld，之前版本使用：

$this->fetch();
// 或者
view();

渲染输出的时候会定位到 helloworld.html模板文件，而新版会自动定位到hello_world.html模板文件。

对于指定模板渲染的fetch方法和view助手函数不受影响，对于非驼峰操作方法名也没有影响。

从5.1.0升级到5.1.5

从5.1.0版本可以无缝升级到5.1.5（包含以下任何一个版本）。

从5.0升级到5.1

由于5.1版本很多用法不同于5.0版本，本篇内容帮助你更顺利的从5.0版本迁移到5.1版本。

如非必要，在建项目请勿盲目升级，5.0版本依然持续维护中。

命名空间调整

如果你自定义了应用类库的命名空间，需要改为设置环境变量APP_NAMESPACE而不是应用配置文件，如果你使用了.env配置文件，可以在里面添加：

APP_NAMESPACE = 你的应用类库根命名空间名

然后，检查你的应用类库中use或者调用的系统类库，如果使用了下面的系统类库（主要涉及的类库是5.0静态调用的系统类库），那么命名空间需要调整如下：

如果只是用于依赖注入则无需更改命名空间。

后面括号里面的类名使用是的根命名空间（），这是因为5.1对常用的系统核心类库做了类库别名，举个例子，如果应用类库开头use了 thinkUrl

use thinkUrl;
Url::build('index/index');

则需要改成

use thinkfacadeUrl;
Url::build('index/index');

或者

use Url;
Url::build('index/index');

5.1为系统的类库注册了类库别名，因此可以直接从根命名空间方式调用Url。

所以路由配置文件在迁移到5.1版本后你可以直接删除下面的一行代码

use thinkRoute;

配置文件调整

原有的配置文件config.php从应用目录移动到和应用目录同级的config目录，并拆分为app.php、cache.php 等独立配置文件，系统默认的配置文件清单如下：

换而言之就是原来所有的一级配置都独立为一个配置文件

原来的应用extra目录下面的配置文件直接移动到config目录下面。 原来模块的配置文件（包括extra目录下面的）直接移动到模块下的config目录，然后参考上面的应用配置文件进行调整。

5.1的配置文件全部采用二级配置方式，所有不带一级配置名的参数都会作为app的二级配置，例如

config('app_debug');

等同于

config('app.app_debug');

并且注意，5.1的二级配置参数区分大小写。

一级配置app下的配置参数都在app.php配置文件中定义。

如果要获取数据库配置（database.php文件）的参数，则需要使用

config('database.hostname');

动态设置配置参数的时候，也要注意一级配置名

config('cache.type', 'memcache');

如果要获取一级配置下面的所有参数，使用

Config::pull('database');

view_replace_str配置参数改成template配置文件的tpl_replace_string配置参数。

常量调整

5.1取消了所有的框架内置常量（不影响应用代码中的自定义常量），如需获取，请使用thinkfacadeApp类的内置方法以及thinkfacadeEnv类获取，下面给出的是5.0和5.1的常量对照表：

通过Env类的get方法获取路径变量的时候不区分大小写，例如下面的写法是等效的：

Env::get('root_path');
Env::get('ROOT_PATH');

路由调整

原有的路由定义文件route.php 移动到应用目录同级的route目录下面，如果有定义其它的路由配置文件，一并放入route目录即可（无需更改文件名）。

url_route_on配置参数无效，会始终检查路由，没有定义路由的情况下默认解析方式依然有效。

原来的before_behavior和after_behavior参数更改为before和after，并且路由缓存功能暂时取消。

Route类的rule方法不再支持批量注册路由，请使用Route::rules方法替代。

如果使用了domain方法批量绑定模块，需要改为单独绑定，原来的用法：

Route::domain([
    'a' => 'a',
    'b' => 'b'
]);

需要改为：

Route::domain('a','a');
Route::domain('b','b');

数据库调整

• 取消了Query类的getTableInfo方法，可以用更加具体的getTableFields 或者getFieldsType方法替代；
• 数据库查询后5.1不会清空查询条件；
• 取消了select(false) 用法，使用 fetchSql()->select() 替代；
• 如果使用了mysql的JSON查询语法，user$.name 需要改为 user->name；
• 改变了查询构造器的数组多字段批量查询，从原来的

where([
    'name'  =>  ['like','think%'],
    'id'    =>  ['>',0],
])

需要调整为

where([
    ['name','like','think%'],
    ['id','>',0],
])

或者使用表达式语法

where('name','like','think%')->where('id','>',0)

对于纯等于的数组条件则无需调整

where(['name'=>'think', 'type'=>1])

模型调整

为了确保模型的用法统一，对模型进行了一些调整，包括：

• 模型的数据集查询始终返回数据集对象而不再是数组；
• 模型的数据表主键如果不是id，则必须设置模型的pk属性；
• 软删除trait引入更改为 use thinkmodelconcernSoftDelete；
• 全局查询范围base方法中无需添加软删除条件；
• 聚合模型功能废除，使用关联模型配合关联自动写入功能替代，更灵活；
• 模型的查询范围scope方法调用后只能使用数据库的查询方法；
• 取消模型的数据验证功能，请使用控制器验证或者路由验证替代；

控制器调整

为了规范化，继承了thinkController类的话，初始化方法从原来的_initialize方法更改为initialize。

fetch方法以及view助手函数的replace参数废弃，如果需要模板替换功能，改成template配置文件的tpl_replace_string配置参数。或者使用filter方法进行过滤。

官方扩展

官方的下列composer扩展请升级到最新的2.0版本：

topthink/think-captcha
topthink/think-mongo
topthink/think-migration
topthink/think-testing
topthink/think-queue

其它注意事项

Request类不再需要instance方法，直接调用类的方法即可。

废弃了Rest控制器扩展，建议更改为资源控制器的方式。 原来内置的其它控制器扩展，请自行在应用里面扩展。

因为严格遵循PSR-4规范，不再建议手动导入类库文件，所以新版取消了Loader::import方法以及import和vendor助手函数，推荐全面采用命名空间方式的类以及自动加载机制，如果必须使用请直接改为php内置的include或者require语法。

为了保持Loader类库的单纯性，原Loader类的controller、model、action和validate方法改为App类的同名方法，助手函数用法保持不变。

模板的变量输出默认添加了htmlentities安全过滤，如果你需要输出html内容的话，请使用{$var|raw}方式替换，并且date方法已经做了内部封装，无需再使用变量替换了。

最后一个步骤不要忘了：清空缓存目录下的所有文件