内核与二次开发

给要改内核、做深度定制或参与贡献的人。YeCha 的设计取向是「少魔法、可读源码」:没有容器、没有编译步骤,请求从 index.php 进,一路是普通 PHP 函数调用。

本页导航

请求生命周期

浏览器 → Web 服务器伪静态 → index.php
  1. require config.inc.php + core/bootstrap.php(常量、自动加载、会话)
  2. Plugins::boot()            加载启用插件(注册钩子 / 页面 / 后台菜单)
  3. Router::resolve($path)     解析成 kind + 参数
  4. 页缓存命中判断(home/post/meta_list/… 可缓存)
  5. Front::home() / Front::post() / Front::metaList() …
     取数据 → Markdown::render() / Changelog::render() → 组装 $main / $side / $toc
  6. View 渲染主题 views/layout.php(含导航、侧栏、资源版本号)
  7. Hooks::run('front.shell', …) 外壳注入 → 输出 HTML

/admin/ 是独立的后台入口,结构相同但走 Auth 鉴权与 Csrf 校验。

目录与核心类

文件职责
index.php / admin/index.php前台 / 后台唯一入口与分发
core/Router.php路径解析、保留词、越界页码判定
core/Front.php首页、内容页、分类/标签/归档/搜索的数据与渲染组装
core/Db.phpPDO 封装、表前缀 ye_、预处理
core/View.php主题定位、模板回落、View::asset() 版本化
core/Markdown.phpMarkdown → HTML(转义优先、锚点、表格、围栏代码 data-lang)
core/Changelog.php/changelog 结构化时间线渲染器(1.2.5 起)
core/Nav.php导航单一数据源,顶部/页脚/下拉分组
core/Lang.php / core/Poly.php / core/ZhTw.php界面语言包、内容译文、繁简
core/Plugins.php / core/Hooks.php / core/Upgrade.php插件引导、动作总线、迁移执行
core/Cache.php文件缓存(pages / blocks)
core/Csrf.php / core/Auth.php / core/Uc.php表单令牌、鉴权、用户中心
core/Mail.php / core/Feed.php / core/Market.php邮件、RSS/sitemap、云市场
core/Str.php / core/helpers.php / core/version.php字符串、全局辅助函数、版本号

路由解析顺序

Router::resolve() 从上到下依次命中,先到先得:

  1. 空路径 → home(含 /page/N/ 页码)
  2. /healthz → 健康检查
  3. 语言段(仅 Poly::on() 且语言已启用时递归剥掉 /en/、/ja/…)
  4. /category/…、/tag/…、索引页、/archives/YYYY[/MM][/page/N]
  5. /search、/login、/register、/logout、/count、/feed、/sitemap.xml、/pages、/user/…
  6. 业务前缀 mall / site / ai(插件停用则回落 404)
  7. docs、changelog 干净 URL → 同名内容页
  8. /{slug}.html → 文章或页面
  9. 插件独立页 /{slug}[/...]
  10. 其余 404

Router::RESERVED 里的词不能被内容 slug 占用;越界页码与非法页码(page/0、page/abc)统一判 404,判据只在 Router::pageBeyond() 一处实现,避免重复内容页与自指 canonical。

数据库与索引

表用途
ye_contents文章 / 页面(type、status、slug、content_format、published_at、deleted_at…)
ye_poly_contents内容译文(group_id + lang + status + manual_override…)
ye_metas分类 / 标签(type、name、names_i18n、slug_i18n、count 预计算)
ye_relationships内容 ↔ 术语(content_id、meta_id)
ye_options站点选项(name / value / autoload)
ye_users / ye_comments用户、评论
ye_views / ye_attachments阅读量明细、附件
ye_migrations迁移执行历史

要点:

  • 所有前台列表都带 type='post' AND status='publish' AND deleted_at IS NULL;写新查询时照抄这个条件,别漏软删过滤。
  • count 是预计算列,术语列表/侧栏直接读;不要在列表页写 (SELECT COUNT(*) FROM ye_relationships …) 子查询(1.2.0 已从 xinglan、wenshu 主题清掉这种反模式)。
  • 首页文章总数走 Front::postsTotal():优先 ye_options.stats.posts_total(O(1))→ 缓存(3600s) → 现算(最后兜底)。
  • 深翻页(offset 很大)走 ye_meta_page_bounds 键序快路径;1.2.4 起繁体(tw)也接入该快路径,子集不足时安全回退旧路径。
  • 索引设计见 install/schema.sql 与 tools/optimize-indexes.php;改查询先用 EXPLAIN 看真实行数。

多语机制

  • 语言靠 URL 前缀(/en/…),不靠 cookie;Poly::on() / Poly::enabled() 决定是否解析。
  • 内容译文 Poly::row($baseId, $lang),术语名 Poly::termName($row, $lang),术语链接 Poly::termUrl();无译文回退基准语言。
  • 界面文案在 lang/zh_CN.php、lang/en_US.php 等语言包里,用 __('key') 取;新增键要各语言同时补。
  • 完整说明见多语言与 AI 翻译。

缓存

位置内容清理时机
var/cache/pages/全页缓存(home/post/meta_list/…)改内容、主题、菜单后
var/cache/blocks/侧栏与区块缓存改侧栏、插件后
var/home-static/首页烘焙件(含 /en/)改首页、主题、统计代码后

Cache::flush('pages') / Cache::flush('blocks') 是唯一入口;改数据后要主动清,否则会看到旧页。详见运维:缓存。

编码规范

  • PHP 8.1+,declare(strict_types=1);类文件放 core/,全局辅助函数放 helpers.php。
  • 服务端直出:页面主体内容必须在 HTML 源码里可见,JS 只做交互增强,不用客户端渲染主体列表/详情。
  • 所有输出过 e();SQL 一律预处理,表名走 Db::t();表单写操作带 Csrf::field() + Csrf::check()。
  • 密钥不进源码/仓库/日志;DEBUG=true 只在本机临时使用。
  • 改动前先 php -l,改完跑源站 curl 冒烟(首页、内容页、后台、sitemap、feed)。
  • 注意行尾:仓库里个别文件是 CRLF(如 plugins/market/showcase.php),批量补丁脚本不要整文件转 LF,否则会产生虚假大 diff。

调试与性能

php -l core/Front.php
php -r 'chdir("/www/wwwroot/yecha.org"); require "config.inc.php"; require "core/bootstrap.php"; Cache::flush("pages");'
curl -s -o /dev/null -w '%{http_code} %{time_total}s\n' -H 'Host: example.com' http://127.0.0.1/

排查顺序:instrument → measure → isolate → fix → re-measure。慢查询先看 EXPLAIN 与慢日志指纹,再从 SQL、PHP-FPM 并发、缓存命中次序、OPcache、页面资源体积与图片尺寸逐项隔离;详见运维:性能。

发版流程

YeCha 的更新日志有两份内容源,改版时都要动:

  1. 仓库根 CHANGELOG.md:面向开发者的完整记录(根因 / 修复 / 判据 / 验收 / 部署 / 回滚)。
  2. 线上 /changelog 是数据库内容页(ye_contents.slug=changelog),结构化时间线由 core/Changelog.php 渲染;英文译文在 ye_poly_contents。发布新版本要同步更新这两处(含英文)。
  3. core/version.php 的 YC_VERSION bump。
  4. 按仓库 RELEASE.md 五步走:更新日志检查 → 功能完全性检查 → 出包(git archive <tag>,注意 gzip 非确定性,验证要解压后比内容 SHA)→ GitHub 发布(tag + Release + tar 资产)→ 收尾验收。
  5. 清页缓存(/changelog 为 Cache-Control: no-cache,不需清 CDN)。

/changelog 的版本标题格式固定为 ## YYYY-MM-DD · YeCha <版本> · <标题>,首页「最新更新」区块也按这个格式解析,别随意改。