4.2 PhalApi 2.x 升級指南 · PhalApi 2.x 開發文檔

# PhalApi 2.x 升級指南 PhalApi自2015年初正式開源以來，版本主要經歷了 v1.0.0 ~ v1.4.1，其間，我們一直在致力于“接口，從簡單開始！”的同時，也致力框架的兼容性升級。但考慮到2.x版本是全新的實現機制和方式，經過綜合和慎重考慮，2.x版本將不再支持向前兼容，即1.x版本不能完美升級到2.x版本。對此帶來的不便，我深表歉意。為方便1.x版本的開發者更容易從概念上切換到2.x版本，以下是快速升級指南。 ## 從石器農耕到現代自動化自2017年x月x日發布 v2.0.0 版本開始，PhalApi社區主要存在兩大系列版本，分別是： + **PhalApi v1.x 版本** slogan：接口，從簡單開始！ + **PhalApi v2.x 版本** slogan：助你創造價值！這兩系列版本，最大的差異在于，PhalApi v2.x 版本是： + 使用了composer + 引入了命名空間 + 遵循psr-4規范相比之下，PhalApi v1.x 版本則是： + 未使用composer，自主構建自動加載器PhalApi_Loader + 完全不使用命名空間 + 遵循psr-0規范以及PEAR命名規范使用composer的方式，更有利于可重用組件的管理，并且向國際化、向主流靠攏，同時也要求我們需要對PhalApi進行重新劃分與調整。而引入命名空間，則更是要求核心框架代碼、擴展類庫乃至應用項目開發，都需要重新調整。這是歷史發展的必然趨勢，因為composer和命名空間將會被越來越多的開發人員所熟悉。如果在1.x版本，我們是石器農耕時代，那么2.x版本，我們迎來的將是現代自動化時代。 > 溫馨提示：關于composer，更多可訪問：[Composer 中文網 / Packagist 中國全量鏡像](http://www.phpcomposer.com/)。 ## composer的使用方式在1.x版本中，PhalApi更多是以自主研發的自動加載方式為主，這種方式原始、簡單，并且粗糙。在2.x版本中，PhalApi使用的是composer管理方式，這要求對已有的代碼倉庫進行重新劃分，并分為：項目、擴展類庫和核心框架這三部分。 + 項目：可用于實際項目開發，提供給開發人員使用。 + 擴展類庫：由廣大開發人員共同維護、分享。 + 核心框架：由PhalApi團隊核心人員長期維護，并接受貢獻者的merge request。 ### 如何創建新項目？如果需要使用PhalApi 2.x 版本開發新項目，可以直接使用[phalapi/phalapi](https://github.com/phalapi/phalapi)。在composer方式下，當需要自動加載類和函數時，可使用autoload配置，參考： ``` { "autoload": { "files": [ "src/app/functions.php" ], "psr-4": { "App\\": "src/app" } } } ``` ### 如何使用擴展類庫? 當需要使用擴展類庫時，你只需要簡單的告訴 Composer 需要依賴哪些包。在composer.json中添加相應的包名稱和版本信息，然后更新即可。以添加Task計劃任務擴展為例，首先修改composer.json并添加： ``` { "require": { "phalapi/task": "1.0.*" } } ``` 然后，進行composer更新： ```bash $ composer update ``` 如果擴展類庫還提供了直接可用的接口服務，這里則還需要配置psr-4，以便讓composer能正常自動加載對應的類文件，并且顯示在在線接口文檔。 ### 如何升級框架？借助composer，可輕松更新框架，同時也可以指定需要依賴的具體版本。例如，若希望從2.0.0升級到2.0.1版本，可以： ``` { "require": { "phalapi/kernal": "2.0.1" } } ``` 然后，進行composer更新即可。 ## 命名空間下的差異由于PhalApi 1.x 版本不使用命名空間，而PhalApi 2.x 版本使用了命名空間，因此會有所差異。主要有： ### 接口服務請求時的差異 1.x 版本的默認接口服務是```Default.Index```，對應文件```./Demo/Api/Default.php```；2.x 版本的默認接口服務是```App.Site.Index```，對應文件```./src/app/Api/Site.php```。 1.x 版本的接口服務的請求格式是：Class.Action；2.x 版本的接口服務的請求格式是：Namespace.Class.Action，比舊版本多了命名空間前綴，并且為了兼容原來的格式，缺省的命名空間是App。當命名空間和類名空間存在多組時，將會使用下劃線分割。以下是2.x版本的一些示例： 2.x 請求的service參數|對應的文件|執行的類方法 ---|---|--- 無|./src/app/Api/Site.php|App/Api/Site::Index() ?s=Site.Index|./src/app/Api/Site.php|App/Api/Site::index() ?s=Weibo.Login|./src/Api/Weibo.php|App/Api/Weibo::login() ?s=User.Weibo.Login|./src/user/Api/Weibo.php|User/Api/Weibo::login() ?s=App_User.Third_Weibo.Login|./src/app/user/Api/Third/Weibo.php|App/User/Api/Third/Weibo::login() ### Model層自動匹配的表名差異在1.x 版本中，默認表名的自動匹配規則是：取Model_后面部分的字符全部轉小寫。例如： ```php <?php class Model_User extends PhalApi_Model_NotORM { } ``` 類Model_User自動匹配的表名為```user```。在2.x 版本中，規則類似，但由于多了命名空間，默認表名的自動匹配規則是：取```\Model\```后面部分的字符全部轉小寫，將用下劃線分割。例如： ```php <?php namespace App\Model\User; use PhalApi\Model\NotORMModel as Model; class Friends extends Model { } ``` 則類App\Model\User\Friends自動匹配的表名為```user_friends```。以下是2.x版本的一些示例： 2.x 的Model類名|對應的文件|自動匹配的表名 ---|---|--- App\Model\User|./src/app/Model/User.php|user App\ModelUser\Friends|./src/app/Model/User/Friends.php|user_friends App\User\Model\Friends|./src/app/user/Model/Friends.php|friends App\User\Model\User\Friends|./src/app/user/Model/User/Friends.php|user_friends 和1.x 版本相同的是，自動匹配的表名后面會自動加上表前綴。當自動匹配的表名不能滿足實際開發需求時，1.x 和 2.x 版本均支持自定義表名。 ## 可訪問的入口差異在PhalApi 1.x 版本中，對外可訪問的入口主要有： + 不同項目的訪問入口，如：/Public/demo/index.php + 在線接口列表文檔，如：/Public/demo/listAllApis.php + 在線接口詳情文檔，如：/Public/demo/checkApiParams.php 如何訪問在線接口文檔？鑒于PhalApi 1.x版本中的訪問入口過于分散，且在線接口文檔鏈接過于冗長，在PhalApi 2.x 版本中，我們同時對此進行了優化。即精簡為： + 訪問入口默認只有一個，即：/public/index.php + 在線接口列表與接口詳情文檔，二合為一，鏈接改為：/public/docs.php ## 項目目錄結構的差異在PhalApi 1.x中，項目目錄結構為： ```bash . │ ├── PhalApi //PhalApi框架，后期可以整包升級 ├── Library //PhalApi擴展類庫，可根據需要自由添加擴展 ├── SDK //PhalApi提供的SDK包，客戶可根據需要選用 │ │ ├── Public //對外訪問目錄，建議隱藏PHP實現 │ └── demo //Demo服務訪問入口 │ │ ├── Config //項目接口公共配置，主要有：app.php, sys.php, dbs.php ├── Data //項目接口公共數據 ├── Language //項目接口公共翻譯 ├── Runtime //項目接口運行文件目錄，用于存放日記，可軟鏈到別的區 │ │ └── Demo //應用接口服務，名稱自取，可多組 ├── Api //接口響應層 ├── Domain //接口領域層 ├── Model //接口持久層 └── Tests //接口單元測試 ``` 在PhalApi 2.x中，項目目錄結構為： ```bash . │? ├── config // 項目接口公共配置 │?? ├── app.php // 項目配置 │?? ├── dbs.php // 數據庫配置 │?? ├── di.php // DI依賴注入配置 │?? └── sys.php // 系統環境配置 │? ├── public // 對外訪問目錄，推薦將web根路徑設定在此目錄 │?? ├── docs.php // 自動生成的在線接口文檔 │?? ├── examples // 示例 │?? ├── index.php // 接口服務統一訪問入口 │?? └── init.php // 統一初始化文件 ├── runtime // 項目運行時產生的文件目錄 │? ├── src // 項目PHP源代碼 │?? └── app // 默認使用此App命名空間，可創建多上命名空間 │?? ├── Api // 接口響應控制層 │?? ├── Domain // 接口領域業務層 │?? ├── functions.php // 面向過程式的函數 │?? └── Model // 接口數據模型層 ├── tests // 單元測試 │? ├── bin // 腳本命令 ├── data // 用于存放SQL建表基本語句 ├── language // 語言翻譯包 ├── sdk // 客戶端SDK開發包，支持9+種語言 │? ├── composer.json // composer.json文件 └── vendor // 依賴安裝包 ``` 主要區別在于，對于不放置PHP源代碼的目錄，全部改用小寫。 ## 附錄：對照表 ### 附錄1：類對照表以下是PhalApi 2.x 與PhalApi 1.x 的類對照關系。 PhalApi v2.x |PhalApi v1.x |備注 ---|---|--- PhalApi\PhalApi|PhalApi| PhalApi\Api|PhalApi_Api| PhalApi\ApiFactory|PhalApi_ApiFactory| PhalApi\Cache|PhalApi_Cache| PhalApi\Cache\APCUCache|PhalApi_Cache_APCU| PhalApi\Cache\FileCache|PhalApi_Cache_File| PhalApi\Cache\MemcacheCache|PhalApi_Cache_Memcache| PhalApi\Cache\MemcachedCache|PhalApi_Cache_Memcached| PhalApi\Cache\MultiCache|PhalApi_Cache_Multi| PhalApi\Cache\NoneCache|PhalApi_Cache_None| PhalApi\Cache\RedisCache|PhalApi_Cache_Redis| PhalApi\Config|PhalApi_Config| PhalApi\Config\FileConfig|PhalApi_Config_File| PhalApi\Config\YaconfConfig|PhalApi_Config_Yaconf| PhalApi\Cookie|PhalApi_Cookie| PhalApi\Cookie\MultiCookie|PhalApi_Cookie_Multi| PhalApi\Crypt|PhalApi_Crypt| PhalApi\Crypt\McryptCrypt|PhalApi_Crypt_Mcrypt| PhalApi\Crypt\MultiMcryptCrypt|PhalApi_Crypt_MultiMcrypt| PhalApi\Crypt\RSA\KeyGenerator|PhalApi_Crypt_RSA_KeyGenerator| PhalApi\Crypt\RSA\MultiBase|PhalApi_Crypt_RSA_MultiBase| PhalApi\Crypt\RSA\MultiPri2PubCrypt|PhalApi_Crypt_RSA_MultiPri2Pub| PhalApi\Crypt\RSA\MultiPub2PriCrypt|PhalApi_Crypt_RSA_MultiPub2Pri| PhalApi\Crypt\RSA\Pri2PubCrypt|PhalApi_Crypt_RSA_Pri2Pub| PhalApi\Crypt\RSA\Pub2PriCrypt|PhalApi_Crypt_RSA_Pub2Pri| PhalApi\CUrl|PhalApi_CUrl| PhalApi\Database|PhalApi_DB| PhalApi\Database\NotORMDatabase|PhalApi_DB_NotORM|改用Database全稱 PhalApi\DependenceInjection|PhalApi_DI|改用DependenceInjection全稱 PhalApi\Exception|PhalApi_Exception| PhalApi\Exception\BadRequestException|PhalApi_Exception_BadRequest| PhalApi\Exception\InternalServerErrorException|PhalApi_Exception_InternalServerError| PhalApi\Exception\RedirectException|PhalApi_Exception_Redirect| PhalApi\Filter|PhalApi_Filter| PhalApi\Filter\NoneFilter|PhalApi_Filter_None| PhalApi\Filter\SimpleMD5Filter|PhalApi_Filter_SimpleMD5| PhalApi\Helper\ApiDesc|PhalApi_Helper_ApiDesc|應用層不用關注 PhalApi\Helper\ApiList|PhalApi_Helper_ApiList|應用層不用關注 PhalApi\Helper\ApiOnline|PhalApi_Helper_ApiOnline|應用層不用關注 PhalApi\Helper\TestRunner|PhalApi_Helper_TestRunner| PhalApi\Helper\Tracer|PhalApi_Helper_Tracer| PhalApi\Loader|PhalApi_Loader| PhalApi\Logger|PhalApi_Logger| PhalApi\Logger\ExplorerLogger|PhalApi_Logger_Explorer| PhalApi\Logger\FileLogger|PhalApi_Logger_File| PhalApi\Model|PhalApi_Model| PhalApi\Model\NotORMModel|PhalApi_Model_NotORM| PhalApi\Model\Proxy|PhalApi_ModelProxy| PhalApi\Model\Query|PhalApi_ModelQuery| PhalApi\Request|PhalApi_Request| PhalApi\Request\Formatter|PhalApi_Request_Formatter| PhalApi\Request\Formatter\ArrayFormatter|PhalApi_Request_Formatter_Array|應用層不用關注 PhalApi\Request\Formatter\BaseFormatter|PhalApi_Request_Formatter_Base|應用層不用關注 PhalApi\Request\Formatter\BooleanFormatter|PhalApi_Request_Formatter_Boolean|應用層不用關注 PhalApi\Request\Formatter\CallableFormatter|PhalApi_Request_Formatter_Callable|應用層不用關注 PhalApi\Request\Formatter\CallbackFormatter|PhalApi_Request_Formatter_Callback|應用層不用關注 PhalApi\Request\Formatter\DateFormatter|PhalApi_Request_Formatter_Date|應用層不用關注 PhalApi\Request\Formatter\EnumFormatter|PhalApi_Request_Formatter_Enum|應用層不用關注 PhalApi\Request\Formatter\FileFormatter|PhalApi_Request_Formatter_File|應用層不用關注 PhalApi\Request\Formatter\FloatFormatter|PhalApi_Request_Formatter_Float|應用層不用關注 PhalApi\Request\Formatter\IntFormatter|PhalApi_Request_Formatter_Int|應用層不用關注 PhalApi\Request\Formatter\StringFormatter|PhalApi_Request_Formatter_String|應用層不用關注 PhalApi\Request\Parser|PhalApi_Request_Var|重命名為Parser，避免與關鍵字var沖突 PhalApi\Response|PhalApi_Response| PhalApi\Response\ExplorerResponse|PhalApi_Response_Explorer| PhalApi\Response\JsonResponse|PhalApi_Response_Json| PhalApi\Response\JsonpResponse|PhalApi_Response_JsonP|注意p字母為小寫 PhalApi\Response\XmlResponse|PhalApi_Response_Xml| PhalApi\Tool|PhalApi_Tool| PhalApi\Translator|PhalApi_Translator| #### 類名重命名規則原來的類名遵循PEAR規范，現需要調整遵循PSR-4規范。如： ``` 原來的：PhalApi_Filter 調整后：\PhalApi\Filter ``` 對于有繼承的情況，為了避免最后的關鍵字有沖突，統一在子類后面添加父類的名稱作為后續。如： ``` 原來的： PhalApi_COnfig_File PhalApi_COnfig_Yaconf 調整后： PhalApi\Config\FileConfig PhalApi\Config\YaconfConfig ``` ### 附錄2：函數對照表以下是PhalApi 2.x 與PhalApi 1.x 的函數對照關系。 PhalApi v2.x |PhalApi v1.x |備注 ---|---|--- PhalApi\DI()|DI()| PhalApi\SL()|SL()| PhalApi\T()|T()| 函數名保持一致，但需要注意前面添加PhalApi命名空間前綴。 ### 附錄3：腳本命令對照表以下是PhalApi 2.x 與PhalApi 1.x 的腳本命令對照關系。 PhalApi v2.x |PhalApi v1.x |備注 ---|---|--- ./bin/phalapi-buildsqls|./PhalApi/phalapi-buildsqls|生成SQL語句 ./bin/phalapi-buildtest|./PhalApi/phalapi-buildtest|生成測試骨架代碼暫未遷移|./PhalApi/phalapibuildcode|創建項目代碼暫未遷移|./PhalApi/phalapi-buildapp|創建新項目，暫不需要遷移 ### 附錄4：可訪問入口對照表以下是PhalApi 2.x 與PhalApi 1.x 的可訪問入口對照關系。 PhalApi v2.x |PhalApi v1.x |備注 ---|---|--- ./public/index.php|./Public/demo/index.php|可省略index.php文件 ./public/docs.php|./Public/demo/listAllApis.php|在線接口列表文檔 ./public/docs.php?detail=1|./Public/demo/checkApiParams.php|在線接口詳情文檔，通過detail參數區分 ./public/docs/|./Public/demo/docs/|離線文檔生成目錄