# EcmsAPI

**Repository Path**: twoir/ecmsapi

## Basic Information

- **Project Name**: EcmsAPI
- **Description**: 帝国7.5，8.0专用API接口。以对象开发，可定制入口，多个，自定义，自动加载特性(支持composer管理)，域名绑定，代码更简洁，方便更快捷，帝国（7.2和7.5）选择分支ecms75，帝国8.0选择分支master（php大于等于8.2)。
- **Primary Language**: PHP
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: http://coach.twoir.com/ecms/api/
- **GVP Project**: No

## Statistics

- **Stars**: 13
- **Forks**: 4
- **Created**: 2021-09-19
- **Last Updated**: 2026-01-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: CMS, API, 帝国CMSAPI, TWOIR

## README

# 🌟 帝国CMS EcmsAPI 接口系统（v1.8+）

> ✅ 高可用、面向对象、安全可控的独立 API 解决方案
> 🔧 支持 PHP 8.2+ | 帝国CMS 8.0 | Composer / 自动加载双模式
> 💬 QQ群：[206865209](https://jq.qq.com/?_wv=1027&k=KdZgBbYQ) | 教程地址：[http://coach.twoir.com/ecms/api/](http://coach.twoir.com/ecms/api/)

## 📚 接口概述

为解决传统帝国CMS前后端耦合严重、API开发效率低的问题，**EcmsAPI** 是一套基于现代 PHP 特性的轻量级 RESTful 接口框架。

它完全兼容帝国CMS数据库结构，并通过 **自动联表、异常处理、权限控制、字段维护、JWT鉴权等机制**，帮助开发者快速构建高性能、可维护的API服务。

## ✨ 核心特性

| 特性 | 说明 |
|------|------|
| **双加载模式** | 支持 `composer` 包管理 或 `autoload.php` 自动加载，灵活选择 |
| **OOP 设计** | 全部采用类封装，逻辑清晰，易于扩展和维护 |
| **统一入口 + 安全过滤** | 所有请求经 `/api/v1/` 入口进入，支持版本隔离（如 v2/v3）、防注入、反引号保护字段名 |
| **智能联表查询** | 自动识别主表、副表、模型表及审核/存档状态，无需手动拼接 SQL |
| **内置基础功能** | 注册 / 登录 / 登出 / 验证码 / OAuth（公众号、小程序）/ Sitemap（HTML/XML/TXT）/ JWT 认证（持续更新） |
| **后台权限管理** | 可视化配置 Controller 权限与 Model 字段访问策略，支持多端独立控制 |
| **字段显示控制** | 后台一键设置列表/详情页展示字段，无需修改代码 |
| **高安全性设计** | SQL 关键字自动加反引号 `` ` ``，防止保留字冲突；支持关闭敏感目录访问 |
| **未来版本畅想** | 不依赖前台模板系统，可作为纯 API 服务部署（推荐使用独立分支开发） |

## 🗂️ 目录结构

``` bash
upload/
└── api/
╌╌╌ └── v1/ (api入口)
└── e/
╌╌╌ └──	extend/	
╌╌╌	╌╌╌	└── twoir/
╌╌╌	╌╌╌	╌╌╌	├──	src/ (核心目录)
╌╌╌	╌╌╌	╌╌╌	╌╌╌ ├──ErrorHandler.php
╌╌╌	╌╌╌	╌╌╌	╌╌╌ └──helper.php
╌╌╌	╌╌╌	╌╌╌	└──	config/
╌╌╌	╌╌╌	╌╌╌ ╌╌╌ └──	...
╌╌╌	╌╌╌	╌╌╌ autoload.php (自动加载)
└── eadmin (后台目录)
```

> ✅ 新站安装建议直接覆盖根目录即可完成部署。

## 🛠️ 安装要求

| 项目 | 要求 |
|------|------|
| PHP 版本 | ≥ 8.2 （推荐使用 PHP 8.2+） |
| 帝国CMS 版本 | v8.0 及以上 |
| Web服务器 | Apache/Nginx |

## 🚀 快速安装（仅需4步）

### 第一步，复制文件到指定位置

将 `upload` 目录下的所有文件复制到网站根目录：

```bash
cp -r upload/* /www/wwwroot/your-site/
```

> 💡 若为新站，可直接覆盖。

### 第二步，安装自动加载功能

编辑文件：  `/e/class/connect.php` 在约第10行处插入以下代码

``` php
/**
 * 自动载功能
 * 
 * Author: cighsen02 365182575
 * Create at: 2021.09.01
 */
define('EXTEND_DIR', ECMS_PATH . 'e' . DIRECTORY_SEPARATOR . 'extend');
require_once EXTEND_DIR . DIRECTORY_SEPARATOR . 'twoir' . DIRECTORY_SEPARATOR . 'autoload.php';
```

> ⚠️ 注意路径分隔符兼容性（Windows/Linux），`DIRECTORY_SEPARATOR` 已做适配。

### 第三步，后台接口管理菜单

进入【后台管理系统】→【系统设置】→【扩展菜单】→【管理菜单】

#### 添加分类：
- **分类名称**：`API配置中心`
- **类型**：插件菜单
- **显示顺序**：0（默认）

#### 添加子菜单：
- **菜单名称**：`基础设置`
- **链接地址**：`extend/twoir/apiset.php`
- **打开方式**：金钢模式链接（推荐）
- **显示顺序**：0

> 保存后即可在左侧菜单看到新入口。

### 第四步，模型字段维护(手动)

1. 模型字段维护参考news模型操作 [News](docs/News.md)

## 🌐 接口集合

> 所有接口均以 `/api/v1/` 为前缀，例如：

| 功能 | 接口地址 | 方法 |
|------|----------|-------|
| 用户登录 | `/api/v1/?act=login` | POST |
| 验证码生成 | `/api/v1/?act=create_key&v=login` | GET |
| 获取文章列表 | `/api/v1/?classid={classid}` | GET |
| 获取文章详情 | `/api/v1/?classid={classid}&id={id}` | GET |
| 收藏功能（添加/取消） | `/api/v1/?act=set_fava` | POST |

📘 查看完整接口文档 → [👉 API 文档](docs/api.md)

## 🖼️ 演示站点（真实环境体验）

| 类型 | 地址 | 描述 |
|------|------|------|
| 🏙️ 城市分站 原版UI演示 | [http://v8.959602.com/](http://v8.959602.com/) | 原版风格 + 分站系统（AllCity） |
| 🌍 城市分站 Adcode版本 | [http://y.sj42.com/](http://y.sj42.com/) | 支持周边城市定位（AllCity） |
| 🔍 AllInfo 高级筛选系统 | [http://x.sj42.com/zuowen/c53/](http://x.sj42.com/zuowen/c53/) | 多条件组合查询演示 |

---

## 💬 技术交流 & 支持

- 📢 QQ交流群：**[206865209](https://jq.qq.com/?_wv=1027&k=KdZgBbYQ)**（欢迎开发者加入）
- 📘 学习资源：[http://coach.twoir.com/ecms/api/](http://coach.twoir.com/ecms/api/)
- 🐞 提交 Bug 或建议：[Gitee Issues](https://gitee.com/twoir/ecmsapi/issues)

---

## 🤝 如何参与贡献？

我们欢迎每一位 PHP 开发者共同打造更强大的帝国API生态！

### 贡献流程如下：

1. 🔢 **版本命名规范**
   - `v1.7.x` → 适用于 PHP 7.x
   - `v1.8.x` → 适用于 PHP 8.x（当前主线）

2. 🌿 **创建功能分支**
   ```bash
   git checkout -b feat-user-login-jwt
   ```

3. 💾 提交你的代码
   ```bash
   git add .
   git commit -m "feat: add JWT login for user"
   git push origin feat-user-login-jwt
   ```

4. 📤 创建 Pull Request
   - 在 GitHub 上发起 PR 至 `main` 分支
   - 描述清楚功能变更与影响范围

> ✅ 我们会及时审核并合并优质代码，你也将成为项目贡献者之一！

## 📎 相关链接

- 📂 源码仓库：`https://gitee.com/twoir/ecmsapi.git`（欢迎 Star ⭐）
- 📄 接口文档：[API Documentation](docs/api.md)
- 📘 字段配置：[Model Field Guide](docs/News.md)
- 📞 联系作者：cighsen02@qq.com / QQ: 365182575
  
### 参与贡献

## 🎯 展望未来（Roadmap）

| 版本目标 | 状态 |
|--------|------|
| ✅ 基础 CRUD + 用户体系 | 已完成 |
| ✅ 多模型智能联表 | 已完成 |
| ✅ 后台可视化配置 | 开发中 |
| 🔜 批量数据导入导出 | 开发中 |

> ❤️ 由社区驱动的开源项目，致力于让每个帝国CMS开发者都能轻松构建现代化 Web 应用！