README

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

安装

您可以通过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,
    ];
}

复杂查询

• 强烈建议与 pruvo/laravel-firestore-connection 一起使用 Laravel Scout。
• Laravel Scout通过使用 whereIn 使用结果ID检索模型。Firestore一次最多支持10个ID。因此，每页分页10个。
• Firebase有一个扩展，可以将所有数据导出到与Google BigQuery同步。BigQuery类似于SQL，因此您可以在那里跨数据并构建B.I.面板。

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）。请参阅许可文件获取更多信息。