4.2 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 中国全量镜像。
composer的使用方式
在1.x版本中，PhalApi更多是以自主研发的自动加载方式为主，这种方式原始、简单，并且粗糙。在2.x版本中，PhalApi使用的是composer管理方式，这要求对已有的代码仓库进行重新划分，并分为：项目、扩展类库和核心框架这三部分。
- 项目：可用于实际项目开发，提供给开发人员使用。
- 扩展类库：由广大开发人员共同维护、分享。
- 核心框架：由PhalApi团队核心人员长期维护，并接受贡献者的merge request。
如何创建新项目？
如果需要使用PhalApi 2.x 版本开发新项目，可以直接使用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更新：
$ 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
class Model_User extends PhalApi_Model_NotORM {
}类Model_User自动匹配的表名为user。
在2.x 版本中，规则类似，但由于多了命名空间，默认表名的自动匹配规则是：取\Model\后面部分的字符全部转小写，将用下划线分割。例如：
<?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中，项目目录结构为：
.
│
├── 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中，项目目录结构为：
.
│
├── 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/ | 离线文档生成目录 |