PhalApi自2015年初正式開源以來,版本主要經(jīng)歷了 v1.0.0 ~ v1.4.1,其間,我們一直在致力于“接口,從簡單開始!”的同時,也致力框架的兼容性升級。但考慮到2.x版本是全新的實現(xiàn)機制和方式,經(jīng)過綜合和慎重考慮,2.x版本將不再支持向前兼容,即1.x版本不能完美升級到2.x版本。對此帶來的不便,我深表歉意。
為方便1.x版本的開發(fā)者更容易從概念上切換到2.x版本,以下是快速升級指南。
自2017年x月x日發(fā)布 v2.0.0 版本開始,PhalApi社區(qū)主要存在兩大系列版本,分別是:
這兩系列版本,最大的差異在于,PhalApi v2.x 版本是:
相比之下,PhalApi v1.x 版本則是:
使用composer的方式,更有利于可重用組件的管理,并且向國際化、向主流靠攏,同時也要求我們需要對PhalApi進行重新劃分與調(diào)整。而引入命名空間,則更是要求核心框架代碼、擴展類庫乃至應用項目開發(fā),都需要重新調(diào)整。
這是歷史發(fā)展的必然趨勢,因為composer和命名空間將會被越來越多的開發(fā)人員所熟悉。如果在1.x版本,我們是石器農(nóng)耕時代,那么2.x版本,我們迎來的將是現(xiàn)代自動化時代。
溫馨提示:關于composer,更多可訪問:Composer 中文網(wǎng) / Packagist 中國全量鏡像。
在1.x版本中,PhalApi更多是以自主研發(fā)的自動加載方式為主,這種方式原始、簡單,并且粗糙。在2.x版本中,PhalApi使用的是composer管理方式,這要求對已有的代碼倉庫進行重新劃分,并分為:項目、擴展類庫和核心框架這三部分。
如果需要使用PhalApi 2.x 版本開發(fā)新項目,可以直接使用phalapi/phalapi。
在composer方式下,當需要自動加載類和函數(shù)時,可使用autoload配置,參考:
{
"autoload": {
"files": [
"src/app/functions.php"
],
"psr-4": {
"App\\": "src/app"
}
}
}
當需要使用擴展類庫時,你只需要簡單的告訴 Composer 需要依賴哪些包。在composer.json中添加相應的包名稱和版本信息,然后更新即可。以添加Task計劃任務擴展為例,首先修改composer.json并添加:
{
"require": {
"phalapi/task": "1.0.*"
}
}
然后,進行composer更新:
$ 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參數(shù) | 對應的文件 | 執(zhí)行的類方法 |
---|---|---|
無 | ./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() |
在1.x 版本中,默認表名的自動匹配規(guī)則是:取Model_后面部分的字符全部轉(zhuǎn)小寫。例如:
<?php
class Model_User extends PhalApi_Model_NotORM {
}
類Model_User自動匹配的表名為user
。
在2.x 版本中,規(guī)則類似,但由于多了命名空間,默認表名的自動匹配規(guī)則是:取\Model\
后面部分的字符全部轉(zhuǎn)小寫,將用下劃線分割。例如:
<?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 版本相同的是,自動匹配的表名后面會自動加上表前綴。
當自動匹配的表名不能滿足實際開發(fā)需求時,1.x 和 2.x 版本均支持自定義表名。
在PhalApi 1.x 版本中,對外可訪問的入口主要有:
如何訪問在線接口文檔?
鑒于PhalApi 1.x版本中的訪問入口過于分散,且在線接口文檔鏈接過于冗長,在PhalApi 2.x 版本中,我們同時對此進行了優(yōu)化。即精簡為:
在PhalApi 1.x中,項目目錄結構為:
.
│
├── PhalApi //PhalApi框架,后期可以整包升級
├── Library //PhalApi擴展類庫,可根據(jù)需要自由添加擴展
├── SDK //PhalApi提供的SDK包,客戶可根據(jù)需要選用
│
│
├── Public //對外訪問目錄,建議隱藏PHP實現(xiàn)
│ └── demo //Demo服務訪問入口
│
│
├── Config //項目接口公共配置,主要有:app.php, sys.php, dbs.php
├── Data //項目接口公共數(shù)據(jù)
├── Language //項目接口公共翻譯
├── Runtime //項目接口運行文件目錄,用于存放日記,可軟鏈到別的區(qū)
│
│
└── Demo //應用接口服務,名稱自取,可多組
├── Api //接口響應層
├── Domain //接口領域?qū)? ├── Model //接口持久層
└── Tests //接口單元測試
在PhalApi 2.x中,項目目錄結構為:
.
│?
├── config // 項目接口公共配置
│?? ├── app.php // 項目配置
│?? ├── dbs.php // 數(shù)據(jù)庫配置
│?? ├── di.php // DI依賴注入配置
│?? └── sys.php // 系統(tǒng)環(huán)境配置
│?
├── public // 對外訪問目錄,推薦將web根路徑設定在此目錄
│?? ├── docs.php // 自動生成的在線接口文檔
│?? ├── examples // 示例
│?? ├── index.php // 接口服務統(tǒng)一訪問入口
│?? └── init.php // 統(tǒng)一初始化文件
├── runtime // 項目運行時產(chǎn)生的文件目錄
│?
├── src // 項目PHP源代碼
│?? └── app // 默認使用此App命名空間,可創(chuàng)建多上命名空間
│?? ├── Api // 接口響應控制層
│?? ├── Domain // 接口領域業(yè)務層
│?? ├── functions.php // 面向過程式的函數(shù)
│?? └── Model // 接口數(shù)據(jù)模型層
├── tests // 單元測試
│?
├── bin // 腳本命令
├── data // 用于存放SQL建表基本語句
├── language // 語言翻譯包
├── sdk // 客戶端SDK開發(fā)包,支持9+種語言
│?
├── composer.json // composer.json文件
└── vendor // 依賴安裝包
主要區(qū)別在于,對于不放置PHP源代碼的目錄,全部改用小寫。
以下是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規(guī)范,現(xiàn)需要調(diào)整遵循PSR-4規(guī)范。如:
原來的:PhalApi_Filter
調(diào)整后:\PhalApi\Filter
對于有繼承的情況,為了避免最后的關鍵字有沖突,統(tǒng)一在子類后面添加父類的名稱作為后續(xù)。如:
原來的:
PhalApi_COnfig_File
PhalApi_COnfig_Yaconf
調(diào)整后:
PhalApi\Config\FileConfig
PhalApi\Config\YaconfConfig
以下是PhalApi 2.x 與PhalApi 1.x 的函數(shù)對照關系。
PhalApi v2.x | PhalApi v1.x | 備注 |
---|---|---|
PhalApi\DI() | DI() | |
PhalApi\SL() | SL() | |
PhalApi\T() | T() |
函數(shù)名保持一致,但需要注意前面添加PhalApi命名空間前綴。
以下是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 | 創(chuàng)建項目代碼 |
暫未遷移 | ./PhalApi/phalapi-buildapp | 創(chuàng)建新項目,暫不需要遷移 |
以下是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參數(shù)區(qū)分 |
./public/docs/ | ./Public/demo/docs/ | 離線文檔生成目錄 |
更多建議: