README

Firebase集成于CodeIgniter 4

快速入门

1. 使用Composer安装: > composer require tatter/firebase
2. 编辑 .env 并添加Firebase凭证路径: GOOGLE_APPLICATION_CREDENTIALS = ../credentials/keyfile.json
3. 通过服务访问组件: $authentication = service('firebase')->auth;
4. 使用Firestore的Collection和Entity来建模数据: $widget = collection(WidgetCollection::class)->get($widgetId);

描述

这是CodeIgniter 4对“Kreait\Firebase”的集成，即“PHP的非官方Firebase Admin SDK”

• 文档
• GitHub仓库

它提供便利的服务和自定义Firestore类，以便在CodeIgniter 4中使用Firebase项目。请注意底层服务的需求

• kreait\firebase-php
• google\cloud-firestore

值得注意的是，您必须安装gRPC PHP扩展和凭证文件，以便访问具有项目 -> 编辑器或项目 -> 拥有者角色的服务帐户。

安装

通过Composer轻松安装，以利用CodeIgniter 4的自动加载功能，并始终保持最新状态

composer require tatter/firebase

或者，通过下载源文件并将目录添加到app/Config/Autoload.php来手动安装。

注意：截至2022年2月5日，此库完全支持PHP 8.1，但Google的Protobuf存在不兼容性（希望很快修复：protocolbuffers/protobuf#9293）。

凭证

您必须提供包含应用程序服务帐户凭证的密钥文件。通常的做法是将keyfile.json添加到您的项目中，并编辑.env以指定其路径（相对于public/）。

GOOGLE_APPLICATION_CREDENTIALS = ../keyfile.json

警告 确保您将密钥文件排除在任何仓库更新之外！

要从Firebase项目生成密钥文件

1. Firebase项目主页
2. 项目设置（齿轮图标）
3. 服务帐户
4. Firebase Admin SDK
5. 生成新的私有密钥

有关获取凭证的更多信息，请参阅Firestore快速入门指南

有关凭证指定的更多信息，请参阅SDK设置文档

用法

加载Firebase服务

$firebase = service('firebase');

服务将根据您的需求创建和缓存每个组件。通过它们的名称访问组件

$storage = $firebase->storage;
$bucket  = $storage->getBucket('my-bucket');

您还可以使用服务直接访问Kreait\Firebase\Factory的所有功能，例如如果您需要一个单独的组件实例

$shareClient = $firebase->auth;
$altClient   = $firebase->createAuth();

有关支持组件的列表，请参阅SDK文档。本撰写时可用

• 身份验证
• 数据库
• Firestore
• 消息传递
• 远程配置
• 存储
• 调用者

调用者

虽然Firebase SDK尚未官方支持，但此库包括一个用于Firebase可调用函数的组件。一个简单的示例展示了其所有功能

// Get the component
$caller = service('firebase')->caller;

// Set the UID of the user making the call
$caller->setUid($user->uid);

// Make the call
$data     = ['customerId' => 7, 'charge' => 3.50];
$response = $caller->call('https://us-central1-myproject.cloudfunctions.net/addCharge', $data);

if ($response === null) {
    echo implode(' ', $caller->getErrors());
}
else {
    print_r($response);
}

Firestore

本库通过 FirestoreClient 提供直接访问 Firestore 数据库的功能。使用辅助函数可以直接访问客户端的共享实例

helper('firestore');

$document = firestore()->collection('users')->document('lovelace');
$document->set([
    'first' => 'Ada',
    'last' => 'Lovelace',
    'born' => 1815
]);

printf('Added data to the "lovelace" document in the users collection.');

由于 SDK 和 Google 类已经代表了一个完整的数据库实现，因此不需要框架数据库层。您可以按照 Google 用户指南 直接与 Firestore 类进行交互。

集合

Collection 类受到框架中 Model 的启发，并处理了开发人员熟悉的大部分预处理和后处理。您只需要提供集合名称和要使用的实体类型即可

<?php

namespace App\Collections;

use App\Entities\Widget;
use Tatter\Firebase\Firestore\Collection;

final class WidgetCollection extends Collection
{
    public const NAME   = 'widgets';
    public const ENTITY = Widget::class;
}

实例化

您可以像创建 Model 一样创建您的集合实例。Firestore 辅助程序还包含一个辅助函数来创建和管理共享实例，就像框架中的 model() 辅助函数一样

$widgets = new WidgetCollection();
// OR
helper('firestore');
$widgets = collection(WidgetCollection::class);

默认情况下，新集合将创建一个与 NAME 常量匹配的顶层集合的 CollectionReference。或者，您可以直接传递一个 CollectionReference 以供其使用。使用 collection() 函数的第二个参数可以创建任何 Firestore\Entity 或 DocumentReference 的子集合

$user = collection(UserCollection::class)->get($userId);

$userWidgets = collection(WidgetCollection::class, $user);
foreach ($userWidgets->list() as $widget) {
    echo "{$user->name}: {$widget->name}";
}

方法

Collection 提供以下 CRUD 方法

• add(array|Entity $entity): Entity
• update(Entity $entity, array $data): Entity
• remove(Entity|string $entity): void
• get(DocumentReference|string $reference): ?Entity
• list($source = null): Traversable 详见下文

和支持方法

• fromSnapshot(DocumentSnapshot $snapshot): Entity
• fake(array array $overrides = []): Entity
• make(array array $overrides = []): Entity *与 fake() 相同，但会插入文档

此外，这些方法还可以访问底层 Firestore（子）集合的元数据

• collection(): CollectionReference
• parent(): ?DocumentReference
• id(): string
• name(): string
• path(): string

最后是一些类似 Model 的验证方法

• setValidation(ValidationInterface $validation): self
• skipValidation(bool $skip = true)
• validate(array $data, bool $cleanValidationRules = true): bool
• getValidationRules(array $options = []): array
• getErrors(): array

检索文档

您可以使用 Firestore 客户端直接返回快照，并使用 fromSnapshot() 将其转换为您的选择实体，但 Collection 还允许为 list() 指定一个覆盖状态。这可以是一个显式的 CollectionReference 或（更有帮助的）一个 Google\Cloud\Firestore\Query 实例，这打开了使用过滤器、排序和限制以及遍历集合组的可能性

// Using filters
$widgets = new WidgetCollection();
$query   = $widgets->collection()->where('color', '=', 'purple'); // returns Query
foreach ($widgets->list($query) as $widget) {
    echo $widget->weight;
}

// Grouped collections (traverses all collections and subcollections named "widgets")
$group = firestore()->collectionGroup('widgets');
foreach ($widgets->list($group) as $widget) {
    echo $widget->color;
}

为了让这更简单，Collection 将“传递”以下方法调用到底层集合

• endAt()、endBefore()、limit()、limitToLast()、offset()、orderBy()、select()、startAfter()、startAt()、where()

这允许进行更简单的方法链式调用

$result = $widgets->list($widgets->orderBy('color')->limit(5));

请注意，list() 总是返回一个 Traversable，因此文档仅在实际上需要时才被检索和转换为实体

实体

此库还附带自己的 Firestore Entity，它可以处理 Google 的日期时间转换，并提供以下方法来访问底层 Firestore 文档的元数据

• document(?DocumentReference $document = null): ?DocumentReference 获取或设置文档
• id(): string
• super(): ?DocumentReference 获取一个实体的父实体，如果它来自子集合