安装指南

从拿到安装包到站点可访问，通常只需：上传 → 运行向导 → 加固安全。

环境要求

目录需可写：content/upload/、content/cache/（Linux 常见 755/775，属主为 Web 用户）。

三步安装

第一步：上传程序

1. 从 官方下载页 获取最新安装包并解压
2. 将全部文件上传到网站根目录（虚拟主机常见 public_html / wwwroot），或子目录
3. 确认 content/cache/、content/upload/ 可写

第二步：运行安装向导

浏览器访问：

http://你的域名/install.php

按向导填写：

完成后会写入 content/cache/install.lock，并尽量将 install.php 重命名为 install.php.disabled。

第三步：删除安装入口并登录

1. 立即删除或重命名 install.php（若仍存在）
2. 访问前台域名确认主题正常
3. 后台默认入口：admin.php（见下文安全加固）

安装后必做

1. 登录后台
2. 重命名后台入口：将根目录 admin.php 改为不易猜测的文件名（如 manage_x8k2.php），并更新书签
   仍使用 admin.php 时，示例插件「小贴士」会在后台首页提示安全风险
3. 外观 → 主题：启用所需主题；有 settings.php 时可配置外观
4. 设置 → 站点信息 / SEO：站点标题、副标题、描述、版权（主题通过系统配置读取）
5. 设置 → 链接：选择动态 / 伪静态；伪静态需配置服务器，见 伪静态与路由
6. 插件 → 插件管理：按需启用（支付、OAuth 等）
7. 按需配置 SMTP、支付网关
8. 执行一次 设置 → 更新缓存

重装

1. 备份数据库与 content/upload/
2. 删除 content/cache/install.lock
3. 如程序要求，设置环境变量 HOPE_ALLOW_REINSTALL=1
4. 必要时从 install.php.bak 恢复 install.php
5. 重新访问安装向导

常见问题

打开 install.php 空白 / 报错

• 检查 PHP 版本与必装扩展
• 查看 content/cache/error.log 或 Web 服务器错误日志
• 确认未误删 system/ 或 content/ 关键文件

提示目录不可写

• 调整 content/cache、content/upload 权限与属主
• 部分主机禁止 777，优先用属主可写的 755/775

安装完成仍可访问 install.php

• 手动删除或重命名 install.php
• 确认存在 content/cache/install.lock

子目录安装后样式 / 链接错乱

• 后台核对站点 URL（含路径与尾斜杠）
• 伪静态时修正 RewriteBase 或 Nginx location 前缀
• 更新缓存后再测

后台无法登录

• 确认使用的是重命名后的入口文件
• 清除浏览器 Cookie 后重试
• 检查数据库用户表管理员是否安装成功

前台 500 / 白屏

• 开启开发者模式排查（见 开发准备工作）
• 确认 system/config.php 数据库信息正确
• PHP 版本过低或缺少扩展时，安装后也可能在个别页面报错

从旧版本升级

已有站点不要再跑安装向导。覆盖文件、插件字段迁移与缓存刷新见 升级与更新。

开发环境与目录约定见 开发准备工作。

升级与更新

本文说明 Hope CMS 程序覆盖升级、插件/主题升级、数据库字段迁移与站点缓存刷新。

适用场景速查

升级前建议：备份数据库 + 备份 content/upload/ +（可选）整站文件快照。

程序升级

1. 后台导出或 mysqldump 备份数据库
2. 备份整站（至少 system/、content/、入口 PHP）
3. 用新版覆盖文件；保留 system/config.php 与本地已改配置
4. 保留 content/upload/、content/cache/install.lock、自定义主题/插件
5. 登录后台执行 更新缓存；若从 1.0.4 等旧版覆盖升级，可再点 清理旧版残余（或依赖在线升级自动清理）
6. 抽查：首页、文章、登录、后台写文章、已启用插件

若发行说明要求执行 SQL 或一次性脚本，按说明操作；不要重复跑 install.php。

升级后若旧结构主题异常，见 常见问题 · 旧版兼容。

清理旧版残余文件

从 HopeCMS 1.0.4 覆盖升级后，旧的 controller / model、base.php、旧类名 lib 等文件可能仍留在 system/。
逻辑见 system/lib/legacy_cleanup.php：

• 在线升级成功后自动执行
• 也可在后台 设置 → 更新缓存 旁手动「清理旧版残余」

仅删除白名单路径，不会动 config.php、主题、插件、上传目录。

插件更新

插件目录：content/plugin/{插件名}/。

生命周期

启用顺序：加载 {插件}_callback.php → callback_init()（不会自动执行 install.sql）。

推荐写法

// tips_callback.php
function callback_up() {
    callback_init();
}
function callback_init() {
    // 有表时：myplugin_upgrade_schema();
}
function callback_rm() {
    MetaStorage::getInstance('tips')->deleteAllName('YES');
}

有表插件将 CREATE + ALTER 放在同一升级函数。完整示例见 数据库与 SQL。

字段升级原则

1. 建表用 CREATE TABLE IF NOT EXISTS
2. 新字段先 SHOW COLUMNS 再 ALTER（可重复执行）
3. callback_init 与 callback_up 调用同一函数
4. 禁止改核心表结构（article、user、option 等）

主题更新

• 建表 / 初始化：主题根目录 callback.php 的 callback_init()（删除时 callback_rm()）
• CSF settings.php 增删字段后，读取必须带默认值：hope_option('key', 'default') / _hope()
• 新增 pages/*.php 页面模板后：后台新建页面并选择该模板
• $prefix（如 default_options）不要随意改名，否则已保存配置失效

主题结构见 主题开发指南。

更新缓存

后台：设置 → 数据 → 更新缓存（或系统设置中的「更新缓存」入口）。

会做什么

全量 SnapshotBank::refresh()（全局实例常为 $SNAP），重建包括但不限于：

options、user、sta、comment、tags、category、link、menu、newlog、record、logalias、logcategory、logtags

并调用 Settings::resetRoutingTableCache() 清空伪静态路由表内存缓存（保存「设置 → 链接」时也会重置）。

菜单标题同步

刷新 menu 时会同步文章 / 页面 / 分类 / 标签类型菜单项标题为来源最新名称；自定义链接名不受影响。

改了标签名、分类名或文章标题后，点一次「更新缓存」即可让导航跟上。

代码中局部刷新

global $SNAP;
$SNAP = SnapshotBank::getInstance();

$SNAP->refresh();                                // 全量
$SNAP->refresh(['tags', 'menu', 'category']);    // 指定
$SNAP->refreshPosts();                           // 文章相关常用组合

缓存文件在 content/cache/*.php；请确保目录可写。

开发自检清单

• [ ] 插件 / 主题 Version 头信息已递增
• [ ] 新表与新字段在幂等升级函数中（callback_init / callback_up）
• [ ] callback_rm 已清理 MetaStorage；有表则明确是否 DROP
• [ ] 未改核心表结构与 system/ 业务文件
• [ ] 主题新配置均有默认值；$prefix 未误改
• [ ] 升级前已备份；升级后已「更新缓存」并抽查前台

相关文档

• 安装指南
• 插件开发指南
• 数据库与 SQL
• 主题开发指南
• 开发准备工作

常见问题

集中说明安装、升级与二次开发中的常见疑惑。旧主题 / 旧插件兼容说明只在本文维护，其它章节不再重复。

相关：安装指南 · 升级与更新 · 主题开发指南 · 插件开发指南

安装与后台

打开 install.php 空白 / 报错

• 检查 PHP 版本与必装扩展（见 安装指南）
• 查看 content/cache/error.log 或 Web 服务器错误日志
• 确认未误删 system/ 或 content/ 关键文件

安装后无法进后台

• 确认已删除或重命名根目录 install.php
• 入口默认为 admin.php；若已改名，请使用新文件名
• 清除浏览器缓存后重试

前台样式丢失 / 链接异常

• 后台 设置 → 更新缓存
• 检查「设置 → 链接」模式是否与服务器伪静态配置一致（见 伪静态与路由）

升级后仍看到旧报错 / 旧类文件

从 1.0.4 覆盖升级后，可用后台 设置 → 清理旧版残余（system/lib/legacy_cleanup.php）删除废弃的 controller/model 等文件；在线升级成功时也会自动清理。

旧版兼容（legacy_compat）

内核只认主题与 API 的新规范。需要继续跑旧结构主题，或仍使用旧函数/类名的第三方插件时，启用插件 「旧版兼容」（content/plugin/legacy_compat/）。

default、hopecms 等已迁移主题，以及已改用现行 API 的插件，不必启用。

何时启用

怎么启用

1. 后台 插件 → 插件管理 启用「旧版兼容」
2. 启用时会自动排到 active_plugins 最前，保证其它旧插件加载前垫片已就绪
3. 再启用或切换旧结构主题；执行一次 更新缓存

升级程序后若旧主题突然空白或找不到模板：优先检查本插件是否仍启用。

旧主题路径对照

Handler 仍可使用逻辑名 header、log_list、echo_log 等，内核映射到新文件；旧物理文件由本插件注入候选路径。

旧插件 API 对照（节选）

完整对照表：content/plugin/legacy_compat/naming_map.php。插件说明：content/plugin/legacy_compat/README.md。

新项目要不要写旧名？

不要。新主题按 head.php / archive.php / pages/ / account/ / widgets/ 规范编写；新插件直接使用 hope_listen、Settings、HopeDb 等现行 API。

主题与插件开发

主题设置页不出现

主题根目录需有 settings.php（CSF）。确认当前主题已启用，并刷新后台菜单。

侧边栏组件不显示

• 确认 widgets/config.php 已注册对应 side_* key
• 确认存在 widgets/widget-{name}.php
• 换主题后到 外观 → 侧边栏 重新勾选组件

插件启用后无效果

• 确认入口文件头信息与目录名一致
• 钩子是否写在入口或 *_lib.php 且已被 require
• 查看是否与其它插件互斥；需要时检查 content/cache/error.log

更多

目录总览见 目录说明。反馈渠道见 联系我们。

目录说明

Hope CMS 根目录只保留两个文件夹：content/（内容区）与 system/（程序区），外加少量入口文件。

相关：开发准备工作 · 常见问题

根目录

hope/
├── index.php      # 前台入口 → system/bootstrap.php
├── admin.php      # 后台入口 → system/bootstrap.php
├── install.php    # 安装向导
├── content/       # 主题、插件、上传、缓存等可变内容
└── system/        # 内核、业务、后台逻辑、公共库

content/ — 内容区

content/
├── theme/       # 前台主题
├── plugin/      # 插件
├── admin/       # 后台视图（HTML / CSS / JS）
├── upload/      # 用户上传文件
├── cache/       # 运行时缓存（配置、分类、统计等）
├── lang/        # 语言包
├── logs/        # 日志
├── static/      # 静态资源
└── theme_ref/   # 主题参考材料（非运行必需）

站内开发文档位于当前主题 content/theme/hopecms/docs/。

system/ — 程序区

system/
├── Hope/            # 内核命名空间：启动、路由、配置、事件
├── app/             # 业务分层：handler / store / service
├── admin/           # 后台控制器
├── lib/             # 公共库
├── options/         # 主题选项框架（Codestar）
├── deploy/          # 部署示例（如 nginx）
├── bootstrap.php    # 内核引导（前台 / 后台共用）
├── config.php       # 数据库等站点配置
└── checkcode.php    # 验证码兼容入口

system/Hope/ — 内核

system/Hope/
├── Foundation/            # Application、Paths、ClassLoader、path_constants
├── Bootstrap/             # RuntimeBoot 启动编排
├── Http/                  # FrontRouter、Request、RouteMatch
├── Config/                # Settings 站点配置
├── Runtime/               # SnapshotBank 快照缓存
├── Presentation/          # PageComposer 视图路径解析
└── Event/                 # HookBus 事件总线

system/app/ — 业务分层

system/admin/ — 后台控制器

按功能拆分，例如：article.php、article_edit.php、comment.php、setting.php、theme.php、plugin.php 等。
视图在 content/admin/。

system/lib/ — 公共库

lib/
├── auth/          # 登录会话、密码、授权
├── database/      # HopeDb / HopeMysqli / 查询与元存储
├── http/          # 请求输入、站点 URL、JSON 输出、HTTP 客户端
├── mail/          # 邮件发送
├── payment/       # 支付通道与收银台
├── captcha/       # 验证码与字体
├── markdown/      # Markdown 解析
├── support/       # 语言、异常等支撑
├── view/          # 侧栏日历、应用商店视图 helpers
├── common.php     # 全局辅助函数
├── hooks.php      # 钩子常量
├── sidebar.php    # 侧栏注册与渲染
└── upgrade_helper.php

其他

请求流程

前台

index.php
  → system/bootstrap.php
  → Application 启动
  → FrontRouter 匹配路由
  → app/handler/*
  → content/theme/<当前主题>/

后台

admin.php
  → system/bootstrap.php（加载内核）
  → system/admin/globals.php
  → system/admin/<act>.php
  → content/admin/<act>.php（视图）

记忆口诀

• content：装什么（主题、插件、文件、缓存）
• system：怎么跑（内核、业务、后台、公共库）

二次开发时：改界面与扩展优先看 content/；改路由、保存逻辑、权限与数据层优先看 system/。

开发准备工作

Hope CMS 支持主题与插件扩展。本文说明本地环境、目录约定、请求流程与常用 API，便于二次开发。

相关：挂载点手册 · 主题开发指南 · 插件开发指南 · 数据库与 SQL

开发环境

将站点根目录（含 index.php）设为 Web 根目录，并确保 content/upload/、content/cache/ 可写。

目录结构

根目录只保留 content/（内容区）与 system/（程序区），外加入口文件：

hope/                              # 站点根（HOPE_ROOT）
├── index.php                      # 前台入口
├── admin.php                      # 后台入口
├── install.php                    # 安装向导（库表 SQL 内嵌）
├── system/                        # 内核（升级会覆盖，勿直接改业务）
│   ├── Hope/                      # Foundation / Bootstrap / Http / Config / Runtime / Presentation / Event
│   ├── app/
│   │   ├── handler/               # 前台请求处理（*_Handler）
│   │   ├── store/                 # 数据访问（*_Store）
│   │   └── service/               # 领域服务
│   ├── admin/                     # 后台控制器（与 content/admin 视图配对）
│   ├── lib/                       # 公共库（common.php、hooks.php、sidebar.php、database/、http/…）
│   ├── options/                   # 主题选项框架（CSF）
│   ├── bootstrap.php              # 内核引导
│   └── config.php                 # 数据库、AUTH_KEY 等
└── content/                       # ★ 开发者主要工作区
    ├── theme/                     # 主题
    ├── plugin/                    # 插件
    ├── admin/                     # 后台 HTML / CSS / JS
    ├── upload/                    # 用户上传
    ├── cache/                     # 运行时缓存
    ├── lang/                      # 语言包
    └── logs/                      # 日志

记忆口诀： content 装什么；system 怎么跑。

完整说明见 目录说明。

快速上手：示例插件

官方示例： content/plugin/tips/

1. 复制 tips 目录并改名，修改 Plugin Name 与函数前缀
2. 后台 插件 → 插件管理 启用
3. 启用时加载 {插件}_callback.php 并调用 callback_init()

// tips.php
hope_listen('adm_main_top', 'tips_render_admin_banner');
hope_listen('adm_head', 'tips_enqueue_admin_css');

// tips_callback.php
function callback_init() { /* 启用即生效 */ }
function callback_rm() {
    MetaStorage::getInstance('tips')->deleteAllName('YES');
}

完整说明见 插件开发指南。

快速上手：示例主题

官方示例： content/theme/default/

1. 复制 default 为新主题目录，修改 head.php 元信息与 settings.php 的 $prefix
2. 在 pages/ 下新建页面模板，首行写 /*@name 关于我们*/
3. 后台 页面 → 新建页面，选择对应模板
4. 布局参考同主题 head.php / foot.php

<?php
/*@name 关于我们*/
defined('HOPE_ROOT') || exit('access denied!');
?>
<section class="about">
    <h1><?= htmlspecialchars((string) Settings::get('sitename')) ?></h1>
</section>
<?php include PageComposer::themePath('footer'); ?>

文件清单、CSF、模板变量见 主题开发指南。

请求流程

插件可通过 HopeHooks::ROUTING_REGISTER 注册前台伪静态路由，见 伪静态与路由。

常用常量

路径常量：HOPE_PATH_APP、HOPE_PATH_STORE、HOPE_PATH_HANDLER、HOPE_PATH_SERVICE、HOPE_PATH_ADMIN、HOPE_PATH_LIBRARY。

用户角色

插件后台页由核心保障管理员权限；独立 AJAX 需自行校验：

if (!AuthSession::isLogin() || ROLE !== ROLE_ADMIN) {
    JsonOut::authError('权限不足');
}

挂载点（速览）

hope_listen(HopeHooks::ADM_HEAD, 'tips_enqueue_admin_css');
hope_listen(HopeHooks::ADM_MAIN_TOP, 'tips_render_admin_banner');
hope_emit(HopeHooks::INDEX_HEAD);

完整列表见 挂载点手册。常量源码：system/lib/hooks.php。

配置与选项

系统设置

$sitename = Settings::get('sitename');
Settings::updateOption('apikey', $key);
Settings::updateOption('is_openapi', 'y');

主题配置（CSF）

$color = hope_option('primary_color', '#3b82f6');
$layout = _hope('site_layout', 'double');

站点标题等请用 Settings::get('sitename') / hope_site_name()。

插件私有配置

$storage = MetaStorage::getInstance('tips');
$storage->setValue('config', ['foo' => 'bar'], 'array');
$config = $storage->getValue('config');
$storage->deleteAllName('YES'); // 卸载时

输入输出

$id   = RequestInput::getIntVar('id');
$page = RequestInput::getIntVar('page', 1, 1);
$name = RequestInput::postStrVar('name');
$pwd  = RequestInput::postRawStr('password');

JsonOut::ok(['list' => $rows]);
JsonOut::error('参数错误');
JsonOut::authError('未登录');

hope_abort('权限不足', './');

模板与 URL

include PageComposer::themePath('header');     // → head.php
include PageComposer::themePath('log_list');   // → archive.php
include PageComposer::themePath('pages/about'); // 独立页模板
include PageComposer::userPath('index');       // account/

SiteUrl::post($gid);
SiteUrl::category($sid);
SiteUrl::tag($tagname);
SiteUrl::plugin('tips', ['id' => 1]);
SiteUrl::userCenter(['api' => 1]);

URL 规则受后台「设置 → 链接」影响，见 伪静态与路由。

命名迁移速查

完整对照与运行时垫片见 常见问题 · 旧版兼容。

开发规范

• PHP 遵循 PSR-1、PSR-12
• 文件开头：defined('HOPE_ROOT') || exit('access denied!');
• 主题配置用 hope_option / _hope，始终带默认值
• 禁止在业务里 HopeDb::getInstance()->query() 拼接不可信输入
• 输出用户内容用 htmlspecialchars / hope_html_clean

开启开发者模式

方式一： 在 system/config.php 末尾：

const ENVIRONMENT = 'develop';

方式二： 后台开启「调试模式」。

上线前请改回 production 并关闭调试。错误日志多在 content/cache/error.log 或 content/logs/。

下一步

• 挂载点手册
• 插件开发指南
• 主题开发指南
• 数据库与 SQL
• API 开发文档

挂载点手册

Hope CMS 通过挂载点（Hook）在不改核心的前提下扩展功能。常量定义于 system/lib/hooks.php（HopeHooks），注册/触发 API 在 system/lib/common.php。

相关：开发准备工作 · 插件开发指南 · 伪静态与路由

API 一览

// 注册（推荐常量）
hope_listen(HopeHooks::INDEX_HEAD, 'myplugin_head_css');
hope_listen('adm_main_top', 'tips_render_admin_banner'); // 字符串亦可

// 触发
hope_emit(HopeHooks::INDEX_HEAD);
hope_emit(HopeHooks::SAVE_LOG, $gid, $logData);

约定：

• 回调内输出用户内容用 htmlspecialchars
• 需要 JSON 中断时用 JsonOut::* / hope_abort()，避免半截 HTML
• 函数名加插件/主题前缀，避免冲突

启动与路由

hope_listen(HopeHooks::ROUTING_REGISTER, 'myplugin_register_routes');

详见 伪静态与路由。

前台页面

主题模板负责 hope_emit(...)，插件负责 hope_listen(...)。

文章与评论

hope_listen(HopeHooks::ARTICLE_CONTENT_ECHO, function ($content, &$ret) {
    $ret = str_replace('foo', 'bar', $ret ?: $content);
});

用户与登录

hope_listen(HopeHooks::USER_MENU, function () {
    echo '<a href="' . htmlspecialchars(SiteUrl::plugin('myplugin')) . '">我的扩展</a>';
});

后台

hope_listen(HopeHooks::ADM_MENU_EXT, function () {
    echo '<li><a href="./?act=plugin_set&plugin=myplugin">我的插件</a></li>';
});

具体菜单 HTML 请对照当前后台模板。

用户管理事件

媒体与下载

分类、设置与插件生命周期

示例：最小可用

// myplugin.php
hope_listen(HopeHooks::ADM_HEAD, 'myplugin_admin_css');
hope_listen(HopeHooks::SAVE_LOG, 'myplugin_on_save');

function myplugin_admin_css() {
    echo '<link rel="stylesheet" href="' . HOPE_PLUGINS_URL . 'myplugin/assets/admin.css">' . "\n";
}

function myplugin_on_save($gid, $data = null) {
    // 文章保存后的业务逻辑
}

源码常量以 system/lib/hooks.php 为准；本页与代码不一致时以代码为准。

数据库与 SQL

Hope CMS 使用 MySQL / MariaDB。业务访问统一通过 HopeDb 与 HopeSql 完成。

• 生命周期 / MetaStorage：对照示例插件 tips
• 自建表：对照 oauth、video、music 的 *_upgrade_schema() / callback_init()

相关：插件开发指南 · 升级与更新

核心类与文件

表前缀

const DB_PREFIX = 'hope_'; // system/config.php

约定：

• HopeDb::table('article') 不要手动加前缀，框架会拼为 hope_article
• 原生 SQL 可拼接 DB_PREFIX，或在 HopeSql / HopeDb::executeFile 中使用 {db_prefix}
• 少数场景：DB_PREFIX . 'myplugin_log'

链式查询（推荐）

$rows = HopeDb::table('myplugin_log')
    ->where(['status' => 1, 'uid' => $uid])
    ->whereLike('title', $keyword)
    ->whereIn('id', $ids)
    ->order('id DESC')
    ->limit(20, 0)
    ->findAll();

$row = HopeDb::table('myplugin_log')->where(['id' => $id])->find();

$total = HopeDb::table('myplugin_log')->where(['status' => 1])->count();

$list = HopeDb::table('myplugin_log', 'l')
    ->select(['l.id', 'l.title', 'u.nickname'])
    ->leftJoin('user', 'u', 'l.uid = u.uid')
    ->where(['l.status' => 1])
    ->order('l.id DESC')
    ->limit(10)
    ->findAll();

链式方法一览

快捷方法

HopeDb::select('article', ['hide' => 'n']);
HopeDb::getOne('user', ['uid' => 1]);
HopeDb::insert('myplugin_log', ['title' => '示例', 'status' => 1]);
HopeDb::update('myplugin_log', ['id' => 1], ['status' => 0]);
HopeDb::delete('myplugin_log', ['id' => 1]);
HopeDb::count('myplugin_log', ['status' => 1]);

原生 SQL

$rows = HopeDb::fetchAll(
    'SELECT * FROM `' . DB_PREFIX . 'myplugin_log` WHERE uid = ' . (int) $uid
);

$row = HopeDb::fetchOne('SELECT COUNT(*) AS cnt FROM `' . DB_PREFIX . 'myplugin_log`');

HopeDb::execute('UPDATE `' . DB_PREFIX . 'myplugin_log` SET views = views + 1 WHERE id = ' . (int) $id);

$safe = HopeDb::escape($keyword);

插件/主题建表（callback_init）

不再使用目录下的 install.sql 自动执行。启用时核心只调用 callback_init()。

function myplugin_upgrade_schema() {
    $table = DB_PREFIX . 'myplugin_log';
    if (HopeDb::fetchOne("SHOW TABLES LIKE '{$table}'")) {
        return;
    }
    HopeDb::execute("CREATE TABLE IF NOT EXISTS `{$table}` (
        `id` int unsigned NOT NULL AUTO_INCREMENT,
        `title` varchar(255) NOT NULL DEFAULT '',
        `uid` int unsigned NOT NULL DEFAULT 0,
        `status` tinyint NOT NULL DEFAULT 1,
        PRIMARY KEY (`id`)
    ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4", true);
}

function callback_init() {
    myplugin_upgrade_schema();
}

function callback_rm() {
    MetaStorage::getInstance('myplugin')->deleteAllName('YES');
    HopeSql::dropTables(['myplugin_log']);
}

何时执行

HopeSql 高级选项

HopeSql::executeFile(HOPE_ROOT . 'path/to/custom.sql', [
    'replace_prefix' => true,
    'ignore_error'   => false,
    'charset_setup'  => false,
    'version_gate'   => false,
]);

HopeSql::dropTables(['table_a', 'table_b'])：逻辑表名（不含前缀）批量 DROP。

字段升级（Schema Migration）

function myplugin_upgrade_schema_fields() {
    static $done = false;
    if ($done) return;
    $done = true;

    $table = DB_PREFIX . 'myplugin_log';
    HopeDb::execute("CREATE TABLE IF NOT EXISTS `{$table}` (...)", true);

    $existing = [];
    foreach (HopeDb::fetchAll("SHOW COLUMNS FROM `{$table}`") as $col) {
        $existing[$col['Field']] = true;
    }

    if (empty($existing['new_field'])) {
        HopeDb::execute(
            "ALTER TABLE `{$table}` ADD COLUMN `new_field` varchar(100) NOT NULL DEFAULT ''",
            true
        );
    }
}

在 callback_init() / callback_up() 中调用同一函数即可。

MetaStorage 插件存储

$storage = MetaStorage::getInstance('tips');

$storage->setValue('config', [
    'enabled' => 'y',
    'per_page' => 20,
], 'array');

$config = $storage->getValue('config');
$storage->deleteAllName('YES');

适合开关、JSON 配置、计数；列表/关联数据请自建表。

系统核心表（只读参考）

不得修改以下核心表结构，仅可通过 Store / API 读写：

插件自建表命名建议：{DB_PREFIX}{插件名}_{用途}，如 hope_oauth_bind。

开发建议

1. 生命周期 → 先写好 callback_* 与 MetaStorage
2. 新建表 → callback_init / *_upgrade_schema()
3. 加字段 → 同一升级函数内 SHOW COLUMNS + ALTER
4. 日常查询 → 优先 HopeDb::table() 链式
5. 复杂 SQL → fetchAll / fetchOne / execute，注意转义
6. 卸载清理 → callback_rm() 必须清 MetaStorage；有表则明确是否 DROP

主题开发指南

主题位于 content/theme/{主题目录}/。启用后前台页面由该目录下的 PHP 模板渲染。

官方示例主题：content/theme/default/。学习列表页、侧边栏、用户中心、CSF 设置时优先对照此主题。

相关文档：开发准备工作 · 挂载点手册 · 侧边栏开发说明 · 伪静态与路由 · 数据库与 SQL

站内「主题生成器」页可拼装主题 PHP 片段（输出适配现行 Hope CMS API）。

1. 从零创建主题

1. 复制 content/theme/default/ 为 content/theme/你的主题/
2. 修改 head.php 顶部 Theme Name / Version / Description
3. 修改 settings.php 的 $prefix（如 yourtheme_options）与标题文案
4. 将 functions.php 中函数前缀（如 nova_*）改为自己的命名空间，避免冲突
5. 后台 外观 → 主题 启用；如有 callback.php，启用时会执行 callback_init()
6. 建议执行一次 设置 → 更新缓存
7. 到 外观 → 侧边栏 检查组件是否仍可用

2. 目录结构

官方 default 采用下列命名（推荐新主题照此创建）：

content/theme/default/
├── head.php               # 必需：主题元信息 + HTML 头部
├── foot.php               # 必需：页脚与闭合标签
├── archive.php            # 必需：首页 / 分类 / 标签 / 搜索 / 归档列表
├── single.php             # 必需：文章详情
├── 404.php                # 推荐：404 页
├── functions.php          # 推荐：主题函数库（模板中 require）
├── settings.php           # 可选：CSF 主题设置
├── hooks.php              # 可选：主题级钩子（每请求自动 include）
├── callback.php           # 可选：启用 / 删除 / 升级回调
├── preview.png            # 推荐：后台主题列表预览图
├── widgets/               # 可选：侧边栏
│   ├── sidebar.php
│   ├── config.php         # 组件注册表（注册 key 仍可用 side_*）
│   └── widget-*.php       # 如 widget-blogger.php
├── pages/                 # 可选：独立页面模板
│   └── page.php
├── account/               # 可选：登录 / 注册 / 用户中心
│   ├── index.php
│   ├── login.php
│   ├── register.php
│   ├── auth.php
│   └── profile.php
├── partials/              # 可选：可复用片段
└── assets/                # 静态资源
    ├── css/
    ├── img/
    └── js/

最小可运行主题

至少需要：head.php、foot.php、archive.php、single.php。其余按需增加。

3. 主题元信息

写在 head.php 文件最顶部的注释块，后台主题列表会解析：

<?php
/*
Theme Name: 默认主题
Theme Type: cms
Theme Url: http://www.hopecms.cn
Author: Hope CMS
Author Url: http://www.hopecms.cn
Version: 1.0.0
Description: Hope CMS 默认主题：大标题首页、双栏列表、标签云侧栏与个人中心。
*/
defined('HOPE_ROOT') || exit('access denied!');
require_once PageComposer::themePath('module'); // → functions.php

Theme Type 与后台展示对应关系（Theme_Store）：

示例：Theme Type: cms → 显示「博客」；Theme Type: cms video → 显示「博客.视频」。

4. 核心模板与变量

控制器先 include PageComposer::themePath('header')，再 include 列表或详情模板；模板内再 include footer（逻辑名；物理文件可为 head.php / foot.php）。

4.1 列表页 archive.php（逻辑名 log_list）

用于首页、分类、标签、搜索、日期归档、作者页等。

$page_html = hope_pagination($lognum, $index_lognum, $page, $pageurl);
foreach ($logs as $value) {
    // $value['gid'] $value['log_title'] $value['log_cover'] ...
    echo '<a href="' . SiteUrl::post($value['gid']) . '">'
        . htmlspecialchars($value['log_title']) . '</a>';
}

列表变体（可选）：archive_card.php / archive_grid.php / archive_seamless.php，可由主题设置切换；薄封装内通常 include PageComposer::themePath('archive')。

4.2 详情页 single.php（逻辑名 echo_log）

<?php include PageComposer::themePath('sidebar'); ?>
<?php include PageComposer::themePath('footer'); ?>

4.3 head.php / foot.php 常用变量

头部 / 页脚应输出挂载点：

<?php hope_emit('index_head'); ?>
<?php hope_emit('index_footer'); ?>

站点标题请读系统设置，例如：

htmlspecialchars((string) Settings::get('sitename'));
// 或主题助手：hope_site_name() / hope_site_info()

5. 自定义页面

后台创建「页面」时可选择模板，文件放在 pages/：

<?php
/*@name 关于我们*/
defined('HOPE_ROOT') || exit('access denied!');
?>
<main>
    <h1>关于我们</h1>
    <div><?= $log_content ?></div>
</main>
<?php include PageComposer::themePath('footer'); ?>

• @name 后的文字会出现在后台模板下拉里
• 页面同样会先加载 head.php（逻辑名 header），模板内记得闭合 footer
• 复杂站点（如本主题 hopecms）可有多个：page_docs.php、page_download.php、page_generator.php（主题生成器）等

6. functions.php

建议所有主题辅助函数集中在此，并在 head.php 中：

require_once PageComposer::themePath('module'); // 逻辑名 → functions.php

function your_asset($path) {
    $path = ltrim((string) $path, '/');
    if ($path !== '' && strpos($path, 'assets/') !== 0) {
        $path = 'assets/' . $path;
    }
    return THEME_URL . $path;
}

function your_brand() {
    $name = trim((string) Settings::get('sitename'));
    return htmlspecialchars($name !== '' ? $name : 'Hope CMS');
}

生成内容链接用核心类，不要手拼规则：

SiteUrl::post($gid);          // 文章
SiteUrl::category($sid);      // 分类
SiteUrl::tag($tagname);       // 标签
SiteUrl::author($uid);        // 作者
SiteUrl::userCenter();        // 个人中心

7. settings.php（主题设置）

主题目录内有 settings.php 时，后台出现主题设置页（Codestar / CSF）。

约定

<?php
if (!defined('HOPE_ROOT')) exit;

$prefix = 'yourtheme_options';

CSF::createOptions($prefix, [
    'plugin_title' => '某某主题设置',
    'footer_text'  => 'Hope CMS',
    'theme'        => 'light', // light | dark | auto
]);

CSF::createSection($prefix, [
    'title'  => '基本设置',
    'icon'   => 'fa fa-cog',
    'fields' => [
        [
            'type'    => 'notice',
            'style'   => 'info',
            'content' => '站点标题、副标题、SEO 描述与页脚版权请在后台「设置 → 站点信息 / SEO 设置」中维护。',
        ],
        [
            'id'      => 'primary_color',
            'type'    => 'color',
            'title'   => '主题色',
            'default' => '#3b82f6',
        ],
        [
            'id'      => 'hero_enable',
            'type'    => 'switcher',
            'title'   => '启用首页 Hero',
            'default' => true,
        ],
    ],
]);

options完整的.php 覆盖：文本、选择、开关、上传、颜色、调色板、repeater/group、accordion/tabbed、code_editor、依赖 dependency、backup 等。

WordPress Codestar 可迁移：API 用 CSF::；读取用 hope_option()，不要用 get_option。

8. hooks.php（主题钩子）

每个前台请求在加载已启用插件之后，会自动 include 当前主题的 hooks.php（若存在），再执行 hope_emit('init')。

适合：注册主题专属钩子、挂文章自定义字段、改写用户中心菜单等。

<?php
defined('HOPE_ROOT') || exit('access denied!');

hope_listen('index_head', 'yourtheme_extra_css');
hope_listen('user_menu', 'yourtheme_user_menu_item');

9. callback.php（主题生命周期）

可在启用时建表、写默认配置；删除时清理 MetaStorage / 自建表。建表写法见 数据库与 SQL。

<?php
defined('HOPE_ROOT') || exit('access denied!');

function callback_init() {
    // 同步默认配置、建扩展表
}

function callback_rm() {
    // MetaStorage::getInstance('yourtheme')->deleteAllName('YES');
}

10. 侧边栏与用户中心

• 侧边栏：widgets/ + config.php，详见 侧边栏开发说明
• 用户中心：优先使用主题 account/；若主题未提供，系统可能回退到其它主题的 user/
• 登录 / 注册页同理，建议主题内自备完整 account/ 目录

include PageComposer::userPath('index');

11. 挂载点（主题侧）

主题模板负责 埋点，插件负责 注册回调。

完整列表见 挂载点手册。

12. 检查清单与注意事项

1. 不硬编码域名，用 SITE_URL、THEME_URL、SiteUrl::*
2. 输出用户内容用 htmlspecialchars
3. 勿修改 system/；业务扩展用主题 hooks.php 或独立插件
4. $prefix 与函数名前缀全局唯一
5. hope_option / _hope 始终带默认值
6. SITE_URL 已有尾斜杠，拼接时避免双斜杠
7. 静态资源建议放在 assets/
8. 启用新主题后更新缓存；换主题后检查侧边栏组件是否仍注册
9. 站点标题 / SEO 用系统设置，不在主题 CSF 重复配置

侧边栏开发说明

Hope CMS 主题侧边栏由「容器模板 + 配置注册 + 组件文件」组成，统一放在 widgets/ 目录。后台在 外观 → 菜单 → 侧边栏 中按组管理组件；前台按槽位渲染。

无侧边栏的主题可不创建 widgets/ 目录。

相关：主题开发指南

目录约定

推荐（与官方 default 一致）：

content/theme/default/
├── functions.php
└── widgets/
    ├── sidebar.php          # 默认侧边栏容器
    ├── config.php           # $sidebar 组件注册表
    ├── widget-search.php
    ├── widget-newlog.php
    ├── widget-hotlog.php
    └── ...

*注册 key 仍建议使用 `side_`**（与后台已存配置兼容）。默认解析：

1. widgets/widget-{name}.php（如 key side_blogger → widget-blogger.php）

列表页、文章页中引入：

<?php include PageComposer::themePath('sidebar'); ?>

第二组：

<?php include PageComposer::themePath('sidebar1'); ?>

容器模板

<?php
defined('HOPE_ROOT') || exit('access denied!');
?>
<aside class="sidebar">
    <?php hope_emit('index_sidebar'); ?>
    <?php if (!hope_render_sidebar_widgets('sidebar')): ?>
        <?php
        hope_include_sidebar_widget('side_newlog', '最新文章', ['显示数量' => '5']);
        ?>
    <?php endif; ?>
</aside>

要点：

1. hope_emit('index_sidebar')：插件可在此插入内容
2. hope_render_sidebar_widgets($slot)：按组输出；$slot 与文件名一致（sidebar / sidebar1）
3. 核心 API 在 system/lib/sidebar.php

注册组件（widgets/config.php）

<?php
defined('HOPE_ROOT') || exit('access denied!');

$sidebar = [
    'side_search' => [
        'title' => '搜索',
        'default' => [
            '输入提示' => '搜索文章、标签…',
        ],
    ],
    'side_hotlog' => [
        'title' => '热门文章',
        'default' => [
            '显示数量' => '5',
        ],
    ],
];

自定义 HTML 组件无需注册：后台类型选「自定义组件」。

编写组件文件

例如 widgets/widget-hotlog.php（注册 key 为 side_hotlog）：

<?php
defined('HOPE_ROOT') || exit('access denied!');

$limit = (int) hope_widget_field($fields, '显示数量', $widget_config['default']['显示数量'] ?? 5);
$Post_Store = new Post_Store();
$logs = $Post_Store->getHotLog(max(1, $limit));
?>
<div class="widget widget-hotlog">
    <h3 class="widget-title"><?= htmlspecialchars($widget_title ?: '热门文章') ?></h3>
    <!-- 循环输出 $logs -->
</div>

渲染时注入的变量：

$limit = (int) hope_widget_field($fields, '显示数量', $widget_config['default']['显示数量'] ?? 5);
$hint  = hope_widget_field($fields, '输入提示', '搜索…');

自定义 HTML 组件

无需在 config.php 注册。后台添加侧边栏项时类型选「自定义组件」，直接填 HTML。

未配置任何组件时，容器内应用 hope_include_sidebar_widget(...) 做兜底，避免空白侧栏。

切换主题后：旧主题注册的组件类型若新主题没有对应文件，该项可能不渲染——启用新主题后请到 外观 → 侧边栏 检查并调整。

多侧边栏组

1. 在 widgets/ 增加 sidebar1.php、sidebar2.php…（内调 hope_render_sidebar_widgets('sidebar1')）
2. 后台「菜单 → 侧边栏」会出现组切换 Tab
3. 添加的组件会写入对应组

渲染流程

后台菜单(type=sidebar, url=slot)
    → SnapshotBank menu 缓存
    → hope_menu_sidebar_widgets(slot)
    → hope_render_sidebar_widget()
         ├─ 解析 widget-*.php / side_*.php → include
         └─ 否则输出自定义 content

检查清单

1. config.php 中 $sidebar 键名与组件文件映射一致（side_foo → widget-foo.php）
2. 容器已调用 hope_render_sidebar_widgets('sidebar')
3. 后台能看到已注册组件，多组时能切换
4. 未配置组件时有合理兜底
5. 无侧边栏主题不创建 widgets/

更多主题约定见 主题开发指南。

插件开发指南

插件是在不修改 system/ 核心的前提下扩展 Hope CMS 的主要方式：通过挂载点插入逻辑、可选建表、提供后台设置页与前台页面。

官方示例插件： content/plugin/tips/（小贴士）。无自建表、结构完整，适合作为脚手架。

有表 / 存储的对照：content/plugin/oauth/（callback_init 建表 + MetaStorage 配置）。

相关文档：开发准备工作 · 挂载点手册 · 数据库与 SQL · 升级与更新 · 伪静态与路由 · API 开发文档 · 常见问题

1. 从 tips 起步

1. 复制 content/plugin/tips/ → content/plugin/你的插件名/
2. 目录名与入口文件名一致：你的插件名/你的插件名.php
3. 重命名 tips_*.php，并全局替换函数前缀（如 tips_ → myplugin_）
4. 修改入口文件头信息中的 Plugin Name / Description / Version
5. 后台 插件 → 插件管理 启用
6. 确认钩子生效；需要持久化时再补 MetaStorage / 建表

启用时核心流程：写入 active_plugins → 加载 {插件}_callback.php → 调用 callback_init()（不会自动执行 install.sql）。

每请求加载：对已启用插件 include_once content/plugin/{名}/{名}.php，再加载当前主题 hooks.php，最后 hope_emit('init')。

2. 目录结构

content/plugin/tips/
├── tips.php                 # 必需：入口 + 头信息 + 注册钩子
├── tips_callback.php        # 强烈推荐：启用 / 更新 / 删除
├── tips_setting.php         # 可选：后台设置页（有则显示「设置」）
├── tips_lib.php             # 推荐：业务函数
├── tips_show.php            # 可选：前台独立页（SiteUrl::plugin）
├── preview.png              # 可选：插件列表预览图
└── assets/
    └── tips.css

命名规则：目录名、入口文件名、钩子函数前缀保持一致。

3. 入口文件与头信息

<?php
/*
Plugin Name: 小贴士
Version: 1.0.0
Plugin URL: http://www.hopecms.cn
Description: 插件启用后，在后台首页随机展示一句内置使用提示。
Author: Hope CMS
Author URL: http://www.hopecms.cn
*/
!defined('HOPE_ROOT') && exit('error');

require_once HOPE_ROOT . 'content/plugin/tips/tips_lib.php';

hope_listen('adm_main_top', 'tips_render_admin_banner');
hope_listen('adm_head', 'tips_enqueue_admin_css');

active_plugins 中存储的是相对路径：tips/tips.php。

4. 生命周期回调

文件：content/plugin/{名}/{名}_callback.php

tips（无表）

<?php
defined('HOPE_ROOT') || exit('access denied!');

function callback_init() {
}

function callback_up() {
    callback_init();
}

function callback_rm() {
    MetaStorage::getInstance('tips')->deleteAllName('YES');
}

有表时（对照 oauth）

function callback_init() {
    require_once HOPE_ROOT . 'content/plugin/oauth/oauth_lib.php';
    oauth_upgrade_schema(); // 内含 CREATE TABLE IF NOT EXISTS
    $storage = MetaStorage::getInstance('oauth');
    if (!$storage->getValue('config')) {
        $storage->setValue('config', oauth_default_config(), 'array');
    }
}

function callback_rm() {
    MetaStorage::getInstance('oauth')->deleteAllName('YES');
    HopeSql::dropTables(['oauth_bind']); // 不带表前缀
}

要点：

• 建表在 PHP 里执行，不要依赖自动跑 install.sql
• HopeDb::table('xxx') 不带前缀；原生 SQL / dropTables 注意 DB_PREFIX
• 卸载是否删表由你决定：商业数据可选择只清 MetaStorage、保留业务表

详见 数据库与 SQL、升级与更新。

5. 挂载点（Hook）

hope_listen('adm_main_top', 'tips_render_admin_banner');
hope_listen(HopeHooks::ADM_HEAD, 'tips_enqueue_admin_css'); // 推荐常量

常用挂载点

完整参数与示例见 挂载点手册。

约定： 钩子回调里输出 HTML 时对用户数据做 htmlspecialchars；需要中断请求时用 JsonOut::* / hope_abort()。

6. 后台设置页

存在 {名}_setting.php 且插件已启用时，插件列表显示「设置」。

访问：{后台入口}?act=plugin_set&plugin=tips
（默认入口为 admin.php，生产环境应重命名。）

必须定义：

<?php
defined('HOPE_ROOT') || exit('access denied!');

function plugin_setting_view() {
    // 输出后台 HTML（可沿用 content/admin 的 Bootstrap / card 样式）
}

保存配置推荐两种方式：

A. MetaStorage（键值，适合开关与小配置）

$storage = MetaStorage::getInstance('myplugin');
$storage->setValue('config', ['enable' => 1], 'array');
$config = $storage->getValue('config');

B. 自建表

用 HopeDb::table(...)->insert/update；设置页里处理 POST 时用 RequestInput::postStrVar 等过滤。

设置页由核心保证管理员登录；若另写 AJAX 接口，须自行校验：

if (!AuthSession::isLogin() || ROLE !== ROLE_ADMIN) {
    JsonOut::authError('权限不足');
}

7. 前台页面 {名}_show.php

放置该文件且插件已启用时，可通过插件路由访问：

$url = SiteUrl::plugin('tips');
$url = SiteUrl::plugin('tips', ['id' => 1]);

• 未启用或文件不存在 → 404
• 页面可自绘完整 HTML，也可 include 当前主题头尾保持站点风格

include PageComposer::themePath('header');
// ... 插件内容 ...
include PageComposer::themePath('footer');

静态资源：

function tips_asset_url($path) {
    return HOPE_PLUGINS_URL . 'tips/assets/' . ltrim($path, '/');
}

8. 数据库与配置

$rows = HopeDb::table('myplugin_log')
    ->where(['uid' => $uid])
    ->order('id DESC')
    ->limit(20)
    ->findAll();

禁止在业务里直接拼接不可信输入执行 SQL。详见 数据库与 SQL。

9. 安全规范

1. 每个 PHP 文件检查 HOPE_ROOT
2. 读写请求用 RequestInput::getIntVar / postStrVar / postRawStr
3. 输出 HTML 用 htmlspecialchars；JSON 用 JsonOut::ok / JsonOut::error
4. CSRF：后台表单遵循现有 admin 习惯；前台写操作校验登录态与 token
5. 不修改核心表结构语义；不覆盖 system/、content/admin 核心文件
6. SQL 表名、字段名白名单化，勿把用户输入拼进标识符

10. 调试

1. system/config.php 增加 const ENVIRONMENT = 'develop';，或后台开启调试模式
2. 错误日志：content/logs/ 或 content/cache/error.log
3. 改钩子后：禁用再启用插件，确保 callback_init 重跑
4. 确认 active_plugins 中路径为 目录/入口.php
5. 前台 _show.php 404：检查是否启用、文件名是否 {名}_show.php、链接是否 SiteUrl::plugin

11. 与主题的分工

Shop 等主题依赖的商业能力应做成普通插件，可启用 / 禁用 / 删除，而不是改核心。

12. 发布检查清单

• [ ] 头信息完整，Version 可递增
• [ ] callback_rm 清理 MetaStorage；有表则明确是否 dropTables
• [ ] callback_up / *_upgrade_schema 可重复执行（IF NOT EXISTS / 判列）
• [ ] 设置页、前台页在未启用时不可访问
• [ ] 函数名、MetaStorage 名、表名带插件前缀，无全局污染
• [ ] 附简短说明（README 或设置页文案）
• [ ] 在 PHP 7.4+ / 8.x 各测一次启停与卸载

13. 最小插件骨架

<?php
/*
Plugin Name: 演示插件
Version: 1.0.0
Description: 最小可运行示例
Author: You
*/
!defined('HOPE_ROOT') && exit('error');

hope_listen('adm_head', function () {
    echo "<!-- myplugin loaded -->\n";
});

仅入口也可运行；正式发布请补全 _callback.php 与卸载清理。

伪静态与 URL 路由

Hope CMS 通过 链接模式（linkmode） 与 路由表 控制前台 URL 形态。后台在 设置 → 链接 中配置；路由表由 Settings::getEnhancedRoutingTable() 生成，由 Hope\Http\FrontRouter 匹配并分发到对应 *_Handler。

相关：挂载点手册 · API 开发文档 · 插件开发指南

链接模式

$linkmode = (string) Settings::get('linkmode');
$isRewrite = ($linkmode === '1' || $linkmode === '2');

保存链接设置后会刷新路由缓存。

后台 设置 → 更新缓存（全量 $SNAP->refresh()）也会一并调用 Settings::resetRoutingTableCache()，清空进程内路由表缓存。单独刷新 options 缓存时同样会重置路由表。

后台 URL 规则

在 设置 → 链接 → 伪静态管理 中可配置（hope_option 键名）：

生成链接时由 SiteUrl 替换占位符。

常用占位符

变量隔离： 文章路径里的分类请写 {%category_alias%}；分类列表自身写 {%alias%}。

分页占位符 {%page%} 在生成非分页链接时会被自动剔除。推荐连接写法：/{%page%}/、_{%page%}、-{%page%}、?page={%page%}。

自定义首页（home_page_id > 0）时，文章列表分页由 SiteUrl::postPage() 生成，路径可能带 posts/ 前缀。

内置活动路由

伪静态示例：/user、/login、/register、/plugin/video
动态示例：?user、?login、?plugin=video

请求匹配流程

浏览器请求
  → Web 服务器重写到 index.php（伪静态时）
  → FrontRouter 解析路径
  → Settings 路由表按优先级匹配
  → 校验 must_get / 方法
  → 写入 $_GET
  → *_Handler 执行

要点：

1. 伪静态模式跳过纯 query 型内容路由；动态模式跳过纯 path 型 rewrite 路由
2. 活动路由排在默认首页路由之前，避免 ?category=1 被首页抢走
3. 插件可通过 HopeHooks::ROUTING_REGISTER 向路由表头部追加规则

Web 服务器配置

Apache（站点根目录 .htaccess）

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [L]
</IfModule>

子目录安装（如 /hope/）将 RewriteBase 改为 /hope/。

Nginx

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

index.php 式（linkmode=2） 若无效可改用：

location / {
    if (!-e $request_filename) {
        rewrite ^/(.*)$ /index.php/$1 last;
    }
}

IIS

需安装 URL Rewrite，将请求重写到 index.php。系统兼容 HTTP_X_REWRITE_URL。

生成链接（开发）

主题与插件应使用 SiteUrl，不要手写路径：

SiteUrl::post($gid);
SiteUrl::category($sid);
SiteUrl::tag($tagname);
SiteUrl::postPage();
SiteUrl::userCenter(['api' => 1]);
SiteUrl::plugin('video', ['vid' => 1]);
SiteUrl::login();
SiteUrl::register();

SiteUrl::plugin() 在伪静态下生成 /plugin/video?vid=1，在动态下生成 ?plugin=video&vid=1。

插件扩展伪静态

站点 已开启 linkmode 1 或 2 时，可注册独立 path 规则：

1. 新建 {插件名}_rewrite.php，实现注册函数
2. 入口中 hope_listen(HopeHooks::ROUTING_REGISTER, 'xxx_register_rewrite_routes')
3. 可选：提供 processor 回调，将路径参数写入 $_GET

hope_listen(HopeHooks::ROUTING_REGISTER, 'myplugin_register_routes');

function myplugin_register_routes($table, &$routes) {
    $linkmode = (string) Settings::get('linkmode');
    if ($linkmode !== '1' && $linkmode !== '2') {
        return;
    }

    $routes = array_merge([
        [
            'type'      => 'rewrite',
            'model'     => 'Plugin_Handler', // 以当前核心约定为准
            'method'    => 'loadPluginShow',
            'pattern'   => '/myplugin/{%id&type=num%}',
            'processor' => function ($params, $route) {
                $_GET['plugin'] = 'myplugin';
                $params['plugin'] = 'myplugin';
                return $params;
            },
        ],
    ], $routes);
}

路由项字段

Pattern 类型修饰：{%id&type=num%} 仅数字；{%slug&type=alnum%} 字母数字。

对照现成实现：content/plugin/video/video_rewrite.php（若存在）。

常见问题

开启伪静态后全部 404

• 检查是否重写到 index.php
• 子目录确认 RewriteBase / SITE_URL
• 确认 linkmode 为 1 或 2 且规则已保存

首页正常，文章/分类 404

• 检查 rule_article、rule_category 是否与服务器兼容
• 勿遗漏必要占位符；保存后「更新缓存」

插件伪静态不生效

• 站点 linkmode 必须为 1 或 2
• 确认 routing_register 已注册且插件已启用
• 更具体的 pattern 应用 array_merge($newRoutes, $routes) 插到表头

动态模式下用户中心 API

• ?user&api=1&action=profile
• 认证专用：/auth_api 或 ?auth_api
• 使用 SiteUrl::userCenter()、SiteUrl::authApi()，勿硬编码

相关文件

API 开发文档

Hope CMS 提供 REST 风格接口，通过 URL 参数 rest-api 指定方法名。响应均为 JSON。

相关：伪静态与路由 · 挂载点手册 · 插件开发指南

基础地址

http://www.hopecms.cn/?rest-api={方法名}

示例：

GET http://www.hopecms.cn/?rest-api=article_list&page=1&count=10

开关

除支付相关接口外，其余 API 需在后台开启 OpenAPI（Settings::get('is_openapi') !== 'n'），否则返回 api is closed。

支付接口（pay_notify、pay_create、pay_cashier、pay_status）不受此限制。

鉴权方式

需要鉴权的接口（如发文、上传）支持两种方式：

1. API Key 签名（服务端 / 第三方）

后台「设置 → API」获取 apikey，请求携带：

$req_time = time();
$req_nonce = bin2hex(random_bytes(16));
$apikey   = '你的apikey';
$req_sign = md5($req_time . $req_nonce . $apikey);

POST http://www.hopecms.cn/?rest-api=article_post&req_time=...&req_nonce=...&req_sign=...

缺少参数、签名错误或 nonce 重放时返回相应错误信息。

2. 登录 Cookie（浏览器端）

已登录用户携带站点认证 Cookie 时，可免 API Key，且 author_uid 可自动取当前用户。

响应格式

成功：

{ "code": 200, "msg": "ok", "data": { ... } }

失败：

{ "code": 0, "msg": "错误说明" }

认证失败：code 多为 401（以 JsonOut::authError 实际返回为准）。

文章接口

article_list — 文章列表

GET ?rest-api=article_list

返回 data.articles（含 id、title、cover、url、date、author_name、tags 等）。

article_detail — 文章详情

GET ?rest-api=article_detail&id=1

密码保护文章返回错误。成功返回 data.article。

article_post — 发布文章

POST ?rest-api=article_post

需鉴权。主要字段：title、content（必填），以及 excerpt、category_id、tags、cover、draft、alias、top、sortop、allow_remark、password、template 等。

article_update — 更新文章

POST ?rest-api=article_update

需鉴权。需传 id 及要更新的字段。

分类与微语

评论与用户

个人中心 API

前台个人中心通过 ?user&api=1（或伪静态 /user?api=1）调用，需登录 Cookie。POST 须携带页面输出的 token。

GET  http://www.hopecms.cn/?user&api=1&action=profile
POST http://www.hopecms.cn/?user&api=1
     Body: token=...&action=profile&nickname=...

业务实现位于 system/app/service/（如 UserHub / 用户中心模块）。主题可在 account/ 提供模板并对接前端 JS。

插件可通过 HopeHooks::USER_CENTER_API（hope_emit_once）扩展自定义 action。

媒体上传

POST ?rest-api=upload

需 API Key 鉴权。multipart/form-data 字段：file、可选 sid、author_uid。

成功返回 media_id、url、file_info。

支付接口

由 Pay_Handler 处理，不依赖 OpenAPI 开关：

网关密钥、回调 URL 在后台 支付设置 中配置。参数以 system/app/handler/pay_handler.php 及支付插件为准。

若后台开启 API 限流，超限请降低频率或调整限额。

调用示例（PHP）

$base = 'http://www.hopecms.cn/';
$req_time = time();
$req_nonce = bin2hex(random_bytes(16));
$apikey = 'your_apikey';
$sign = md5($req_time . $req_nonce . $apikey);

$url = $base . '?rest-api=article_list&page=1&count=5'
    . '&req_time=' . $req_time
    . '&req_nonce=' . $req_nonce
    . '&req_sign=' . $sign;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$body = curl_exec($ch);
curl_close($ch);

$data = json_decode($body, true);

扩展 API

优先通过插件扩展，避免直接改核心 Api_Handler：

1. 个人中心类：挂载 HopeHooks::USER_CENTER_API 接管自定义 action
2. 独立前台接口：插件 _show.php + 自建鉴权，或注册路由后由插件处理
3. 拦截 rest-api：在 init 钩子里识别方法名并 JsonOut::ok 后结束（注意与核心方法名冲突）

若维护私有分支必须改核心：在 Api_Handler 增加私有方法，方法名即 rest-api 值；需鉴权则调用 Handler 内鉴权方法。

实现入口：system/app/handler/api_handler.php。

联系我们

欢迎通过以下渠道获取帮助、反馈问题或参与社区交流。

联系方式

• 邮箱：cnxblog@qq.com
• QQ：271106735
• 用户社群：178900213 点击加入

官方渠道

如何反馈问题

提交问题时请尽量提供：

1. Hope CMS 版本（后台首页）
2. PHP / MySQL（或 MariaDB）版本
3. 当前主题与已启用插件
4. 复现步骤与报错信息（可附 content/cache/error.log 相关片段）

获取程序

• 前往 下载中心 获取最新安装包
• 请仅从 hopecms.cn / www.hopecms.cn 等官方域名下载

社区参与

• 在用户论坛发帖互助
• 分享自研主题与插件到应用中心
• 对照官方示例主题 default、示例插件 tips 提交改进建议

文档与参考

站内文档按「入门 → 开发基础 → 主题 → 插件 → 接口」组织；还可参阅：

• 目录说明
• 常见问题（含旧版兼容）

站内「主题生成器」可快速拼装主题 PHP 片段。

软件许可证

Hope CMS（希望CMS）核心代码按 Apache License 2.0 发布。部分捆绑的第三方库可能采用各自许可证，以其目录内说明为准。