php-fcm 是轻量级直连 fcm http api 的 php 客户端，无需 firebase admin sdk，适合仅需推送通知的场景；支持 legacy server key 或 v1 access token 认证，要求 php ≥ 7.4、ext-curl 和 ext-json，需显式设置 timeout 防卡死。
php-fcm 是一个轻量、直连 HTTP API 的 FCM 客户端库，不依赖 Firebase Admin SDK，适合只需要发通知、不涉及用户认证或数据库操作的场景。它用起来快，但得自己处理 token 刷新、错误重试和响应解析。
为什么不是直接用 kreait/firebase-php？
很多项目默认搜到 kreait/firebase-php，但它本质是 Firebase Admin SDK 的 PHP 封装，要求你提供完整的 serviceAccountKey.json 文件，并启用 Google Cloud 的 IAM 权限。如果你只是想快速发几条推送，又没开 Google Cloud 项目或不想暴露私钥，php-fcm 更合适——它只认 FCM 的 legacy server key 或 v1 access token（后者需 OAuth2 流程）。
安装 php-fcm 并确认最低依赖
运行这条命令即可：
composer require paragraph1/php-fcm
注意三点：
-
php-fcm要求 PHP ≥ 7.4，且必须启用ext-curl和ext-json - 它底层用
GuzzleHttp/psr7处理请求，Composer 会自动拉取兼容版本（通常为^2.6），不用手动指定 - 别装错包名：
paragraph1/php-fcm≠sngrl/php-firebase-cloud-messaging（后者已多年未维护，HTTP client 有已知 timeout bug）
初始化客户端时最容易漏掉的配置项
你不能只传一个 key 就完事。php-fcm 支持两种认证方式，选错会导致 401 Unauthorized：
- Legacy 模式（最常用）：用 Firebase 控制台「云消息传递」页里复制的
Server key，初始化时传['server_key' => 'your-server-key-here'] - v1 模式（推荐新项目）：需先用 service account 获取 access token，再传
['access_token' => 'ya29.c.xxx']；token 有效期 1 小时，得自己缓存+刷新 - 无论哪种，都必须显式设置
['timeout' => 10]，否则默认 0（无限等待），网络抖动时 PHP 进程会卡死
示例：
$fcm = new \Fcm\FcmClient([
'server_key' => 'AAAAxxx...xxx',
'timeout' => 10,
]);
发送单设备通知时，token 和 data 的边界要划清
FCM 的 notification 字段控制前台展示（用户看到的标题/内容），data 字段才是后台静默接收的键值对。很多人把业务参数塞进 notification 导致收不到：
- Android/iOS App 只在应用前台时才显示
notification；后台或杀死状态，只有data会被系统转发到 App -
data里不能含保留字段如click_action、sound，否则整个 payload 被拒绝（错误码mismatched_sender_id常因此触发） - 总 payload 不超过 4KB，
data+notification加起来超了，FCM 会静默截断，不报错也不返回 warning
正确写法：
$payload = [
'to' => 'cZx...xxx:APA91b...',
'notification' => [
'title' => '订单已支付',
'body' => '订单 #123456 已完成支付',
'sound' => 'default',
],
'data' => [
'order_id' => '123456',
'status' => 'paid',
'page_type' => '2', // 你自定义的跳转标识
],
];
Firebase 的 token 有效期、设备离线重试策略、以及 Android 12+ 对 background message 的限制，这些不在库层面解决——php-fcm 只管发出去，剩下的得你自己补逻辑。php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
