Boardmix 无官方 PHP SDK，须直调 REST API；鉴权用 Bearer Token，Webhook 签名需 hash_hmac 验证；实时协作依赖 Webhook + 增量拉取，须幂等处理、校验 MIME 类型并防范路径遍历。
Boardmix 没有官方 PHP SDK，同步必须走 REST API
Boardmix 目前不提供 PHP 官方 SDK，所有集成都得直接调用其 https://api.boardmix.com/v1/ 接口。这意味着你无法用 composer require boardmix/sdk 一键接入，必须手动处理鉴权、请求构造、错误重试和 Webhook 签名验证。
常见错误是试图找现成封装库，结果踩进过期的第三方包（比如 GitHub 上标“Boardmix PHP”的仓库实际已停更两年，且签名逻辑与当前 v1 API 不兼容）。
- 必须使用 Bearer Token 鉴权，Token 从 Boardmix 后台「开发者设置 → 应用管理」中创建应用后获取，
client_secret永远不能硬编码在 PHP 脚本里 - 所有写操作（如创建白板、更新节点）需在请求头带
Authorization: Bearer <your_token> - Boardmix 的 Webhook 事件体是 JSON，但签名头为
X-Boardmix-Signature，值形如sha256=<hex_string>，PHP 验证时要用hash_hmac('sha256', $payload, $client_secret, true)再 base64 编码比对
实时协作靠 Webhook + 增量拉取，不是长连接或 SSE
Boardmix 不开放 WebSocket 或 Server-Sent Events 接口，所谓“实时”实为服务端主动推送变更事件到你指定的 HTTPS 回调地址。PHP 后端必须能稳定接收并快速响应（要求 3 秒内返回 2xx），否则 Boardmix 会重试 3 次后暂停推送。
典型场景：用户在 Boardmix 中拖动便签，触发 board.object.updated 事件；你的 PHP 接口收到后，应立即查 /v1/boards/{board_id}/objects?updated_after={last_timestamp} 拉取最新快照，而非直接信任 Webhook payload 中的字段（它只含变更摘要，不含完整数据）。
立即学习“PHP免费学习笔记（深入）”；
- Webhook 的
event_time是毫秒时间戳，PHP 用(int)($_SERVER['HTTP_X_BOARDMIX_EVENT_TIME'] ?? 0) / 1000转为秒级 UNIX 时间 - 增量拉取时，
updated_after参数必须用上一次成功处理的事件时间，不能用当前时间——否则会漏掉并发更新 - Boardmix 对同一 board 的 Webhook 推送是保序的，但不同 board 之间不保证顺序，PHP 侧需按
board_id+event_time做幂等去重（例如 Redis 键boardmix:seen:{board_id}:{event_time}）
PHP 处理 Boardmix 文件上传要绕过 $_FILES 直接读 raw body
Boardmix Webhook 中的附件（如图片、PDF）不会走 multipart/form-data，而是以 base64 字符串嵌在 JSON 的 attachment.data 字段里。PHP 默认的 $_FILES 完全用不上，硬套会导致空数组。
正确做法是用 file_get_contents('php://input') 读原始请求体，再 json_decode() 解析，最后对 $data->attachment->data 调用 base64_decode()。注意：Boardmix 的 base64 字符串不含 data:image/png;base64, 前缀，直接解就行。
- 大文件（>5MB）可能触发 PHP 的
post_max_size限制，但 Boardmix 实际限制是 10MB，建议将post_max_size和upload_max_filesize都设为12M - 解码后的二进制内容别直接
file_put_contents()，先用finfo_open(FILEINFO_MIME_TYPE)校验 MIME 类型，防止恶意构造的 base64 绕过 - Boardmix 传来的
attachment.filename可能含路径遍历字符（如../etc/passwd），务必用basename()截取干净文件名
调试 Webhook 签名失败？先检查 client_secret 是否被 URL 解码过
Boardmix 控制台生成的 client_secret 可能含 +、/、= 字符，在 PHP 中若经 urldecode() 或通过 GET 参数传递，会被错误转换（如 + 变空格），导致 hash_hmac 签名永远不匹配。
最稳妥方式是把 client_secret 存进环境变量（BOARDMIX_CLIENT_SECRET），用 getenv('BOARDMIX_CLIENT_SECRET') 读取，全程避免任何 URL 编解码环节。
- 验证签名时，payload 必须是未解析的原始 JSON 字节流（即
file_get_contents('php://input')结果），不能是json_encode($decoded)后的字符串——JSON 序列化会改变空格、换行、键序，破坏签名一致性 - Boardmix 的
X-Boardmix-Signature头值格式固定为sha256=xxx，提取 hex 部分用explode('=', $sig, 2)[1]即可，别用正则 - 本地测试 Webhook 可用
curl -X POST -H "X-Boardmix-Signature: sha256=..." -d @sample_event.json https://yoursite.com/webhook，但注意 sample_event.json 必须保存为 UTF-8 无 BOM 格式，否则签名计算偏差
/v1/boards/{id}/activities 来兜底。 
