README

Firebase集成于CodeIgniter 4

快速开始

1. 使用Composer安装: > composer require devinet/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);

描述

这是对"Kreait\Firebase"的CodeIgniter 4集成，即"PHP的官方Firebase Admin SDK"的非官方版本。

• 文档
• GitHub仓库

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

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

值得注意的是，您必须安装gRPC PHP扩展以及Service Account的凭证文件，该Service Account具有项目 -> 编辑或项目 -> 拥有者角色。

安装

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

composer require devinet/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);

默认情况下，新集合将创建一个指向顶层集合的CollectionReference，该集合与它的NAME常量匹配。或者，您可以直接传递一个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 获取实体的父实体，如果它来自子集合