简介

本开发文档面向 DouPHP 内容管理系统的开发者，围绕文章、案例、课程、下载、图库、视频等核心内容模块，系统阐述其数据模型、分类体系、标签与 SEO、发布流程、审核机制、版本控制、检索优化与缓存策略。文档提供从架构到代码级的可视化说明，并给出扩展字段、富文本集成、自定义内容类型与 API 集成的最佳实践。

最新更新：show模块文本处理逻辑已重构，移除了正则表达式匹配，改用更高效的str_replace方法处理换行符标准化，显著提升了多平台兼容性和处理性能。

项目结构

DouPHP 采用"多入口 + 模块化"的架构：

• 根入口负责引导、环境检测、配置加载、自动加载与容器初始化。
• 三端分离：admin（后台）、front（前台）、api（接口），各自具备路由、控制器、服务、模型与视图。
• 模块按功能划分，如 article、course、download、gallery、cases、video、show 等，统一通过 module.php 注册为列式或单页模块。

graph TB
A["根入口 index.php"] --> B["引导 bootstrap.php"]
B --> C["配置 config/config.php"]
B --> D["模块注册 config/module.php"]
B --> E["自动加载与别名"]
E --> F["DI 容器"]
F --> G["路由调度器"]
G --> H["admin 后台"]
G --> I["front 前台"]
G --> J["api 接口"]

图表来源

• bootstrap.php:15-180
• config.php:15-53
• module.php:1-132

章节来源

• bootstrap.php:15-180
• config.php:15-53
• module.php:1-132

核心组件

• 内容模型层：以 Article 为例，前后端分别定义 Model，使用 traits 实现列表字段派生、URL 生成、分类关联、归档筛选、默认排序等能力。
• 业务服务层：ArticleService 在后台负责列表构建、新增/更新/删除/批量操作；在前台负责列表与详情数据组装、Markdown 渲染、访问统计。
• 路由与控制器：前端控制器调用 Service 完成数据准备，结合模板渲染页面；课程模块示例展示了分类信息构建、SEO 标题/关键词/描述注入与详情页 Schema 输出。
• 附件与富文本：支持远程图片本地化、草稿图片暂存、主图上传、内容图片存储与清理。
• 审计与日志：后台操作写入审计日志，便于追踪变更。
• 文本处理优化：show模块实现了高效的换行符标准化处理，使用str_replace替代正则表达式，提升多平台兼容性。

章节来源

• Article 模型（前台）:32-178
• Article 模型（后台）:28-123
• ArticleService（前台）:27-151
• ArticleService（后台）:33-314
• CourseController（课程控制器）:96-245

架构总览

内容管理的典型请求流：

• 后台编辑：表单提交 → 控制器 → 服务层校验与处理 → 模型持久化 → 附件处理 → 审计日志 → 返回结果。
• 前台展示：路由解析 → 控制器 → 服务层查询与格式化 → 模板渲染 → SEO 元数据输出。

sequenceDiagram
participant U as "管理员"
participant AC as "后台控制器"
participant AS as "后台服务 ArticleService"
participant M as "模型 Article"
participant ATT as "附件服务"
participant AUD as "审计日志"
U->>AC : "提交新增/编辑表单"
AC->>AS : "insert/update(data, adminId)"
AS->>ATT : "处理正文图片/主图"
ATT-->>AS : "返回附件编号/URL"
AS->>M : "create/fill+save"
M-->>AS : "持久化成功"
AS->>AUD : "记录操作日志"
AUD-->>AC : "完成"
AC-->>U : "返回结果/跳转"

图表来源

• ArticleService（后台）:129-243
• Article 模型（后台）:68-123

详细组件分析

文章模块（Article）

• 数据模型
  • 前台模型：启用 translatable 对 title/content/description/keywords 进行当前语言覆写；appends 提供 url、时间短格式、分类信息等 Presenter 字段；prefetchers 批量预热 URL、多语言与附件；scopePublished 仅返回已发布内容；scopeFilterByArchive 支持年/月归档筛选；scopeApplyDefaultOrder 默认排序。
  • 后台模型：fillable 白名单限制可批量写入字段；casts 格式化 image、created_at、status；scopeFilterByKeyword 支持标题模糊搜索；scopeApplyDefaultOrder 根据配置决定是否启用 sort 排序。
• 业务服务
  • 后台服务：buildArticleListData 分页查询并补齐模板字段；insert/update 处理 XSS、远程图片本地化、主图上传、草稿图片认领、审计日志；delete 二次确认与批量删除/转移分类；action 支持批量操作。
  • 前台服务：buildArticleListData 构建列表数据并计算分页；buildArticleShowData 获取详情并 Markdown 渲染；findCategoryById 取分类信息；recordArticleView 点击量自增。
• 分类与 SEO
  • 分类关联：category() 关联 article_category，用于列表与详情展示。
  • SEO：控制器通过 seo->pageTitle/keywords/description 注入页面头信息；详情页可输出结构化数据 schema。
• 富文本与附件
  • 正文内容经 xss()->content 过滤；支持 content_remote_image_local 将远程图片转存至本地；主图通过 attachment()->store 上传并回写 image 字段。

classDiagram
class Article_Front {
+table "article"
+casts
+appends
+translatable
+prefetchers
+moduleSchema()
+category()
+findPublishedById(id)
+scopePublished(query)
+scopeFilterByArchive(query, archive)
+scopeImageNotEmpty(query)
+scopeApplyDefaultOrder(query)
}
class Article_Admin {
+table "article"
+fillable
+casts
+prefetchers
+category()
+scopeFilterByKeyword(query, keyword)
+scopeApplyDefaultOrder(query)
}
class ArticleService_Front {
+buildArticleListData(catId, page, pageSize, archive)
+buildArticleShowData(id)
+findCategoryById(catId)
+recordArticleView(id)
}
class ArticleService_Admin {
+buildArticleListData(catId, keyword, page)
+buildArticleDefaultData()
+insert(data, draftToken, adminId)
+buildArticleEditData(id)
+update(data, adminId)
+delete(id, data)
+action(data)
}
Article_Front --> ArticleService_Front : "被调用"
Article_Admin --> ArticleService_Admin : "被调用"

图表来源

• Article 模型（前台）:32-178
• Article 模型（后台）:28-123
• ArticleService（前台）:27-151
• ArticleService（后台）:33-314

章节来源

• Article 模型（前台）:32-178
• Article 模型（后台）:28-123
• ArticleService（前台）:27-151
• ArticleService（后台）:33-314

课程模块（Course）

• 控制器职责：构建分类信息、SEO 元数据、面包屑导航、详情页结构化数据 schema，并渲染课程列表与详情模板。
• 列表与详情：支持分页、归档筛选、点击量统计、相关课程推荐。

sequenceDiagram
participant C as "CourseController"
participant S as "CourseService"
participant V as "视图模板"
C->>S : "buildCourseListData(catId, page, pageSize, archive)"
S-->>C : "课程列表与分页"
C->>C : "构建分类信息与SEO"
C->>V : "渲染 course_category.dwt"
Note over C,V : "详情页流程类似，包含点击统计与schema输出"

图表来源

• CourseController（课程控制器）:96-245

章节来源

• CourseController（课程控制器）:96-245

幻灯模块（Show）- 文本处理优化

最新更新：show模块的文本处理逻辑已重构，移除了正则表达式匹配，改用更高效的str_replace方法处理换行符标准化。

• 数据模型
  • 后台模型：支持多语言翻译（name、link、image、text字段），使用translatable特性；prefetchers预加载附件和语言数据；listByType方法按终端类型查询幻灯记录。
  • 前台模型：提供scopeForType作用域过滤、scopeOrderBySort默认排序；showList静态方法返回成品数组。
• 文本处理优化
  • 核心改进：使用str_replace(array("\r\n", "\r"), "\n", $text)替代正则表达式进行换行符标准化
  • 性能提升：str_replace比preg_replace执行效率更高，特别是在处理大量文本时
  • 兼容性增强：统一处理Windows（\r\n）、Unix（\n）、Mac（\r）等不同平台的换行符
  • 一致性保证：确保所有文本内容在分割前都转换为统一的\n格式
• 业务服务
  • 后台服务：buildShowListData方法中实现文本标准化处理，将text字段转换为text_array数组以便前端展示
  • 完整CRUD：支持insert、update、delete操作，包含附件处理和审计日志记录
• 控制器与视图
  • ShowController提供完整的RESTful接口，支持列表、创建、编辑、删除操作
  • 模板文件show.htm展示幻灯列表和编辑表单

flowchart TD
A["原始文本输入"] --> B{"检测换行符类型"}
B --> |Windows \\r\\n| C["str_replace替换为\\n"]
B --> |Unix \\n| D["保持不变"]
B --> |Mac \\r| E["str_replace替换为\\n"]
C --> F["统一\\n格式"]
D --> F
E --> F
F --> G["explode按\\n分割"]
G --> H["text_array数组"]
style C fill:#e1f5fe
style E fill:#e1f5fe
style F fill:#c8e6c9
style G fill:#fff3e0

图表来源

• ShowService（后台）:50-54
• Show 模型（后台）:98-102
• Show 模型（前台）:99-103

章节来源

• ShowService（后台）:41-69
• Show 模型（后台）:71-115
• Show 模型（前台）:87-116
• ShowController（幻灯控制器）:61-168

其他内容类型概览

• 案例（cases）、下载（download）、图库（gallery）、视频（video）、幻灯（show）等同属 column_module 内容类型，遵循统一的模块注册与前后端分层模式。
• 建议参照 Article 的实现方式，为各类型建立：
  • 前后端 Model：定义 casts、appends、translatable、prefetchers、scope 筛选与排序。
  • 前后端 Service：封装列表/详情构建、附件处理、统计与导出。
  • 控制器：负责路由、参数校验、SEO 注入与模板渲染。

章节来源

• module.php:1-132

依赖关系分析

• 模块注册：module.php 声明 column_module 与 single_module，决定哪些模块作为列式内容（如 article、course、download、gallery、cases、video、show）参与前台展示与菜单。
• 引导与容器：bootstrap.php 加载配置、注册自动加载、别名、DI 容器、路由调度器与 Request 单例，确保三端在 boot 前可用。
• 配置项：config.php 定义数据库连接、表前缀、字符集、应用密钥与调试开关。

graph LR
M["module.php"] --> R["路由/菜单/展示"]
B["bootstrap.php"] --> C["容器/路由/Request"]
C --> A["admin 后台"]
C --> F["front 前台"]
C --> API["api 接口"]
CFG["config.php"] --> B

图表来源

• module.php:1-132
• bootstrap.php:15-180
• config.php:15-53

章节来源

• module.php:1-132
• bootstrap.php:15-180
• config.php:15-53

性能考虑

• 列表查询优化
  • 使用 with('category') 预加载分类，避免 N+1 查询。
  • field 指定所需字段，减少数据传输。
  • 使用 paginate 分页，控制每页条数。
• 附件与图片
  • 远程图片本地化减少外部依赖与跨域问题。
  • 草稿图片暂存与认领，提升编辑体验与稳定性。
• 内容渲染
  • MarkdownRenderer 在服务层集中处理，避免重复转换。
• 文本处理优化
  • show模块改进：使用str_replace替代正则表达式进行换行符标准化，显著提升处理性能
  • 多平台兼容性：统一处理不同操作系统的换行符差异，确保内容一致性
  • 内存效率：减少正则表达式编译开销，降低内存占用
• 缓存策略（建议）
  • 分类树、站点配置、SEO 元数据可使用缓存层（如 Redis/Memcached）缓存热点数据。
  • 列表页可按分类与归档维度设置短期缓存，配合失效策略保证一致性。
• 索引与搜索
  • 为常用筛选字段（category_id、created_at、title）建立数据库索引。
  • 全文检索建议使用搜索引擎（如 Elasticsearch）或数据库全文索引，结合分词与权重优化。

故障排查指南

• 常见错误定位
  • 非法参数：服务层抛出 DomainException，检查传入 id、adminId、draftToken 是否合法。
  • 记录不存在：删除/更新时先查询目标记录，不存在则返回错误并重定向。
  • 附件上传失败：检查 UploadedFile 与 AttachmentUploadOptions 配置，确认存储路径与权限。
• 审计日志
  • 后台操作均记录审计日志，可通过日志查看变更历史与责任人。
• 富文本与 XSS
  • 正文内容经 xss()->content 过滤，若出现样式丢失或脚本被拦截，检查过滤器规则与白名单。
• 文本处理问题
  • 换行符显示异常：检查文本标准化处理是否正确执行，确认str_replace方法正常工作
  • 多平台兼容性问题：验证不同操作系统下的换行符处理是否符合预期
  • 性能问题：如发现文本处理缓慢，确认是否仍在使用正则表达式而非str_replace

章节来源

• ArticleService（后台）:129-314

结论

DouPHP 的内容管理系统以清晰的三层架构（Model/Service/Controller）与模块化设计为基础，提供了文章、课程、下载、图库、案例、视频、幻灯等内容的完整 CRUD、分类体系、SEO 与附件处理能力。最新的show模块文本处理优化进一步提升了系统的性能和多平台兼容性，通过移除正则表达式匹配并使用更高效的str_replace方法，显著改善了换行符标准化处理的性能表现。通过统一的服务层封装与模型 traits，开发者可以快速扩展新的内容类型，复用列表/详情构建、附件处理、审计日志与 SEO 能力。建议在生产环境中结合缓存与搜索引擎进一步优化检索与展示性能。

附录：API 参考与最佳实践

内容类型与模块注册

• 列式内容模块：product、article、doc、professional、solution、support、course、download、gallery、cases、video、show。
• 单页内容模块：ai、chat、distribution、data、order、user、service、aftersale、health、box、fragment、language、vip、point、money、withdraw、share、attribute、comment、certificate、plugin、favorites、coupon、job、faq、work、area、sn、form、vote、consultation、link、store、onepic、email、weixin、partner、dh、landing、equipment、guestbook、team、tag、brand、sms。

章节来源

• module.php:1-132

内容发布流程（后台）

• 新增/编辑：表单提交 → 服务层校验与处理 → 附件上传/远程图片本地化 → 模型持久化 → 审计日志 → 返回结果。
• 删除：二次确认 → 实际删除 → 审计日志。
• 批量操作：批量删除/转移分类。

章节来源

• ArticleService（后台）:129-314

内容展示流程（前台）

• 列表：分页查询 → 预加载分类 → 格式化 Presenter 字段 → 模板渲染。
• 详情：查找已发布记录 → Markdown 渲染 → SEO 元数据 → 结构化数据 schema → 模板渲染。

章节来源

• ArticleService（前台）:27-151
• CourseController（课程控制器）:96-245

分类体系与标签

• 分类：通过 category() 关联分类模型，支持分类筛选与面包屑导航。
• 标签：可在定义的扩展字段中维护标签集合，或使用 tag 模块统一管理。

章节来源

• Article 模型（前台）:106-114
• Article 模型（后台）:83-91

SEO 优化

• 页面标题/关键词/描述：由控制器通过 seo->pageTitle/keywords/description 注入。
• 结构化数据：详情页输出 schema，提升搜索引擎理解与展示效果。

章节来源

• CourseController（课程控制器）:125-219

富文本编辑器集成

• 正文内容经 xss()->content 过滤，支持远程图片本地化与草稿图片暂存。
• MarkdownRenderer 在服务层集中渲染，保证一致性与性能。

章节来源

• ArticleService（后台）:141-173
• ArticleService（前台）:108-125

文本处理最佳实践

• 换行符标准化：使用str_replace(array("\r\n", "\r"), "\n", $text)统一处理不同平台的换行符
• 性能优化：优先使用str_replace而非preg_replace进行简单字符串替换
• 兼容性保证：确保文本在处理前进行标准化，避免平台差异导致的问题
• 数组分割：标准化后使用explode('\n', $text)安全分割文本

章节来源

• ShowService（后台）:50-54
• Show 模型（后台）:98-102
• Show 模型（前台）:99-103

检索与搜索优化

• 基础筛选：标题关键字、分类、归档时间窗。
• 高级检索：建议引入搜索引擎，结合分词、权重与高亮显示。

章节来源

• Article 模型（后台）:93-108
• Article 模型（前台）:138-154

缓存策略（建议）

• 分类树、站点配置、SEO 元数据缓存。
• 列表页按分类与归档维度短期缓存，配合失效策略。

自定义内容类型与扩展字段

• 步骤建议：
  • 在 module.php 注册新模块。
  • 创建前后端 Model，定义 casts、appends、translatable、prefetchers、scope。
  • 创建前后端 Service，封装列表/详情构建、附件处理、统计与导出。
  • 创建控制器与路由，注入 SEO 元数据与模板渲染。
  • 如需扩展字段，可在 defined 配置或独立表中维护，并在 Model 中映射。

章节来源

• module.php:1-132
• Article 模型（前台）:75-94
• Article 模型（后台）:58-81

版本控制与审核机制（建议）

• 版本控制：可在内容表增加 version 字段，或在独立版本表中记录每次变更，支持回滚与对比。
• 审核机制：利用 status 字段区分草稿/待审/已发布，结合工作流服务实现多级审核。