5.2 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版本的一些示例：

Model层自动匹配的表名差异

在1.x 版本中，默认表名的自动匹配规则是：取Model_后面部分的字符全部转小写。例如：

<?php
class Model_User extends PhalApi_Model_NotORM {
}

类Model_User自动匹配的表名为user。

在2.x 版本中，规则类似，但由于多了命名空间，默认表名的自动匹配规则是：取Model后面部分的字符全部转小写，将用下划线分割。例如：

<?php
namespace AppModelUser;
use PhalApiModelNotORMModel as Model;

class Friends extends Model {
}

则类AppModelUserFriends自动匹配的表名为user_friends。以下是2.x版本的一些示例：

和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 的类对照关系。

类名重命名规则

原来的类名遵循PEAR规范，现需要调整遵循PSR-4规范。如：

原来的：PhalApi_Filter

调整后：PhalApiFilter  

对于有继承的情况，为了避免最后的关键字有冲突，统一在子类后面添加父类的名称作为后续。如：

原来的：
PhalApi_COnfig_File
PhalApi_COnfig_Yaconf

调整后：
PhalApiConfigFileConfig
PhalApiConfigYaconfConfig

附录2：函数对照表

以下是PhalApi 2.x 与PhalApi 1.x 的函数对照关系。

函数名保持一致，但需要注意前面添加PhalApi命名空间前缀。

附录3：脚本命令对照表

以下是PhalApi 2.x 与PhalApi 1.x 的脚本命令对照关系。

附录4：可访问入口对照表

以下是PhalApi 2.x 与PhalApi 1.x 的可访问入口对照关系。

关注微信下载离线手册