### 2019 年 3 月 10 日 发布 >[danger]### 本文主要用于指导开发者从`5.1`升级到`5.2`最新(RC)版本,由于`5.2`不支持`5.1`的无缝升级,下面的升级步骤和指导仅供学习参考,或有遗漏及考虑不周之处,因此不保证你的所有功能都能正常升级。在建项目应该在官方正式发布`5.2`版本之后,再进行升级为宜。 `5.2`版本必须使用`composer`安装,所以你需要首先安装新的`5.2`版本,然后把原来`5.1`的文件复制进去,完成升级工作。 ~~~cmd composer create-project topthink/think:5.2.x-dev tp ~~~ 安装完成后,把原来`application`目录下面的文件复制到`app`目录下面,然后把`config`和`route`目录下的文件复制到同名目录下。接下来,按照下面的步骤来升级操作。 >[info] 从`5.1`多模块迁移到`5.2`的多应用后,应用类库的命名空间原则上可以无需调整,但不再支持跨应用调用(包括路由,每个应用的路由是独立的),这点务必引起重视。 [TOC=2,2] ## 第一步:入口文件修改 如果你之前是多模块模式,你需要按照下面的方式修改默认入口文件,增加`autoMulti()`方法。 ~~~ <?php // [ 应用入口文件 ] namespace think; require __DIR__ . '/../vendor/autoload.php'; // 执行应用并响应 (new App())->autoMulti() ->initialize() ->run() ->send(); ~~~ 更改后,可以删除`app`目录下的默认自带的`controller`目录,这些文件已经不再需要。 如果你原来的默认模块不是`index`,那么还需要调用`name`方法(假如默认模块之前是`home`)。 ``` // 执行应用并响应 (new App())->autoMulti() ->name('home') ->initialize() ->run() ->send(); ``` 如果你之前是单一模块模式,那么入口文件可以保持默认代码不变。 ~~~ <?php // [ 应用入口文件 ] namespace think; require __DIR__ . '/../vendor/autoload.php'; // 执行应用并响应 (new App())->initialize() ->run() ->send(); ~~~ 如果你自定义了访问控制器层的名称,那么需要在入口文件的`initialize()`方法之前调用。 ``` ->controllerLayer('layer_name') ``` 如果你更改了默认的空控制器名,那么需要在入口文件中添加 ``` ->emptyController('你的空控制器名称') ``` 如果你的控制器类开启了类后缀,需要在入口文件中添加 ``` ->controllerSuffix() ``` ## 第二步:配置调整 请按照如下顺序检查及调整你的配置文件和相关配置代码。 ### 配置获取调整 原来获取一级配置参数的方式 ``` Config::pull('app'); ``` 需要改成 ``` Config::get('app'); ``` 所有的配置读取必须从第一级配置开始,例如,原来的 ``` Config::get('exception_handle'); ``` 必须改成 ``` Config::get('app.exception_handle'); ``` ### 废弃动态设置 动态更改配置参数的用法已经废弃,下面的用法不再支持。 ``` Config::set('route.default_return_type', 'json'); ``` 如果你需要把数据库的配置参数读入配置,可以使用 ``` $config = Db::name('config')->column('value', 'name'); Config::set($config, 'route'); ``` ### `Config`类不再支持数组方式读取 `Config`类不再使用`ArrayAccess`接口,因此不再支持数组方式读取。 ### 路由和URL配置独立 路由和URL请求相关的配置参数独立为`route.php`配置文件,而不再使用`app.php`配置文件。 ## 第三步:路由和请求调整 ### 路由定义文件位置调整 单应用模式下,路由定义文件和之前一样就在`route`目录下面,如果你的项目是采用了多应用的话,每个应用的路由定义和匹配都是独立的,也没有模块的概念,路由定义文件的位置应该是在`route/应用子目录`下面,例如: ~~~ route/index/route.php // index应用的路由定义文件 route/index/web.php // index应用的第二个路由定义文件 route/admin/route.php // admin应用的路由定义文件 ~~~ > 应用的路由规则其实是定义的入口文件(或者应用名)后面的URL部分,而不包含应用。 ### 路由注册方法调整 首先如果你的路由定义采用的是返回数组形式,全部改成方法定义。 例如: ~~~ return [ 'hello/:name' => 'index/hello', ]; ~~~ 必须改成: ~~~ Route::get('hello/:name', 'index/hello'); ~~~ 如果路由定义方法(包括`rule`/`get`/`post`/`put`/`delete`/`patch`/`miss`/`group`等方法)使用了`option`和`pattern`参数,全部改成方法调用形式,例如原来的: ~~~ Route::get('hello/:name', 'index/hello', [ 'ext' => 'html'], [ 'name' => '\w+']); ~~~ 需要改成 ~~~ Route::get('hello/:name', 'index/hello') ->ext('html') ->pattern([ 'name' => '\w+']); ~~~ ### 路由分组调整 如果路由分组定义使用了数组,改成闭包方式定义,例如: ~~~ Route::group('blog', [ ':id' => 'Blog/read', ':name' => 'Blog/read', ])->ext('html')->pattern(['id' => '\d+']); ~~~ 必须改成 ~~~ Route::group('blog', function() { Route::get(':id', 'Blog/read'); Route::get(':name', 'Blog/read'); })->ext('html')->pattern(['id' => '\d+']); ~~~ 如果你需要注册一个虚拟的路由分组,可以直接在第一个参数使用闭包 ~~~ Route::group(function() { Route::get('blog/:id', 'Blog/read'); Route::get('user/:name', 'User/read'); })->ext('html')->pattern(['id' => '\d+']); ~~~ ### 取消了`url_controller_layer`配置 改为在入口文件中使用`controllerLayer`方法设置。 ~~~ (new App())->controllerLayer('Action') ->initialize() ->run() ->send(); ~~~ ### 取消`controller_suffix`配置 改为在入口文件中使用`useClassSuffix`方法设置。 ~~~ (new App())->useClassSuffix(true) ->initialize() ->run() ->send(); ~~~ 同时`class_suffix`配置参数已经无效。 ### 取消`mergeExtraVars`方法和对应参数 改为在路由规则中明确指定变量规则。 ### `header`方法参数类型调整 由于强类型约束的原因,`header`方法改为仅支持数组参数传入。 ### 取消`Request`类的`hook`方法 由于不建议扩展`Request`类的方法,该方法已经在最新版本中取消。如果你使用了该功能,只能自定义请求对象(必须继承`think\Request`),然后在入口文件中绑定`request`到容器。 ``` bind('request', new \my\Request()); ``` ### 取消`URL`参数模式配置 原来的URL参数模式配置参数`url_param_type`,统一使用参数/值的方式。如果你设置了该配置参数为1,必须改成定义路由的方式。 ### 取消别名路由 因为使用场景有限和性能开销问题,取消原来的别名路由功能,建议使用资源路由或者单独的路由替代。 ### 取消快捷路由 因为使用场景有限和不太符合规范,取消了原来的控制器快捷路由功能。 ### 取消空操作功能 建议使用分组MISS路由功能替代。 ## 第四步:控制器和视图调整 ### 视图和模板引擎从核心分离 视图和模板引擎类不再内置到核心框架,但使用 ~~~ composer create-project topthink/think ~~~ 会默认安装该组件(如果不需要使用的话可以自己卸载`topthink/think-view`)。 安装后,由于内置的`think\Controller`类不再封装视图方法,如果你的控制器类需要调用`fetch`/`display`/`assign`等视图方法,必须改为继承`think\ViewController`类,如果是使用`view`助手函数方式的话,可以无需调整。 ### `assign`方法调整 `assign`方法只能传入数组,统一设置模板变量。建议统一使用`view`助手函数。 ### `share`方法取消 原来视图类的`share`方法取消,可以使用 ``` think\facade\View::assign($vars); ``` ## 第五步:数据库和模型调整 ### `Db`改为使用门面对象 新版的`Db`类不再是静态类,需要使用`think\facade\Db`门面进行静态代理。 ~~~ \think\facade\Db::name('user')->find(); ~~~ ### 数据库配置信息调整 数据库配置文件或者`connect`方法取消`DSN`数据库配置定义方式,全部采用数组方式配置定义。 ~~~ Db::connect('mysql://root:1234@127.0.0.1:3306/thinkphp#utf8') ->table('user') ->find(); ~~~ 必须改成 ~~~ Db::connect([ // 数据库类型 'type' => 'mysql', // 服务器地址 'hostname' => '127.0.0.1', // 数据库名 'database' => 'thinkphp', // 数据库用户名 'username' => 'root', // 数据库密码 'password' => '1234', // 数据库连接端口 'hostport' => '3306', // 数据库连接参数 'params' => [], // 数据库编码默认采用utf8 'charset' => 'utf8', ]) ->table('user') ->find(); ~~~ ### 取消`fetchPdo`方法 取消了`Query`类的`fetchPdo`方法,需要的时候直接使用`getPdo`方法替代。 ### 取消查询方法传入`Query`对象 取消Query类的CURD查询方法传入当前对象,如果需要请使用闭包替代。 ### `insert`/`insertGetId`/`insertAll`方法取消`replace`参数 `insert`/`insertGetId`/`insertAll`方法的第二个`replace`参数已经取消,改为使用`replace`方法。 ~~~ $data = ['foo' => 'bar', 'bar' => 'foo']; Db::name('user')->insert($data, true); ~~~ 需要改为 ~~~ $data = ['foo' => 'bar', 'bar' => 'foo']; Db::name('user')->replace()->insert($data); ~~~ ### 取消`db`和`model`助手函数 这两个助手函数`5.1`版本已经不再建议使用了,`5.2`版本已经废弃掉这两个助手函数,请直接使用`\think\facade\Db`类静态方法和实际的模型类调用。 ### 取消`setInc`/`setDec`方法 取消Query类的`setInc`/`setDec`方法,统一使用`inc`/`dec`方法替代,同时改进了`inc`/`dec`方法支持延时更新。例如: ~~~ Db::name('user')->where('id', 1) ->inc('exp') ->dec('score') ->update(); ~~~ ### 取消`setField`方法 取消Query类的`setField`方法,请直接使用`data`方法或者`update`方法。 ### 取消`__TABLE_NAME__`支持 `table`方法取消`__TABLE_NAME__`支持,必须明确调用完整表名或者使用`name`方法。 ### 取消`whereOr`等方法传入`Query`对象 因为`Query`对象查询只能使用一次,除了`where`方法本身可以传入`Query`对象外,其它的所有`where`查询方法(例如`whereOr`/`whereExp`等)都不再支持传入`Query`对象。 ### 取消`resultset_type`配置参数 数据集查询结果不再受`resultset_type`配置参数影响,默认情况下,Db查询统一返回数组,模型查询统一返回模型对象和模型数据集对象。如果Db查询的时候也需要返回数据集的话,可以显式调用`fetchCollection`方法。 ### 取消`Query`类的`extend`方法 取消了`Query`类的`extend`方法,如果需要扩展查询方法,建议自定义`Query`类并继承系统的`think\db\Query`类即可,然后在模型中定义`query`属性或者配置数据库连接的`query`参数为你的自定义类。 ### `Expression`对象调整 原来的`Expression`对象已经更改为更适合的`Raw`对象,但不影响`Db::raw()`方法的调用。 ### 取消查询`eq/neq/gt/lt/egt/elt`表达式 由于存在两种用法,并且不够直观,全部统一为更直观的用法。 下面的用法不再支持 ~~~ Db::name('user')->where('id', 'egt', 1) ->where('status', 'neq' ,1) ->select(); ~~~ 统一使用 ~~~ Db::name('user')->where('id', '>=', 1) ->where('status', '<>' ,1) ->select(); ~~~ ### 取消分表功能 出于分表的性能问题和复杂性,不再提供分表方法,建议使用数据库的分区功能替代。新版可以使用`partition`方法指定当前查询的分区。 ### 数据库的查询统计合并 数据库的查询次数合并到`queryTimes`,不再区分读写操作,你可以使用下面的方法获取当前请求的数据库查询次数(包括读写) ~~~ Db::getQueryTimes(); ~~~ ### 取消了模型的`get`/`all`方法 无论使用`Db`类还是模型类查询,全部统一使用`find`/`select`方法,取消了之前模型类额外提供的`get`/`all`方法。同时取消的方法还包括`getOrFail`/`allOrFail`。 ### 取消全局查询范围`base`方法 取消模型类的全局查询范围`base`方法,改由使用`globalScope`属性定义(数组)需要全局查询的查询范围方法。或者在`db($scope)`方法中传入全局查询范围。如果是静态查询,可以使用`useGlobalScope($scope)`。 ### 模型事件调整 模型事件不再支持使用`event`方法注册事件,统一使用模型事件观察者类,你只需要在模型定义或者初始化的时候设置`observerClass`属性。 ~~~ <?php namespace app\index\model; use think\Model; class User extends Model { protected $observerClass = 'app\index\observe\User'; } ~~~ 所有的模型事件统一在观察者类中进行定义,方法的命名规范如下: ~~~ <?php namespace app\index\observe; class User { public function onAfterRead($user){ $user->extra = 'extra'; } public function onBeforeWrite($user){ $user->extra = 'extra'; } } ~~~ 并且模型增加`after_read`事件,在查询后创建模型对象实例的时候触发。 ### 模型属性和数据表字段的对应关系 默认情况下,模型对象数据字段严格区分大小写,你可以关闭严格模式(前提是必须保持数据表字段的小写和下划线定义规范),然后在模型中使用的时候,如果使用驼峰命名调用,则会自动转换为小写和下划线规范的字段(关连模型除外),例如: ~~~ <?php namespace app\index\model; use think\Model; class User extends Model { protected $strict = false; } ~~~ 然后,下面的代码 ~~~ $user = User::find(); echo $user->nick_name; $user->nick_name = 'test'; $user->save(); ~~~ 和下面的用法是等效的 ~~~ $user = User::find(); echo $user->nickName; $user->nickName = 'test'; $user->save(); ~~~ > 如果你的数据表字段不符合规范(存在大小写混合使用的情况),那么必须在模型中开启`strict`属性。 ### 模型`save`方法调整 模型类的`save`方法不再支持`where`参数。 ### 关联统计调整 如果你的关联统计使用了闭包方式返回关联统计字段,需要调整为如下方式: ``` User::withCount(['cards' => function($query,&$name) { $query->where('status', 1); $name = 'card_count'; }])->select(); ``` ### 模型和数据集的输出调整 取消`hidden`/`visible`/`append`方法的第二个参数,当你调用这几个方法的时候,无论模型是否设置了相关属性,都会直接覆盖之前设置的值。 ### 查询缓存调整 如果希望在更新和删除之后自动清除之前的查询缓存,必须在`cache`方法中传入key值而不是`true`。 ### 删除关联类`selfRelation`方法 如果你在定义关联的时候使用了`selfRelation`方法,请直接删除该方法,目前已经不再需要,会自动识别是否为自关联。 ### 删除关联类的`setEagerlyType`方法 一对一关联无需在定义关联的时候指定为`JOIN`查询,在查询的时候直接使用`withJoin`方法即可使用`JOIN`方式进行关联查询。 ### 多对多关联 多对多关联的`pivotDataName`方法更名为更简单的`name`方法。 ## 第六步:行为调整 行为和`Hook`已经用新版的事件机制替代,需要把你的行为改成事件响应或者中间件(部分请求拦截的行为可以直接改为中间件)。 原来的系统内置钩子的行为类 ~~~ <?php namespace app\index\behavior; class Hello { public function run($params) { // 行为逻辑 } } ~~~ 可以改成事件监听类 ~~~ namespace app\index\listener; class Hello { public function handle($event) { // 事件监听处理 } } ~~~ 然后在应用目录的`event.php`文件中配置事件监听。 ~~~ return [ 'listen' => [ 'AppBegin' => ['\app\index\listener\Hello'], // 更多事件监听 ], ]; ~~~ 如果有自定义的钩子,首先需要创建事件类,可以通过命令行生成事件类。 ~~~ php think make:event index@UserLogin ~~~ 会生成`index`应用下面的`UserLogin`事件类。 ~~~ <?php namespace app\index\event; class UserLogin { } ~~~ 然后生成监听器 ~~~ php think make:listener index@UserLogin ~~~ ~~~ <?php namespace app\index\listener; class UserLogin { public function handle($event) { // 事件监听处理 } } ~~~ 在`event.php`定义文件中添加 ~~~ return [ 'bind' => [ 'UserLogin' => ['\app\index\event\UserLogin'], ], 'listen' => [ 'UserLogin' => ['\app\index\listener\UserLogin'], ], ]; ~~~ 修改完成后,你可以删除应用目录下不再使用的`tags.php`文件。 内置事件和钩子的对应关系如下: | 事件| 对应`5.1`钩子| 参数 | | --- | --- | --- | | `AppInit` | `app_init `| 无 | | `AppBegin` | `app_begin` | 无 | | `AppEnd` | `app_end `| 当前响应对象实例 | | `LogWrite` | `log_write `| 当前写入的日志信息 | | `LogLevel` | `log_level `| 包含日志类型和日志信息的数组 | | `ResponseSend` | `response_send `| 当前响应对象 | | `ResponseEnd` | `response_end `| 当前响应对象 | >[danger] 原来的`action_begin`、`module_init`和`view_filter`钩子已经废弃。 ## 第七步:其它调整及注意事项 ### 应用类库后缀规范 取消了`controller_suffix`和`class_suffix`配置参数,App类增加了`controllerSuffix`方法用于开启控制器类库的`Controller`后缀(默认不开启)。其它应用类库的后缀由项目自己决定,框架不再强制规范。 >[info] 需要注意的是,如果你的模型类命名使用了`Model`后缀的话,一定要定义`name`属性或者`table`属性。 ### 系统`Facade`类库别名取消 系统`Facade`类库的别名已经取消,因此不能再使用 ``` use Route; Route::rule('hello/:name', 'index/hello'); ``` 必须使用 ``` use think\facade\Route; Route::rule('hello/:name', 'index/hello'); ``` ### 严格类型检查 由于新版框架核心类库全面启用强类型参数,并且使用严格模式,所以在调用系统方法的时候一定要注意参数的类型,或者注意看抛出的异常信息进行修正。 >[success]### 最后,希望你的`5.2`升级之旅顺利^_^ 希望大家在升级和使用`5.2`的过程中,多反馈和建议,帮助我们尽快完善和发布正式版本。