Download the PHP package firevel/firestore-mirror without Composer

Laravel Firestore Mirror

Automatically sync your Laravel Eloquent models to Google Firestore collections in real-time. This package provides a seamless way to mirror your database records to Firestore, enabling powerful real-time features and offline capabilities for your applications.

Features

• 🔄 Automatic Synchronization: Changes to your Eloquent models are automatically reflected in Firestore
• 🚀 Batch Operations: Efficiently sync entire collections using Firestore's batch API
• 📂 Multiple Collections: Mirror a single model to multiple Firestore collections for denormalization
• 🎯 Flexible Configuration: Customize collection names, document IDs, and document structure
• 🧩 Simple Integration: Just add a trait to your existing Eloquent models
• ⚡ Performance Optimized: Uses Firestore batch operations for bulk updates
• 🛠️ Artisan Command: Built-in command for bulk mirroring with progress tracking and chunked processing

Requirements

• PHP 8.0 or higher
• Laravel 8.0 or higher
• firevel/firestore package

Installation

Install the package using Composer:

Quick Start

Add the HasFirestoreMirror trait to any Eloquent model you want to sync with Firestore:

That's it! Your User model will now automatically sync to Firestore whenever you create, update, or delete records.

Configuration

Customizing Collection Names

By default, the Firestore collection name matches your model's database table name. You can customize this in two ways:

Static Collection Name

Dynamic Collection Name

Customizing Document Structure

Control exactly what data gets synced to Firestore by overriding the toFirestoreDocument() method:

Customizing Document IDs

By default, the Firestore document ID matches your model's primary key. Override this behavior:

Mirroring to Multiple Collections

You can mirror a single model to multiple Firestore collections. This is useful for denormalization patterns common in Firestore, where you might want the same data available in different collections for efficient querying.

Using Property

Using getFirestoreCollectionName() Method

Using getFirestoreCollectionNames() Method (Recommended)

When mirroring to multiple collections:

• All collections receive the same document ID and document structure
• Write and delete operations use Firestore's batch API for atomicity
• If you need different document structures per collection, override toFirestoreDocument() with conditional logic

Priority Order: If multiple methods are defined, getFirestoreCollectionNames() takes precedence over getFirestoreCollectionName(), which takes precedence over the $firestoreCollection property.

Usage

Automatic Syncing

Once you've added the HasFirestoreMirror trait, your models will automatically sync to Firestore on these events:

• Create: New model instances are added to Firestore
• Update: Changes to existing models are synced to Firestore
• Delete: Deleted models are removed from Firestore

Manual Syncing

You can manually sync individual models:

Batch Syncing Collections

The package provides a powerful mirrorToFirestore() collection macro for efficiently syncing multiple models at once using Firestore's batch operations:

The batch operation is atomic - either all documents are synced successfully, or none are.

Artisan Command for Bulk Mirroring

For large-scale operations or initial data migration, use the included Artisan command to mirror all records of a model to Firestore:

Features:

• 📊 Progress Bar: Real-time progress feedback during the mirror operation
• 🔄 Chunked Processing: Processes records in configurable batches to prevent memory issues
• ⚡ Batch Operations: Uses Firestore batch API for optimal performance
• ✅ Validation: Ensures the model exists and uses the HasFirestoreMirror trait

Example Output:

When to Use:

• Initial data migration when setting up Firestore mirroring
• Recovering from sync failures or data inconsistencies
• Re-syncing data after changing toFirestoreDocument() structure
• Batch operations on very large collections (thousands+ records)

Note: The command respects the shouldMirrorToFirestore() method and will skip records that shouldn't be mirrored. For programmatic batch operations within your application code, use the collection macro ->mirrorToFirestore() instead.

Deleting from Firestore

To manually delete a model from Firestore without deleting it from your database:

Advanced Usage

Disabling Syncing Temporarily

You can temporarily disable Firestore syncing for specific operations using the withoutSyncingToFirestore() method:

This is particularly useful for:

• Importing large datasets without Firestore overhead
• Running database seeders and factories during testing
• Performing bulk operations that you'll sync manually later
• Temporary data that doesn't need to be mirrored

Conditional Syncing

The package provides built-in support for conditional syncing. Override the shouldMirrorToFirestore() method to control when models should be synced to Firestore:

When shouldMirrorToFirestore() returns false:

• The model will not be synced to Firestore on create/update
• The model will not be deleted from Firestore on deletion
• Both mirrorToFirestore() and deleteFromFirestore() will return early without making Firestore calls

This is useful for:

• Skipping sync for draft or incomplete records
• Conditional syncing based on user roles or permissions
• Implementing soft-delete patterns where you want to keep Firestore data
• Performance optimization by reducing unnecessary Firestore writes

Multi-Tenant Applications

For multi-tenant applications, you can dynamically set collection names:

Testing

Run the test suite:

Run a specific test:

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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