Photobooth源码解析（上）：PHP 8.4拍照亭Web应用的总体架构

Photobooth 是一个自托管（self-hosted）拍照亭 Web 应用，面向婚礼、派对等线下活动，核心能力包括实时取景（live preview）、照片拼贴（collage）、即拍即打（printing），运行在 Raspberry Pi、Debian 或 Windows 上，后端使用 PHP 8.4 编写。本文从源码视角拆解它的总体架构：目录布局、请求启动流程、配置系统、拍照数据流与服务分层，帮你在不写一行代码的情况下看懂整个项目。

1. 目录结构速览：先看全局再抠细节

仓库顶层按「Web 入口 / 业务代码 / 前端资源 / 文档」清晰地分成几块：

💡 小提示：data/与private/目录在仓库里并不存在，它们是首次请求时由启动脚本自动创建的，这也是阅读源码时容易困惑的地方之一。

2. 一次请求的完整旅程：从index.php说起

打开主页面时，index.php 做了四件事，这也是理解整个应用的最佳切入点：

1. 加载引导文件：第一行有效代码就是require_once 'lib/boot.php'，所有公共能力都在那里初始化；
2. 页面路由判断：若未跳过欢迎页则重定向到welcome/；若启用了绿幕模式（chromaCapture）则重定向到chroma/；
3. 登录/白名单校验：读取$config['login']与$config['protect']决定是否放行；
4. 拼装页面：依次 include template/components/ 下的main.head.php、preview.php、stage.start.php、gallery.php等片段，最后挂载 assets/js/core.js、preview.js等前端脚本。

这种「入口文件只做路由与拼装，业务全部下沉」的写法，让它即使没有前端框架也能保持低耦合。

3. 启动中枢lib/boot.php：安全加固 + 服务容器

lib/boot.php 是每次请求的必经之路，它承担了三重职责：

• 🔒安全加固：生成 CSRF Token 并提供checkCsrfOrFail()校验函数（所有写接口都靠它拦截跨站请求）；把会话文件强制移出 Web 根目录；设置X-Frame-Options、Referrer-Policy等安全响应头；
• 📂目录自举：通过 src/Enum/FolderEnum.php 枚举一次性创建data/images、data/tmp、private/fonts等 20 多个目录；
• 🧩全局单例容器：把 11 个核心服务（配置、日志、语言、打印、邮件、进程等）实例化后挂到$GLOBALS，之后任何地方都能用XXXService::getInstance()取到共享实例，例如：

$languageService = LanguageService::getInstance(); $languageService->translate('abort');

这种「全局单例」模式没有引入重型 DI 容器，对 PHP 8.4 的轻量部署场景非常务实。

4. 配置系统：Symfony Config 驱动的「一份树定义 + 用户增量文件」

Photobooth 没有用数据库存配置，而是采用「PHP 数组文件 + 配置树」方案，这是整个项目最有设计感的部分：

1. src/Configuration/PhotoboothConfiguration.php 用 SymfonyTreeBuilder定义了一棵巨大的配置树，30 多个 Section 类（如CollageConfiguration、PreviewConfiguration、PrintConfiguration）各自负责一块，目录见 src/Configuration/Section/；
2. 用户的实际修改只保存在config/my.config.inc.php一个文件里，src/Service/ConfigurationService.php 负责加载它并与默认值合并、迁移旧版本键名；
3. 保存配置时只写入与默认值不同的部分（diff），文件因此始终精简。

配置还直接驱动了多语言能力：翻译词条存放在resources/lang/下，src/Service/LanguageService.php 按section:key形式定位词条，后台面板的每个字段（如general:ui_language）都有对应的 i18n 标签，这也是它支持多语言 UI 的关键。

5. 拍照核心链路：api/capture.php→PhotoboothCapture

用户点击「拍照」后，前端 POST 到 api/capture.php，链路非常直白：

1. checkCsrfOrFail($_POST)校验令牌；
2. 根据style参数（photo / collage / chroma / video / custom）决定命名与子文件规则，例如拼贴会拆成xxx-1.jpg、xxx-2.jpg；
3. 构造 src/PhotoboothCapture.php 对象，按风格调用三种取图方式之一：
   • captureWithCmd()：执行可配置的外壳命令（如 gphoto2 拍单反、fswebcam 拍网络摄像头），并轮询等待文件落地；
   • captureCanvas()：接收浏览器 Canvas 上传的 base64 数据（自拍模式）；
   • captureDemo()：随机取resources/img/demo/下的示例图，让没有相机也能体验完整流程；
4. 成功后返回 JSON，前端拿到文件名后再调打印、下载、二维码等接口。

拼贴合成则由 src/Collage.php 完成：它读取 template/collage/ 下的 JSON 布局模板（landscape / portrait / community 三大类 30 余种），用 GD 把多张照片按坐标合成为一张图。

6.src/服务分层：没有框架，但分层清晰

项目没有使用 Laravel/Symfony 全家桶，src/按职责分了五层，读起来像「微缩版框架」：

依赖上，composer.json 只要求^8.4+ GD/mbstring 等扩展，第三方库集中在 QR 码、Flysystem（FTP/SFTP 远端同步）、Monolog（日志）、PHPMailer 这类「单点能力」包，整体非常克制。

7. 进程管理：PHP 应用如何托管 Node.js 服务

拍照亭常需要长驻进程（硬件按键服务、U 盘同步），但 PHP 是短生命周期模型。项目用 src/Service/ProcessService.php 优雅地解决了这个问题：

• 以node启动 assets/js/remotebuzzer-server.js（GPIO 按键/旋钮）与sync-to-drive.js（自动拷贝到 U 盘）；
• PID 文件写入var/run/，用pgrep探活并自动清理陈旧 PID；
• ProcessService::boot()在 index.php 末尾被调用，随主页访问自动拉起后台进程。

此外 src/HealthCheck.php 会在管理后台检查 PHP 版本与 gd、mbstring、xml、zip 扩展是否就绪，是排障时的第一站。

8. 小结：Photobooth 架构的三个关键词

• 自举：目录自动创建、配置树自动合并、后台进程自动拉起，首次部署几乎零配置；
• 分层：api/（接口）→src/Service（业务）→src/Utility（工具）→ 模板与 JS（表现），边界清晰；
• 克制：不用重量级框架，只用 Symfony 的 Config / Console / Asset 等单体组件，代码量可控、可移植到树莓派。

（下篇预告：深入api/接口层与前端core.js状态机，解析一次「拍照 → 拼贴 → 打印」的完整时序。）