Weave Code
Cloud Firestore Laravel Package
google/cloud-firestore
Idiomatic PHP client for Google Cloud Firestore, a NoSQL document database built for automatic scaling and high performance. Install via Composer (google/cloud-firestore); requires the gRPC extension. Includes authentication and debugging guides.
Cloud Firestore for PHP is an idiomatic PHP client for Google Cloud Firestore, a fully managed NoSQL document database built for automatic scaling, high performance, and ease of application development. It provides generated classes and a FirestoreClient for reading, writing, and querying documents through the Cloud Firestore API, with support for gRPC and Google Cloud authentication.
- Document operations: retrieve, create, update, and delete Firestore documents
- Typed request/response classes such as
GetDocumentRequestandDocument - gRPC transport with exception handling via
ApiException - Google Cloud authentication integration
- Composer installation:
composer require google/cloud-firestore
Frequently asked questions about Cloud Firestore
- How do I install google/cloud-firestore in a Laravel application?
- Install it with Composer using composer require google/cloud-firestore. The package also requires the gRPC PHP extension, so you must run pecl install grpc and enable extension=grpc in php.ini or bake it into your Dockerfile base image. After that, verify the extension loads in CI before wiring the client into a service provider.
- Does google/cloud-firestore require the gRPC PHP extension?
- Yes. This component requires the gRPC extension to be compiled and enabled, and it is the most common source of installation failures. Google publishes a dedicated PHP gRPC installation guide covering pecl and Docker setups. Bake grpc into your base image and assert its presence in CI so deployments do not fail at runtime.
- How should I authenticate Firestore in Laravel without committing service account keys?
- Prefer Application Default Credentials so the library picks up the runtime identity of Cloud Run or Cloud Functions automatically. If you must use a service account key, read it through config/services.php backed by a secret manager or environment variable, and never commit it to the repository. Bind the client as a singleton in a dedicated service provider so credential handling lives in one place.
- How do I point the Firestore client at the emulator when running PHPUnit tests?
- Use the FIRESTORE_EMULATOR_HOST environment variable. As of v2.3.4 the emulatorHost client option key has been removed from the clients, and the environment variable is the only supported mechanism. Wire it into your phpunit.xml and CI pipeline so the suite talks to the emulator rather than production Firestore.
- Is upgrading from v2.1.0 to v2.3.4 a breaking change?
- No. The v2.3.4 release is chore-only: it removes an unused emulatorHost option key that was already a no-op, plus documentation and sample updates, with no changes to the data, query, or auth APIs. Before any production upgrade, plan a changelog sweep across v2.2.x through v2.3.x, since the prior assessment was written against v2.1.0. Treat that sweep as a gate on the integration ticket.
- Can I use Firestore alongside Eloquent instead of replacing it?
- Yes, and a hybrid setup is usually the right call. Put Firestore behind repository classes such as FirestoreUserRepository while keeping Eloquent and SQL for users, roles, joins, and ledger-grade transactional data. Use Laravel Scout for search indexing and Redis for sessions and hot metadata. This keeps the Google SDK confined to a single namespace that can be mocked or swapped later.
- How do I handle real-time document updates in a Laravel app?
- Firestore real-time sync is normally consumed by client SDKs using onSnapshot listeners, which suits collaborative and notification features without polling or a separate WebSocket tier. For server-side Laravel code, avoid holding long-lived listeners inside PHP-FPM workers. Instead, bridge document changes into Laravel queues or events, for example via Cloud Functions, and process them in background jobs.
- What are the cost and query limitations of Firestore in Laravel?
- Firestore bills per operation, so chatty CRUD patterns directly determine your monthly run rate, and document modelling is the main lever for controlling it. It has no complex joins or GROUP BY, so reporting and analytics usually need application-layer aggregation or a BigQuery export. Review document shape, composite indexes, and denormalisation strategy before build to avoid over-nesting and hotspot keys.
- When should I avoid Firestore and pick something else?
- Avoid it for financial ledgers, heavy reporting, or anything that needs joins and aggregations across entities; relational SQL remains the better fit there. Firestore-specific semantics such as FieldValue.serverTimestamp() and security rules also reduce portability if you may change vendors. The recommended pattern is a hybrid architecture: Firestore for real-time, high-volume, schema-flexible documents and SQL for transactional and analytical workloads.
- Is google/cloud-firestore actively maintained and where do I report issues?
- The package is part of the google-cloud-php monorepo maintained by Google, and it is released under the google/cloud-firestore Composer name with tagged versions such as v2.3.4. Support requests, bug reports, and contributions belong in the parent google-cloud-php repository rather than the split package repo. Check the Packagist release history and the monorepo changelog before pinning a version.
Weaver
How can I help you explore Laravel packages today?