Download the PHP package liuxingwei/simple-api-framework without Composer

SAF 框架使用说明

零、概述

SAF（Simple Api Framework）是一个极简单的PHP API开发框架，适用于前后端分离架构的web项目，作为后端PHP API服务的框架。

说其极简，一方面是因为它只有很少的核心类和几个支持文件，另一方面是因为它只支持有限的场景，当然，也是说它非常易于使用。

SAF没有Beautiful URL路由，GET请求的参数是通过形如name=zhangsan&sex=male的QueryString参数传递的。

SAF遵循了惯例优于配置的理念，API必须放在指定的目录（项目目录的Application\Api）下，且GET请求对应的API类要放在Get子目录，而POST请求对应的API类要放在Post子目录，其他类型的HTTP请求对应的API，也放在与其HTTP METHOD相对应的子目录。

数据库方面，SAF有一个简单的DB类，它是以PDO为底层的，理论上它可以支持多种数据库服务，但是目前只在MySQL上做过测试。因此最适合的数据库搭配就是MySQL5.7+。

对于PHP，由于7.2.*和其前的版本，在trait特性支持上有缺陷（引用继承了同一trait的多个trait时，会导致重复定义方法的致命错误），因此建议PHP 7.3+。

一、环境要求

支持PHP 5.6，建议PHP 7.3+，MySQL 5.7+。

二、下载

1. composer

2. github

三、环境搭建

有如下几种方式，任选其一（前两种方式仅适用于开发、测试环境）：

1、PHP Built-in Server

使用PHP内建服务时，无需nginx、apache，只需PHP。

在命令行下，切换至public文件夹（safpath指SAF的路径），执行php -S localhost:xxxx index.php即可，其中xxxx为端口号。

示例：

浏览器打开localhost:xxxx，看到如下内容，服务启动成功：

2、借助 VSCode 中 PHP Server 插件

安装PHP Server插件，打开File > Preferences > Settings，找到Extensions > PHP Server Configuration，将Relative Path改为./public。

如果PHP可执行文件没加到系统路径中，可以将其填写在PHP Server插件的PHP Path配置项中。

打开public/index.php文件，在文件窗口右键，选PHP Server： Server Project。

浏览器打开localhost:xxxx，看到如下内容，服务启动成功：

PHP Server: Stop可以停止服务。

PHP Server: Reload Server可以重启服务。

3、使用 WAMP

启动WAMP，点进托盘区WAMP图标，选择Apache > httpd-vhosts.conf文件。

在打开的文件中，复制VirtualHost段，修改端口，并将路径修改为项目目录的public文件夹。

示例（safpath即指SAF的路径）：

要复制的段：

复制后修改IP和DocumentRoot、Directory路径：

修改后的完整文件：

重启Apache。

浏览器打开localhost:xxxx，看到如下内容，服务启动成功：

4. nginx

添加一个server配置：

重启nginx。

四、目录结构

初始的项目目录结构如下：

五、创建API

在application/Api/Get或application/Api/Post中根据业务需要创建一个子文件夹（也可以是多级文件夹），在其中创建一个API类。

该类实现Lib\Core\Interfaces\BaseApi接口，并实现run()方法，该方法签名为：run(array $param):mixed。

例如，在Get文件夹创建Example文件夹，并在其中创建Index.php，文件内容如下：

run()方法的参数即为HTTP请求的参数集合。

此时，向服务器的/example/index发出GET请求，即可收到值为

的json返回。

此时，向/example/index发出POST请求，收到的则是

要创建一个接受/example/index的POST请求的API，需要在application/Api/Post中创建Example文件夹，并在Example中创建Index.php文件：

命名空间与uri的关系

API类遵循psr4标准，其命名空间Application\Api映射于项目根目录中的application/Api目录。

API类名与API的uri之间的关系是，将类的命名空间中的Application\Api\xxx部分去除，并将\转换为/，就是该API的uri，而其中的xxx即对应了HTTP METHOD。

例如类Application\Api\Get\Example\Index对应的API的uri即为/example/index，相应的HTTP METHOD为GET。

而类Application\Api\Post\Example\Index对应的API的uri也为/example/index，但相应的HTTP METHOD为POST。

PUT、PATCH、DELETE等HTTP METHOD类推。

由于HTTP定义的url对于大小写不敏感，在转换为类名时，会自动将每部分的首字母转换为大写，并将短横线及其后的一个字母转换为大写字母，以对应命名空间中的大写字母。

run()方法的参数

run()方法的params参数接收了与HTTP METHOD相对应的request数据。

对于POST、PUT、PATCH，如果提交的HEADER中Content-Type为application/json的情况，接收了json解码后的Request Payload数据。

对于PUT、PATCH的application/x-www-form-urlencoded，接收了（解析后的）Form Data数据，类似于$_POST的值。

对于POST的form-data、multipart/form-data、application/x-www-form-urlencoded，则接收了（解析后的）Form Data数据。相当于$_POST的值。

对于GET和DELETE，则接收了解析后的Query String键值对。相当于$_GET的值。

其它情况，则直接在params的BODY元素中存储了提交的Request Payload的原始值。

ErrorCode类

可以将返回的基本结构放在配置文件中，通过ErrorCode类读取。

框架提供了一个ErrorCodeTrait，其中定义了实例变量errCode，实例化了ErrorCode类，可以直接在需要使用ErrorCode的类中使用（注意规避一下与errCode变量名的命名冲突）：

ErrorCode使用的配置文件有default.php和xx.php两个，后一个文件的xx指的是配置语言，默认为中文，即cn。配置文件默认放在项目根目录下的conf/err_define文件夹。

文件位置和语言均中在conf/config.php中配置：

配置方式参见conf/err_define/cn.php。

default.php中放置的是系统预定义的配置，不建议直接修改，可以在语言文件中定义同名元素覆盖默认配置。

配置中的元素的key，可以当作errCode的属性直接使用：

可以这样改写Example\Index：

消息定义可以使用占位符，占位符被包含在{{:和}}之间。可以使用数组指定要替换的与数组键匹配的值。

例如，定义如下消息：

然后在Api的run()方法中这样使用：

结束执行

框架最后调用API代码就是run()方法，因此该方法执行的最后一行代码就标志了API的执行结束。

下面的代码示例了在不同条件下的不同输出并结束API的执行：

默认的输出中，HTTP CODE均为200。

如果认为登录失败是一种错误，可以定义errorCode的属性：

如果定义的code和HTTP错误码相同，还可以使用SafException类的throw静态方法抛异常：

这两段代码的输出是一样的。

输出类型

默认的输出类型为application/json。无需主动对结果进行json_encode，只需run()方法返回要输出的数组即可。

也可以定义其它类型的输出，通过API类的$responseType属性指定。

可以使用的类型有：

html、json、xml、text、javascript、steam。

其中，json和xml类型，run()方法返回数组；html和text返回文本；javascript返回js文本。

stream用于输出文件，除了run()方法要返回待输出文件的内容外，还需要通过headers属性指定response头信息。

配置文件

通用的配置文件放置在conf目录中，文件名为config.php，框架提供了一个示例文件config.php.sample。

该文件内容示例如下：

其中的配置数组将被读入超全局变量$_ENV的config元素中。

上面示例中的变量可以这样读取：

为方便使用，该配置也被定义在CONFIG常量中，相同的配置还可以这样读取：

通常情况下，我们的生产环境和测试、开发环境在配置方面总会有些差别，因此SAF提供了可以覆写conf/config.php文件中的默认配置的方法：

即在conf/env.php文件中放置需要覆写的配置项，比如生产环境的数据库主机地址为10.0.0.1，密码为@77pai*654，则可以在生产服务器的conf/env.php文件作如下配置：

而与conf/config.php相同的配置，则无需在conf/env.php中重复配置。

不要将conf/config.php文件提交到版本库，可以将其放入版本库的忽略文件列表中，而额外提供一个conf/env.php.sample，作为配置的参考。

DB和Model

框架实现了一个基于PDO的DB类，具体使用请参考doc目录的DB-Class-Usage.md文件。

框架提供了一个BaseModel基类，可以以此为基础自定义Model类，继承BaseModel类。建议将Model类定义在Application\Model命名空间中。

上例中，是假定表名与类名相同，都是user（在MySQL中不区分大小写）。

如果实际的表名与类名不同，则需要使用$table属性自定义表名：

框架会将类名定义中的大写字母转换「下划线加小写」字母的形式。

注意不要在MySQL中用驼峰法命名表名，而要用下划线命名法。

上例也可以省略表名的显式定义：

如果使用依赖注入方式注入Model类，建议以多实例模式注入，以避免单例引起的问题。

可以在定义Model时即将其指定为多实例模式：

依赖注入支持

框架提供了对依赖注入的支持。使用了改造过的LIUXINGWEI/LXW-PHP-DI(fork 自PHP-DI/PHP-DI)。主要是增加了Scope注解和scope()方法，以支持非单例注入模式。

Scope注解用于自动装配类的定义，其参数可以是singleton或prototype，不写Scope注解，或者不写Scope的参数，均默认为singleton，即单例模式，prototype则为非单例模式。参见Application/Model/SafExample类的定义。

scope()方法用于依赖注入配置，在调用factory()方法之后，链式调用scope()方法，其参数为singleton或prototype，分别对应单例和非单例模式。参见conf/config.php.sample文件中的定义。

两种非单例注入模式的注入示例见Application/Api/Get/Example/Index。

默认的配置文件是conf/di_config.php，不过可以通过系统配置文件conf/config.php中的di_config项来修改。

该配置项可以是一个PHP-DI配置的路径，也可以是一个包含多个PHP-DI配置文件路径的数组。

框架在conf目录放置了一个依赖注入配置的示例文件conf/di_config.php.sample。

有关PHP-DI的详细使用请查阅PHP-DI 文档。

示例API中Get\Example\Index中有依赖注入示例。

虚拟子目录支持

如果需要将API部署在虚拟子目录中，需要将请求转发至public\index.php，由其负责路由。

同时，需要修改conf\config.php中的api_path设置，将虚拟目录放在该参数中，例如为所有API提供/Api路径前缀：

AJAX 跨域问题

如果将SAF用于AJAX调用的API服务，可能需要跨域。

跨域配置项如下：

enable配置项决定了是否启用跨域。系统默认是不启用。

domain的系统默认值为*。

methods的系统默认值为。

headers的系统默认值为。

由于系统需要使用header的默认值支持，因此此项配置不会覆盖系统默认值，而是会与系统默认值合并。其余三项，则会由用户配置覆盖系统默认值。

参数校验

框架提供了几个基本的校验类，用于对请求参数进行校验。

这些校验方法的使用依赖了annotation（注解）技术。仅需在run()方法上添加注解，即可实现对参数的校验。

每条注解需要声明要校验的参数名，有的还需要带有额外的参数。

已经实现的校验注解及其示例如下（所有注解的字符串类型必须使用双引号作为定界符，使用单引号会引发错误）：

1. Required

Required注解用于参数必须的情况。它只要求参数存在，对于参数值则没有要求。

如上代码要求$params参数数组中必须包含user_name和password两个元素。

2. NotEmpty

NotEmpty注解用于参数不得为空的情况。

如上代码校验参数$params中的user_name元素不得为空。

需要注意的是NotEmpty注解不对参数是否存在进行校验，它仅在要校验的参数存在的情况下才有效。

如果要求参数必须存在且不得为空，需要联合Required注解共同完成校验：

NotEmpty支持对要校验的参数去首尾空格：

不过，trim仅存在于校验过程中，对实际参数没有影响，因此在run()方法内部，仍需自己处理参数的首尾空格问题。

3. 长度校验

对长度的校验有两个注解，Length适用于字符串，Limit适用于数值。

Length注解有max和min两个可选参数，分别限制最大（含）和最小长度（含），为闭区间。

Limit注解也是max和min两个可选参数，闭区间。不过它支持浮点数。

4. 正则校验类

对于电话号码、IP地址、邮编、Email等进行合法性校验时，会使用到正则表达式。

Rule注解就用于这种场合。

与前面的校验类不同，正则校验类允许自定义校验失败时的消息，见上例中的error参数。

自定义校验类

可以自定义校验类，具体写法可以参照Lib\Validatetions中的预置校验类。

简单的说，校验类是依赖doctrine/annotations实现的。

首先，自定义校验类要继承Lib\Validations\AbstractValidation类，并在类前面添加@Annotation和@Target({”METHOD"})注解：

校验类须实现check()方法，其参数即为框架转换后的请求参数（也即run()方法接收到的参数，见前言run()方法的参数。

在校验通过时，check()方法返回true，失败时返回false。

并且在失败时，要设置err变量，其类型为数组，包括code和message两个元素，对应失败的编码和原因。

校验类的蕨类定义了一个变量value，它对应于校验注解的同名参数，如果该参数位于注解的第一位，可以不标名：

上面例子中的两种注解，其效果是一样的，在MyValidation类中的value获取的值均为username。

校验类的其它公有变量，对应于注解中的同名参数。

书写注解时，要注意，如果参数类型为string，则对应的参数值要使用双引号，而不能用单引号。如果参数类型是array，要放在一对花括号中，其格式与标准json基本一致。

以下是一个比较完整的示例：

不建议将自定义校验类放在Lib\Validations命名空间，在升级框架时可能会受影响。

可以将自定义校验类放在框架可识别的任意命名空间中，并在配置文件中使用validation_namespaces对其进行标识。上面的示例就是将校验类放在Application\Validations命名空间中，其在配置文件中的定义如下：