README

This package adds functionalities to the Eloquent model and Query builder for Google Firestore, using the original Laravel API.

Installation

You can install the package via composer:

composer require pruvo/laravel-firestore-connection

Configuration

You can use Firestore either as the main database, either as a side database. To do so, add a new firebase connection to config/database.php:

'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

Extending the base model

This package includes a Firestore enabled Eloquent class that you can use to define models for corresponding collections.

<?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;
}

Limitations

Laravel is a framework originally designed to use SQL databases for its ORM. However, Firestore is a NoSQL database, and therefore, it does not support the same features as SQL databases.

From point of view that you are used to SQL databases, the following features are not supported:

SQL syntaxe

There are not any way to query firestore database using string (like SQL syntaxe). All queries must be done via Firestore SDK.

Only supports AND operator

• SQL database supports select * from users where status = 'disabled' or age > 18; but it is not supported on Firestore.

Do not support equals to null

• But there is a workaround: orderBy('field', 'ASC')->startAt(null).

Model does not support relationship because it is impossible cross collection data, so

• you can not use belongsTo, hasOne, hasMany, morphOne, morphMany, belongsToMany or morphToMany;
• In contrast, Firestore has subcollections, so you can use hasSubcollection to define relationships.

Model ID behavior

• Firestore does not support numeric auto increment. To keep the records orderable it uses Str::orderedUuid();.
• Firestore is a document database, so the primary key is the document name.
• If auto increment is enabled, and you want to set a custom UUID, you must force fill the __name__ attribute before saving the model.

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

Firestore database types

• Avoid use reference type becouse it can not be serialized and does not have advantages. Instead use document reference path (string representation of DocumentReference).
• Avoid use map and array types unless it is needed. The map is equivalent to associative array, and array is equivalent to sequencial array.
• Date attributes are stored as string by default. To store as timestamp (native Firestore type) you must to:
  • set a instance of DateTimeInterface as value; Carbon extends DateTimeInterface and can safely be used;
  • use the cast Pruvo\LaravelFirestoreConnection\Casts\AsCarbon on the model;

<?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,
    ];
}

Complexy queries

• It is strogly recommended use Laravel Scout with pruvo/laravel-firestore-connection.
• Laravel Scout retrive models by results ids using whereIn. Firestore support up to 10 ids by request. So paginate by 10 per page.
• Firebase have an extension that export and sync all data with Google Big Query. BigQuery is SQL like so there you can cross data and build B.I. panels.

Firestore specific operators

Firestore does not support all SQL-like operators and have some specific operators. Check the full list.

Query builder

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

Eloquent builder

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

Firestore specific operations

Firestore has specific operations endAt, endBefore, limitToLast, startAfter and startAt. Check the full list.

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

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email ennio.sousa@pruvo.app instead of using the issue tracker.

Credits

• Ennio Sousa
• All Contributors

License

The MIT License (MIT). Please see License File for more information.