README

此包通过使用原始 Laravel API，为 Google Firestore 的 Eloquent 模型和查询构建器添加功能。

安装

您可以通过 composer 安装此包

composer require pruvo/laravel-firestore-connection

配置

您可以将 Firestore 作为主数据库或副数据库使用。为此，请向 config/database.php 添加新的 Firebase 连接

'firestore' => [
    'driver' => 'firestore',
    'database' => \Google\Cloud\Firestore\FirestoreClient::DEFAULT_DATABASE,
    'prefix' => '',

    // The project ID from the Google Developer's Console.
    'projectId' => env('GOOGLE_CLOUD_PROJECT'),

    // The full path to your service account credentials .json file 
    // retrieved from the Google Developers Console.
    'keyFilePath' => env('GOOGLE_APPLICATION_CREDENTIALS'),

    // A hostname and port to emulator service.
    // 'emulatorHost'=> env('FIRESTORE_EMULATOR_HOST', 'localhost:8900'),
],

Eloquent

扩展基本模型

此包包含一个启用 Firestore 的 Eloquent 类，您可以使用它来定义对应集合的模型。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Pruvo\LaravelFirestoreConnection\Firestoreable;

class Book extends Model
{
    use HasFactory;
    use Firestoreable;

    public $connection = 'firestore';
    public $table = 'books';
    public $primaryKey = 'id';
    public $keyType = 'string';
    public $perPage = 10;
}

限制

Laravel 是一个最初设计用于使用 SQL 数据库进行 ORM 的框架。然而，Firestore 是一个 NoSQL 数据库，因此它不支持与 SQL 数据库相同的特性。

从您习惯的 SQL 数据库的角度来看，以下特性不受支持

SQL 语法

没有方法可以使用字符串（如 SQL 语法）查询 Firestore 数据库。所有查询都必须通过 Firestore SDK 完成。

仅支持 AND 操作符

• SQL 数据库支持 select * from users where status = 'disabled' or age > 18; 但 Firestore 上不支持。

不支持等于 null

• 但是有一个解决方案：orderBy('field', 'ASC')>startAt(null)。

模型不支持关系，因为不可能跨集合数据，因此

• 您不能使用 belongsTo、hasOne、hasMany、morphOne、morphMany、belongsToMany 或 morphToMany;
• 相比之下，Firestore 有子集合，因此您可以使用 hasSubcollection 来定义关系。

模型 ID 行为

• Firestore 不支持数字自增。为了保持记录的可排序性，它使用 Str::orderedUuid();。
• Firestore 是一个文档数据库，因此主键是文档名称。
• 如果启用了自动增量，并且您想设置自定义 UUID，您必须在保存模型之前强制填充 __name__ 属性。

$user = User::newModelInstance([
    'name' => 'Jhon Joe',
    'email' => 'jhon.joe@example.com',
    'password'=> bcrypt('123456'),
]);
$user->forceFill(['__name__' => '00000000-0000-0000-0000-000000000000'])->save();

Firestore 数据库类型

• 避免使用 reference 类型，因为它不能序列化，也没有优势。相反，使用文档引用路径（DocumentReference 的字符串表示）。
• 除非需要，否则请避免使用 map 和 array 类型。其中 map 等同于关联数组，而 array 等同于顺序数组。
• 日期属性 默认存储为字符串。要将它们存储为时间戳（Firestore 的原生类型），您必须
  • 设置 DateTimeInterface 的实例作为值；Carbon 扩展 DateTimeInterface 并且可以安全使用；
  • 在模型上使用 Pruvo\LaravelFirestoreConnection\Casts\AsCarbon 转换；

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Pruvo\LaravelFirestoreConnection\Casts\AsCarbon;
use Pruvo\LaravelFirestoreConnection\Firestoreable;

class Book extends Model
{
    use HasFactory;
    use Firestoreable;

    public $connection = 'firestore';
    public $table = 'books';
    public $primaryKey = 'id';
    public $keyType = 'string';
    public $perPage = 10;

    protected $casts = [
        'created_at' => AsCarbon::class,
        'updated_at' => AsCarbon::class,
    ];
}

复杂查询

• 强烈建议使用 Laravel Scout 与 pruvo/laravel-firestore-connection 一起使用。
• Laravel Scout 通过使用 whereIn 检索结果 ID。Firestore 每个请求支持最多 10 个 ID。因此，每页分页 10 个。
• Firebase 有一个扩展，可以导出和同步所有数据到 Google BigQuery。BigQuery 类似于 SQL，因此您可以在那里进行数据交叉和构建 BI 仪表板。

Firestore 特定操作符

Firestore 不支持所有类似 SQL 的操作符，并有一些特定操作符。查看完整列表。

查询构建器

DB::table('posts')->where('tags', 'array-contains-any', ['cat', 'dog'])->get();
// or
DB::table('posts')->whereArrayContainsAny('tags', ['cat', 'dog'])->get();

Eloquent 构建器

Post::where('tags', 'array-contains-any', ['cat', 'dog'])->get();
// or
Post::whereArrayContainsAny('tags', ['cat', 'dog'])->get();

Firestore 特定操作

Firestore 有特定操作 endAt、endBefore、limitToLast、startAfter 和 startAt。 查看完整列表。

DB::table('user')->orderBy('age', 'ASC')->startAfter([17])->get();
// or
User::orderBy('age', 'ASC')->startAfter([17])->get();

测试

composer test

变更日志

请参阅 CHANGELOG 了解最近更改的信息。

贡献

请参阅 CONTRIBUTING 了解详细信息。

安全性

如果您发现任何安全相关的问题，请通过电子邮件 ennio.sousa@pruvo.app 联系我们，而不是使用问题跟踪器。

鸣谢

• Ennio Sousa
• 所有贡献者

许可证

MIT 许可证 (MIT)。请参阅 许可证文件 了解更多信息。