损坏的/firebase

Firebase集成于CodeIgniter 4

v2.0.0-rc.2 2022-04-02 00:20 UTC

README

Firebase集成于CodeIgniter 4

Coverage Status

快速入门

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

描述

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

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

值得注意的是,您必须安装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\EntityDocumentReference 的子集合

$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 获取一个实体的父实体,如果它来自子集合