---
url: https://docs.zblogcn.com/php/api-mods.md
description: Z-BlogPHP API 接口文档，说明 api.php 的请求地址模式、参数字段约定、鉴权要求及各功能模块的行为。
---

# 接口文档

本篇为 Z-BlogPHP API 各模块的接口文档，说明请求地址模式、参数字段约定、鉴权要求及各功能模块的行为。

API 地址模式：`https://example.com/zb_system/api.php?mod=<模块名>[&act=<行为名>][&其他...]`

* 对于各「API 模块」的`act=post`请求，其请求参数为`$GLOBALS['datainfo']`中与该模块对应的数据字段定义；
  * 参数字段名区分大小写；
  * 不需要提供全部字段值，比如「发布状态」「类型（文章/页面）」「置顶」等项目可以使用默认，而时间相关的字段则会初始为当前时间；
  * 除`Comment`和`Upload`外，`act=post`请求时`ID` 字段为必须指定，为 0 时新建，不为 0 且项目存在时则修改；
  * **注：可在「[zb_system/defend/datainfo.php](https://github1s.com/zblogcn/zblogphp/blob/HEAD/zb_system/defend/datainfo.php "datainfo.php")」文件中搜索查看`$GLOBALS['datainfo']`;**
* 各接口返回信息以实际为准，可参考「[通用返回格式](/php/api-design#通用返回格式 "通用返回格式")」。
* **对于「登录」操作以外的`POST`请求，一律需要设置鉴权；「[登录和鉴权](/php/api-design#权限认证 "登录和鉴权")」**
  * `GET`请求时仅在部分「功能模块」中的部分「只读操作」可以不设置鉴权，此外未鉴权请求频率或查询数量可能受限制；

以下将按「功能模块」进行详细说明。

## member 会员登录及管理 API

| act 方法 | 请求方式   | 参数                                                | 鉴权 |
| -------- | ---------- | --------------------------------------------------- | ---- |
| `login`  | POST       |`用户登录并返回 token`                                 |      |
|          |            |$\_POST\['username'] 用户名称(非别名)
|          |            |$\_POST\['password']`password`建议使用 MD5(明文密码) 值
|          |            |$\_POST\['savedate'] `token`过期时间，最长 365 天
|          |            |返回值：附：**「示例 1」**
|
| `post`   | POST       | `编辑用户或新建用户`                                    | 必须 |
|          |            | `Member`定义字段；附：**「示例 2」**
|
| `get`    | GET / POST | `获取一个用户信息`                                         | 必须 |
|          |            | $\_REQUEST\['id'] 用户 `id`
|
| `delete` | GET / POST | `删除一个用户`                                           | 必须 |
|          |            | $\_REQUEST\['id'] 用户 `id`
|
| `list`   | GET / POST | `获取用户管理列表`                                       | 必须 |
|          |            | `act=list`方法共通参数见：[约束与过滤](/php/api-design#约束与过滤 "约束与过滤")
|          |            | $\_REQUEST\['status'] 指定状态`status`
|          |            | $\_REQUEST\['level'] 指定用户`level`
|          |            | $\_REQUEST\['page'] 第几页'page'
|
|`get_auth`| GET / POST | `查看当前用户权限列表`                                  | 必须 |
|
|`logout`| GET / POST | `退出登录`                                                | 必须 |
|          |            | PS:然后客户端自行删除 token 即可
|

**示例 1**：

```php
//发送的POST字段如下
username = '用户名'
password = md5('密码明文')
savedate = '保存天数'
```

```json
{
    "code": 200,
    "message": "操作成功",
    "data": {
        "user": {
            "ID": "1",
            "Level": "1",
            "Status": "0",
            "Name": "admin",
            "StaticName": "admin" // 等等 members 相关信息
        },
        "token": "Token 信息",
        "expire_time": 1672560322 // 过期时间
    },
    "error": null,
    "runtime": {
    }
}
```

此处`login`操作返回的「鉴权 Token」将用于后续需要「鉴权」的请求，见「[权限认证](/php/api-design#权限认证 "权限认证")」；

**示例 2**：

```json
{
  "ID": "0",
  "Level": "4",
  "Name": "用户名",
  "Password": "zblog_pwdd",
  "PasswordRe": "zblog_pwdd"
}
```

`"ID": "0",` 必须显示设置；

`"Level": "4",` 为用户等级；参考「[用户等级划定](/php/start-faq#用户等级划定 "用户等级划定")」

## post 文章管理 API

| act 方法 | 请求方式   | 参数                                                     | 鉴权               |
| -------- | ---------- | ------------------------------------------------------- | ----------------- |
| `get`    | GET / POST | `获取文章`                                                | 非公开文章需鉴权   |
|          |            |参数 id:文章 ID
|          |            |参数 with_relations:追加的关联对象  | 例：mod=post\&act=get\&id=2\&with_relations=Author 同时输出 Author 对象
|          |            |1.7.2 新增参数 viewnums:同时刷新浏览计数 | 例：mod=post\&act=get\&id=2\&viewnums=1
|
| `post`   | POST       | `新建或编辑文章`                                            |必须               |
|          |            |`Post`表单字段定义 附：**「示例 1」**
|
| `delete` | GET / POST | `删除文章`                                                  | 必须               |
|          |            |$\_REQUEST\['id'] 文章 `id`
|
| `list`   | GET / POST | `获取文章列表` | 未鉴权请求数量受限为每页面展示数量 |
|          |            |$\_REQUEST 参数定义如下
|          |            | `cate_id`, `tag_id`, `auth_id`, `type`, `date`, `manage`, `search` |已鉴权有后台管理权限为后台每页面展示数量 |
|          |            |\
|          |            |`act=list`方法共通参数见：[约束与过滤](/php/api-design#约束与过滤 "约束与过滤")
|          |            |参数 with_relations:追加的关联对象  | 例：mod=post\&act=get\&id=2\&with_relations=Author 同时输出 Author 对象
|          |            |1.7.2.3045 增加 参数 with_subcate:可以在分类列表输出子分类的文章 | 例：mod=post\&act=list\&cate_id=2\&with_subcate=1
|

**示例 1**：

```php
$_POST['ID'] 为 0 是新建
$_POST['Title']
$_POST['Alias']
$_POST['Type'] 为 0 是文章，1 是 page 页面
$_POST['AuthorID']
$_POST['CateID'] 如果没有提供 CateID,可提供 CateName
$_POST['Intro']
$_POST['Content'] 
$_POST['Tag']
$_POST['PostTime']
$_POST['Status'] 状态
```

注：对于发布文章，额外提供一个`CateName`字段可用来代替`CateID`指定分类，前提是存在以该字段值命名的分类；也可以使用`category`模块内的接口实现自动创建分类等操作；

## app 应用管理 API

| act 方法  | 请求方式    | 参数                                                    | 鉴权               |
| --------- | ---------- | ------------------------------------------------------- | ----------------- |
| `get`     | GET / POST | `获取指定 type 和 id 的应用`                             | 需鉴权   |
|           |            | `type` 为 theme 或 plugin
|           |            | `id` 为应用的 id 值
|
| `get_apps`| GET / POST | `获取所有的应用列表(含未激活的)`                               | 需鉴权   |
|
| `get_themes`| GET / POST | `获取所有的主题列表(含未激活的)`                               | 需鉴权   |
|
| `get_plugins`| GET / POST | `获取所有的插件列表(含未激活的)`                               | 需鉴权   |
|
| `set_theme`| POST      | `激活指定主题`                               | 需鉴权   |
|           |            |$\_POST\['id] `id` 为主题的 id 值
|           |            |$\_POST\['style] `style` 为主题的 style 名
|
| `enable_plugin`| POST      | `启用指定插件`                               | 需鉴权   |
|           |            |$\_POST\['id] `id` 为插件的 id 值
|
| `disable_plugin`| POST      | `禁用指定插件`                               | 需鉴权   |
|           |            |$\_POST\['id] `id` 为插件的 id 值
|

## category 分类管理 API

| act 方法  | 请求方式    | 参数                                                    | 鉴权               |
| --------- | ---------- | ------------------------------------------------------- | ----------------- |
| `get`     | GET / POST | `获取指定 id 的分类`                             | 无需鉴权   |
|           |            | `id` 为分类的 id 值
| `post`    | POST       | `编辑或发布分类`                                 | 需鉴权   |
| `delete`  | GET / POST | `删除分类`                                      | 需鉴权   |
| `list`    | GET / POST | `列出分类`                                      | \&manage=1(管理模式)需鉴权   |
|

## comment 评论管理 API

### 接口一览

| act | 请求方式 | 说明 | 鉴权 |
| --- | --- | --- | --- |
| `get` | GET / POST | 获取指定 `id` 的评论 | 无需鉴权 |
| `post` | POST | 发布评论 | 需鉴权 |
| `delete` | GET / POST | 删除指定 `id` 的评论 | 需鉴权 |
| `list` | GET / POST | 获取评论列表 | 管理模式需鉴权 |
| `check` | GET / POST | 审核评论 | 需鉴权 |
| `batch` | POST | 批量处理评论 | 需鉴权 |

### 接口说明

#### `get`：获取评论

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `id` | int | 评论 ID |

请求示例：

```
mod=comment&act=get&id=1
```

#### `post`：发布评论

请求参数为 `$GLOBALS['datainfo']['Comment']` 中的数据字段，只需提交需要赋值的字段，字段名区分大小写。

> 与其它模块不同，`comment` 的 `post` 只能新增评论，**不能**通过指定 `ID` 修改已有评论；`AuthorID`、`IP`、`Agent`、`PostTime` 等字段由服务端根据当前登录用户自动填充。发布前需先登录，见「[登录和鉴权](/php/api-design#权限认证 "登录和鉴权")」。

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `LogID` | int | 评论所属文章 ID，必填（也可用 `postid`） |
| `Name` | string | 评论者昵称；已登录用户会被其登录用户名覆盖 |
| `Email` | string | 评论者邮箱 |
| `HomePage` | string | 评论者网站 |
| `ReplyID` | int | 所回复评论的 ID，为 0 或不填则为顶层评论 |
| `Content` | string | 评论正文 |

请求示例：

```json
{
  "LogID": 1,
  "Name": "访客",
  "Email": "mail@example.com",
  "HomePage": "https://example.com",
  "ReplyID": 0,
  "Content": "写得很详细，收藏了。"
}
```

#### `delete`：删除评论

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `id` | int | 要删除的评论 ID |

#### `list`：获取评论列表

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `manage` | int | 进入管理模式，例：`&manage=1` |
| `post_id` | int | 按文章 ID 过滤 |
| `auth_id` | int | 按评论作者 ID 过滤 |
| `ischecking` | int | 按审核状态过滤 |
| `root_id` | int | 按楼层（根评论）ID 过滤 |
| `parent_id` | int | 按父评论 ID 过滤 |

* 非管理模式（不传 `manage`）：仅需提供 `post_id` 返回指定文章已审核的公开评论，无需鉴权；
* 管理模式（`manage=1`）：需鉴权，不传 `post_id` 时返回全部评论，可配合 `auth_id`、`ischecking`、`root_id`、`parent_id` 等条件过滤。

分页、排序等共通参数见：「[约束与过滤](/php/api-design#约束与过滤 "约束与过滤")」。

请求示例：

```
mod=comment&act=list&post_id=1&page=1&perpage=20
mod=comment&act=list&manage=1&ischecking=1&sortby=PostTime&order=desc
```

#### `check`：审核评论

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `id` | int | 要审核的评论 ID |
| `ischecking` | int | 目标审核状态：`1` 设为审核中（待审），`0` 通过审核，例：`&ischecking=1` |

#### `batch`：批量处理评论

以下三个操作参数任选其一，配合待处理评论的 ID 数组（`id`）使用：

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `all_del` | int | 删除所选评论 |
| `all_pass` | int | 通过所选评论的审核，例：`&all_pass=1` |
| `all_audit` | int | 将所选评论设为审核中 |
| `id` | array | 待处理评论的 ID，以表单数组形式提交（即 `$_POST['id']`，例如表单字段 `id[]`） |

请求示例：

```http
POST /zb_system/api.php?mod=comment&act=batch&all_pass=1
Content-Type: application/x-www-form-urlencoded

id[]=1&id[]=2&id[]=3
```

## module 模块与侧栏管理 API

| act 方法        | 请求方式    | 参数                                            | 鉴权               |
| --------------- | ---------- | ---------------------------------------------- | ----------------- |
| `get`           | GET / POST | `获取指定 id 的模块`                             | 无需鉴权   |
|                 |            | `id` 为模块的 id 值
| `post`          | POST       | `编辑或新建模块`                                 | 需鉴权   |
|                 |            |POST 参数：附：**「示例 1」**
| `delete`        | GET / POST | `删除模块`                                      | 需鉴权   |
|                 |            | `id` 为模块的 id 值
| `list`          | GET / POST | `列出模块`                                      | 无需鉴权   |
| `set_sidebar`   | POST       | `设置侧栏`                                      | 需鉴权   |
| `list_sidebar`  | GET / POST | `列出指定的侧栏`                                 | 需鉴权   |
|                 |            | `id` 为侧栏的 id 值(1-9)
|

**示例 1**：

```php
$_POST['ID'] 为 0 是新建
$_POST['FileName'] 模块的唯一标识符，起名需符合文件名规则
$_POST['HtmlID'] 模块的HTML的id
$_POST['MaxLi'] 模块内li标签最大数量
$_POST['IsHideTitle'] 是否隐藏模块的标题
$_POST['Type'] 模块的类别，为div或ul
$_POST['Content'] 模块的内容
$_POST['NoRefresh'] 锁定模块的内容不让程序更改
```

## system 系统设置与管理 API

| act 方法  | 请求方式    | 参数                                                    | 鉴权               |
| --------- | ---------- | ------------------------------------------------------- | ----------------- |
| `basic_info`| GET / POST | `获取网站基本信息`                                 | 不需要   |
|           |            | PS：如果发送鉴权则会多返回系统语言包数组
|
| `get_info`| GET / POST | `获取网站高级信息`                                     | 需鉴权   |
|
| `misc_statistic`| GET / POST | `清空缓存并重新编译模板`                                     | 需鉴权   |
|           |            | PS：即后台的刷新缓存操作
|
| `misc_showtags`| GET / POST | `Misc获取常用tags`                                     | 需鉴权   |
|           |            |参数`type` = 0，即获取文章的常用 tags
|
| `get_setting`| GET / POST | `获取常用设置数组`                                     | 需鉴权   |
|           |            | 返回值：返回常用的 option 数组
|
| `save_setting`|  POST | `保存系统常用设置`                                     | 需鉴权   |
|           |            | 附：**「示例 1」**
|

**示例 1**：

```php
$GLOBALS['setting_keys'] = array(
    'ZC_BLOG_NAME',
    'ZC_BLOG_SUBNAME',
    'ZC_BLOG_COPYRIGHT',
    'ZC_TIME_ZONE_NAME',
    'ZC_BLOG_LANGUAGEPACK',
    'ZC_API_ENABLE',
    'ZC_XMLRPC_ENABLE',
    'ZC_DEBUG_MODE',
    'ZC_DEBUG_MODE_WARNING',
    'ZC_ADDITIONAL_SECURITY',
    'ZC_USING_CDN_GUESTIP_TYPE',
    'ZC_CLOSE_SITE',
    'ZC_DISPLAY_COUNT',
    'ZC_DISPLAY_SUBCATEGORYS',
    'ZC_PAGEBAR_COUNT',
    'ZC_SEARCH_COUNT',
    'ZC_SYNTAXHIGHLIGHTER_ENABLE',
    'ZC_COMMENT_TURNOFF',
    'ZC_COMMENT_AUDIT',
    'ZC_COMMENT_REVERSE_ORDER',
    'ZC_COMMENTS_DISPLAY_COUNT',
    'ZC_COMMENT_VERIFY_ENABLE',
    'ZC_UPLOAD_FILETYPE',
    'ZC_UPLOAD_FILESIZE',
    'ZC_ARTICLE_INTRO_WITH_TEXT',
    'ZC_ARTICLE_THUMB_SWITCH',
    'ZC_ARTICLE_THUMB_TYPE',
    'ZC_ARTICLE_THUMB_WIDTH',
    'ZC_ARTICLE_THUMB_HEIGHT',
    'ZC_MANAGE_COUNT',
    'ZC_POST_BATCH_DELETE',
    'ZC_DELMEMBER_WITH_ALLDATA',
    'ZC_CATEGORY_MANAGE_LEGACY_DISPLAY',
);
```

## tag 标签管理 API

| act 方法  | 请求方式    | 参数                                                    | 鉴权               |
| --------- | ---------- | ------------------------------------------------------- | ----------------- |
| `get`     | GET / POST | `获取指定 id 的标签`                             | 无需鉴权   |
|           |            |参数 `id`: 为附件的 id 值
| `post`    | POST       | `编辑或发布标签`                                 | 需鉴权   |
|           |            |POST 参数：附：**「示例 1」**
| `delete`  | GET / POST | `删除标签`                                      | 需鉴权   |
|           |            |参数 `id`: 为附件的 id 值
| `list`    | GET / POST | `列出标签`                                      | 管理模式需鉴权   |
|           |            |参数 manage:进入管理模式                          |例：\&manage=1
|

**示例 1**：

```php
$_POST['ID'] 为 0 是新建
$_POST['Alias'] 标签的别名 
$_POST['Intro'] 标签的简介
$_POST['Template'] 标签的模板,默认为空
```

## upload 附件管理 API

| act 方法  | 请求方式    | 参数                                                    | 鉴权               |
| --------- | ---------- | ------------------------------------------------------- | ----------------- |
| `get`     | GET / POST | `获取指定 id 的附件`                             | 需鉴权   |
|           |            |参数 `id`: 为附件的 id 值
| `post`    | POST       | `编辑或发布附件`                                 | 需鉴权   |
|           |            |附：**「示例 1」**
| `delete`  | GET / POST | `删除附件`                                      | 需鉴权   |
|           |            |参数 `id`: 为附件的 id 值
| `list`    | GET / POST | `列出附件`                                      | 需鉴权   |
|           |            |参数 manage:进入管理模式                          |例：\&manage=1
|           |            |参数 author_id:列出用户 ID 为 author_id 下的附件
|           |            |参数 post_id:列出 post_id 文章下的附件

**示例 1**：

客户端或小程序 POST 提交上传文件到 mod=upload\&act=post

提交成功后 json($upload) 对象
例如：

```json
{"code":200,"message":"操作成功","data":
{"upload":{"ID":118,"AuthorID":"1","Size":100676,
"Name":"tmp_14af3ac3791ceeb34e0755ccc3586ce2.jpg",
"SourceName":"tmp_14af3ac3791ceeb34e0755ccc3586ce2.jpg",
"MimeType":"image/jpeg","PostTime":1648973749,
"DownNums":0,"LogID":0,"Intro":"","Url":"xxxxxxxxxxxxxxx"}
},"error":null,
"runtime":{"time":"54.25","query":14,"memory":4035,"debug":0,"loggedin":1,"error":0}
}
```

提交失败后返回 false