This package adds functionalities to the Eloquent model and Query builder for Google Firestore, using the original Laravel API.
You can install the package via composer:
composer require pruvo/laravel-firestore-connection
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'),
],
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;
}
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:
There are not any way to query firestore database using string (like SQL syntaxe). All queries must be done via Firestore SDK.
- SQL database supports
select * from users where status = 'disabled' or age > 18;
but it is not supported on Firestore.
- But there is a workaround:
orderBy('field', 'ASC')->startAt(null)
.
- you can not use
belongsTo
,hasOne
,hasMany
,morphOne
,morphMany
,belongsToMany
ormorphToMany
; - In contrast, Firestore has subcollections, so you can use
hasSubcollection
to define relationships.
- 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();
- Avoid use
reference
type becouse it can not be serialized and does not have advantages. Instead use document reference path (string representation ofDocumentReference
). - Avoid use
map
andarray
types unless it is needed. Themap
is equivalent to associative array, andarray
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 extendsDateTimeInterface
and can safely be used; - use the cast
Pruvo\LaravelFirestoreConnection\Casts\AsCarbon
on the model;
- set a instance of
<?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,
];
}
- 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 does not support all SQL-like operators and have some specific operators. Check the full list.
DB::table('posts')->where('tags', 'array-contains-any', ['cat', 'dog'])->get();
// or
DB::table('posts')->whereArrayContainsAny('tags', ['cat', 'dog'])->get();
Post::where('tags', 'array-contains-any', ['cat', 'dog'])->get();
// or
Post::whereArrayContainsAny('tags', ['cat', 'dog'])->get();
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();
composer test
Please see CHANGELOG for more information what has changed recently.
Please see CONTRIBUTING for details.
If you discover any security related issues, please email ennio.sousa@pruvo.app instead of using the issue tracker.
The MIT License (MIT). Please see License File for more information.