5.2RC版本升級不完全指導（僅供學習參考） · ThinkPHP官方博客

### 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`的過程中，多反饋和建議，幫助我們盡快完善和發布正式版本。