# cgi-restful-api

**Repository Path**: chenic/cgi-restful-api

## Basic Information

- **Project Name**: cgi-restful-api
- **Description**: 适用于 php-fpm 运行环境 的快速 RESTful API 开发框架
- **Primary Language**: PHP
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-02-08
- **Last Updated**: 2025-02-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cgi-restful-api

适用于 php-fpm 运行环境 的快速 RESTful API 开发框架

## 特征

1. 超轻量级
2. 适用于 php-fpm 运行环境
3. 自动化的多级 RESTful API 路由
4. 使用 Medoo 作为数据库 ORM
5. 所有第三方库均包括在项目代码中，不依赖 composer
6. 全面静态化，数据库和缓存均为静态类调用，语法提示全面，IDE 友好

## 许可

MIT，可使用于商业项目

## 安装

本项目不依赖 composer ，直接将项目 clone 到 php-fpm 运行环境即可。

## 运行

### 配置

配置文件位于 `.env` ，可以修改其中的数据库连接信息，或是增加其他项目所需的配置参数。

> 请将 test.env 复制为 .env，并修改其中的配置参数

在程序中使用 php 原生的 getenv 函数来获取配置参数。

### 运行

项目入口文件位于 `public/index.php` 。

在本机调试时，可以使用 php 内置服务器来运行项目，命令如下：

```bash
cd public
php -S localhost:8000
```

在 vscode 中可以使用可以创建命令，命令的 tasks.json 如下：

```json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "run dev",
      "type": "shell",
      "command": "php -S 127.0.0.1:8080",
      "options": {
        "cwd": "public"
      },
      "problemMatcher": []
    }
  ]
}
```

在宝塔中，网站目录设置为项目目录，运行目录设置为 `/public`

## 演示

项目包括了一个简单的激活码管理业务应用，需要数据库支持，数据库表结构如下：

```sql
CREATE TABLE `code` (
	`code` VARCHAR(32) NOT NULL COLLATE 'utf8mb4_general_ci',
	`expire_time` DATETIME NULL DEFAULT NULL,
	`used_time` DATETIME NULL DEFAULT NULL,
	`create_time` DATETIME NULL DEFAULT CURRENT_TIMESTAMP,
	PRIMARY KEY (`code`) USING BTREE,
	INDEX `used_time` (`used_time`) USING BTREE
)
COMMENT='激活码'
COLLATE='utf8mb4_general_ci'
ENGINE=InnoDB
;
```

## 开发指南

### 1.路由

项目使用自动路由，在 app/controller 目录下创建控制器文件，文件名为控制器名，文件名小写。
控制器内的方法名以路由 + '\_' + 请求方法的方式命名，以 controller/user.php 为例：

```
function code_get() 方法对应 GET 请求 /user/code
function code_post() 方法对应 POST 请求 /user/code
function code_put() 方法对应 PUT 请求 /user/code
function code_delete() 方法对应 DELETE 请求 /user/code
```

项目支持多级路由，在 controller 目录中创建的多级子目录，目录将视为路由的一部分，以 controller/admin/merchant/goods.php 为例：

```
function goods_get() 方法对应 GET 请求 /admin/merchant/goods
function goods_post() 方法对应 POST 请求 /admin/merchant/goods
function goods_put() 方法对应 PUT 请求 /admin/merchant/goodse
function goods_delete() 方法对应 DELETE 请求 /admin/merchant/goods
```

### 2.数据库

项目使用 Medoo 作为数据库 ORM，在配置好数据库参数后，可以在代码中直接使用 Db 类进行数据库读写，请参阅 [Medoo 文档](https://medoo.lvtao.net/1.2/doc.php)。
支持以下方法：

#### Db::select($table, $columns, $where)

#### Db::select($table,$json, $columns, $where)

查询数据满足条件的所有记录，返回一个多维数组。

#### Db::get($table, $columns, $where)

#### Db::get($table, $json,$columns, $where)

查询一条记录，返回一个数组。

#### Db::rand($table, $column, $where)

#### Db::rand($table, $join, $column, $where)

随机返回满足条件的记录。

#### Db::insert($table, $data)

插入数据，返回插入的 id。

#### Db::update($table, $data, $where)

更新数据，返回更新的行数。

#### Db::delete($table, $where)

删除数据，返回删除的行数。

#### Db::has($table, $where)

确认满足 $where 条件的记录是否存在，返回一个 TRUE 或 FALSE。

#### Db::count($table, $where)

返回符合$where 条件的记录数。

#### Db::max($table,$column, $where)

返回符合$where 条件的记录中 $column 字符的最大值。

#### Db::min($table,$column, $where)

返回符合$where 条件的记录中 $column 字符的最小值。

#### Db::avg($table,$column, $where)

返回符合$where 条件的记录中 $column 字符的平均值。

#### Db::sum($table,$column, $where)

返回符合$where 条件的记录中 $column 字符的合计。

#### Db::id()

返回最后插入的行 id。

#### Db::action($callback)

启动一个事务。

#### Db::query($sql)

执行 $sql 语句，返回 PDOStatement 对象。

#### Db::quote($string)

对字符串进行安全转义。

#### Db::raw($query,$map)

使用原始表达式来进行复杂的或自定义的查询，尤其是在使用 SQL 内置函数的时候，对 $query 进行原生转换，以防止注入和优化语法。

#### Db::debug()

开启调试模式，输出 sql 语句（不需要使用 echo 或 print），不实际执行。

#### Db::error()

获得最后一个执行的错误

#### Db::last()

返回最后一条执行的 SQL 语句

#### Db::info()

返回数据库相关信息

#### Db::pdo()

返回数据库的 pdo 连接对象

> 本项目未实现所有 Medoo 类方法的封装，如有需要请自行在 framework/support/Db.php 看添加。

### 3.缓存

项目使用 Redis 作为缓存，在配置好 Redis 服务参数后，可以在代码中直接使用 Redis 类进行数据库读写,支持以下方法：

#### Redis::set($key, $value)

设置一个缓存值。

#### Redis::get($key)

获取一个缓存值。

#### Redis::del($key)

删除一个缓存值。

#### Redis::setEx($key, $expire, $value)

设置一个自动过期的缓存值。

> 项目未实现所有 Redis 类方法的封装，如有需要请自行在 framework/support/Redis.php 文件中添加。

### 4.请求类

在程序中使用 Request 类来获取请求参数，支持以下方法：

#### Request::get($key,[$default])

获取一个 GET 请求参数，未提交时返回 $default。

#### Request::post($key,[$default])

获取一个 POST 请求参数，未提交时返回 $default。

#### Request::header($key)

获取一个 header 参数。

### 5.响应类

在程序中使用 Response 类来响应请求，支持以下方法：

#### Response::Success($data)

返回一个 api 执行成功响应，json 格式，内容为 {code:0,msg:'success',data:$data}。

#### Response::Error($code,$msg='',$data=null)

返回一个 api 执行错误响应，json 格式，内容为 {code:$code,msg:$msg,data:$data}。

#### Response::Redirect($url)

返回一个页面跳转指令，跳转到 $url 指定的网址。

#### Response::Raw($code,$data)

返回一个原生响应，返回的 http 状态码为 $code，返回内容为 $data。

## 待续

1. 请求参数的传递需要进一步优化。
2. 依赖于第 1 条，中间件功能尚未开发完成。
3. 自动生成文档功能。

## 参与贡献

欢迎参与贡献！

我不太熟悉开源项目管理，如果你能提供一些指导，我将不胜感激，请加我微信。

<img src="codesi.jpg" alt="加我微信" width="300" height="400">