kreait firebase-php 是一个功能完善的 PHP 版 Firebase SDK，封装了 Authentication、Realtime Database、Firestore、Cloud Messaging、Remote Config 和 Cloud Storage 等多个服务的调用接口。相比直接请求 Firebase 的 REST 接口，使用这个库可以让 PHP 代码更简洁，类型提示更友好，异常处理也更规范。本文将从环境准备、初始化配置开始，逐步演示各个服务模块的典型用法，并分享一些容易踩坑的细节。
安装与初始化配置
kreait firebase-php 对 PHP 版本有一定要求，建议使用 PHP 8.0 及以上版本，低于这个版本时只能安装旧版的发布包，功能会有缺失。安装方式首选 Composer，直接执行下面的命令即可拉取最新版本：
composer require kreait/firebase-php
安装完成后，接下来要解决的是身份认证问题。Firebase 的服务端 SDK 不支持简单的 API Key 认证，必须使用服务账号凭据。登录 Firebase 控制台后，进入项目设置中的服务账号页面，点击生成新的私钥，会下载一个 JSON 格式的凭据文件。这个文件包含了客户端邮箱、私钥等敏感信息，务必妥善保管，不要提交到代码仓库。
拿到凭据文件后，通过 Factory 类创建 Firebase 实例。推荐将凭据文件路径放在环境变量中，代码只在运行时读取，这样开发环境和生产环境可以使用不同的凭据而无需改动代码。
use Kreait\Firebase\Factory;
use Kreait\Firebase\ServiceAccount;
$factory = (new Factory)
->withServiceAccount(__DIR__ . '/config/firebase-credentials.json')
->withDatabaseUri('https://your-project.firebaseio.com');
$firebase = $factory->create();
$database = $firebase->createDatabase();如果在创建实例时抛出凭据解析异常，多半是 JSON 文件内容被改动过或者路径不对。可以先用 json_decode 手动解析一遍文件内容，确认格式无误后再排查其他原因。
数据库与身份认证的常用操作
Realtime Database 的读写是使用频率最高的部分。拿到 $database 实例后，可以像操作数组一样对任意路径进行读写。读取时用 getReference 定位到具体节点，写入时则区分 set、update 和 push 三种语义，分别对应覆盖写入、部分更新和追加新记录。
// 写入数据
$database->getReference('users/1001')->set([
'name' => '张三',
'email' => 'zhangsan@ipipp.com',
'role' => 'admin'
]);
// 读取单个节点
$snapshot = $database->getReference('users/1001')->getSnapshot();
$user = $snapshot->getValue();
// 追加记录，自动生成唯一键
$newRef = $database->getReference('logs')->push([
'action' => 'login',
'time' => time()
]);查询方面，SDK 提供了链式调用的过滤器，支持按某个子键排序后限制返回条数。例如要取出最新注册的十个用户，可以先按 createdAt 排序再截取末尾十条。
$users = $database->getReference('users')
->orderByChild('createdAt')
->limitToLast(10)
->getValue();身份认证模块同样重要，尤其是需要在服务端创建用户、验证自定义令牌的场景。createAuth 返回的 Auth 对象可以完成用户增删改查、修改密码、设置自定义声明等操作。下面的例子演示了创建用户并为其打上角色标签：
$auth = $firebase->createAuth();
$user = $auth->createUser([
'email' => 'lisi@ipipp.com',
'password' => 'secret-pass-123',
'displayName' => '李四'
]);
// 设置自定义声明，客户端验证令牌时可以读到
$auth->setCustomUserClaims($user->uid, ['role' => 'editor']);需要注意的一点是，Auth 相关操作有配额限制，频繁调用可能触发限流。如果业务上需要批量导入用户，SDK 提供了批量接口，比循环调用单个创建的效率高很多，也能减少配额消耗。
错误处理与生产环境建议
SDK 的所有异常都继承自 Kreait\Firebase\Exception\FirebaseException，但在实际编码中更推荐捕获各个模块的具体异常类型，这样能准确区分是网络问题、权限问题还是数据格式问题。例如认证模块抛出的 EmailNotFound、数据库模块抛出的 PermissionDenied，含义完全不同，处理方式也不一样。
use Kreait\Firebase\Exception\Auth\EmailNotFound;
use Kreait\Firebase\Exception\AuthException;
try {
$auth->getUserByEmail('someone@ipipp.com');
} catch (EmailNotFound $e) {
echo '用户不存在';
} catch (AuthException $e) {
echo '认证服务异常：' . $e->getMessage();
}部署到生产环境时有几个细节值得留意。首先是凭据管理，不要把 JSON 文件放在 Web 根目录下，可以通过环境变量 GOOGLE_APPLICATION_CREDENTIALS 指向文件路径，SDK 会自动识别。其次是数据库规则，Realtime Database 默认的测试规则允许任何人读写，上线前务必在控制台改成正式的权限规则，否则数据会裸奔。
另外，如果 PHP 应用部署在内网或需要走代理访问 Google 接口，可以在创建 Factory 时通过 withHttpClient 注入自定义的 Guzzle 客户端，配置代理参数即可。对于高并发场景，建议复用 Factory 创建的实例，把 Firebase 对象注册到容器中作为单例使用，避免每次请求都重新解析凭据文件带来的开销。
整体来看，kreait firebase-php 的 API 设计比较贴合 PHP 开发者的习惯，文档也提供了大量可运行的示例。只要把凭据配置和权限规则这两块处理好，接入 Firebase 的各项服务基本不会遇到太大障碍。官方文档中还包含 Cloud Messaging 推送、Firestore 文档操作等更深入的示例，有需要的读者可以进一步查阅。
修改时间：2026-09-16 23:22:52