Weave Code
Cloud Datastore Laravel Package
google/cloud-datastore
Official Google Cloud PHP client for Datastore, a fully managed NoSQL document database. Provides idiomatic access to entities, queries, transactions, indexes, and the local emulator, with Google Cloud authentication, pagination helpers, and support for key-based lookups and ancestor queries. Ideal...
At a glance
Frequently asked questions about Cloud Datastore
- What is google/cloud-datastore and what does it do?
- It is the official Google Cloud PHP client for Datastore, a fully managed NoSQL document database, and also works with Firestore in Datastore mode. The package is a GAPIC-generated SDK that exposes DatastoreClient plus entity, key, query, and transaction value objects. It handles authentication, batching, key-based lookups, ancestor queries, and cursor pagination. It is a transport layer, not an application framework integration.
- Is there a Laravel service provider or facade for google/cloud-datastore?
- No. This is not a Laravel package: there is no service provider, facade, config file, or Eloquent driver shipped with it. You install it via Composer and register a DatastoreClient instance yourself, typically as a singleton in a service provider. Most teams wrap it behind a repository or gateway interface rather than injecting the raw client throughout the app.
- Can I use Eloquent or Laravel migrations with Google Cloud Datastore?
- No. Datastore is schemaless with kinds, ancestors, and entity groups, so it does not map onto Eloquent's relational assumptions like joins, foreign keys, migrations, and eager loading with(). The DB facade, query builder, seeders, and artisan database tooling have no Datastore equivalent. You hand-roll repositories, pagination, and transactions, and reimplement model events, observers, and soft deletes if you need them.
- How do I install google/cloud-datastore in a Laravel project?
- Run composer require google/cloud-datastore; the package is PSR-4 compliant and drops into any Laravel app cleanly. The client prefers gRPC, so you will usually need the grpc PHP extension installed as well, otherwise it falls back to REST with different latency and error characteristics. Some shared hosts and managed PHP runtimes cannot install the extension, so verify that before committing to the library.
- How does authentication work for the Datastore PHP client?
- It uses standard Google Application Default Credentials. Locally you typically point GOOGLE_APPLICATION_CREDENTIALS at a service-account JSON key, while on GCP or GKE you rely on the attached service account or workload identity. No Laravel-specific config is needed, but you must keep credentials out of version control and grant the narrowest IAM roles that work.
- How do I test Datastore code locally or in CI?
- Set the DATASTORE_EMULATOR_HOST environment variable to point at a running Datastore emulator, and the client will use it instead of production. The emulator is the practical way to run integration tests in CI without touching real GCP resources. Because there is no Eloquent layer to fake, most teams combine emulator-backed integration tests with a repository interface they can mock in unit tests.
- How do transactions and pagination work compared with Laravel's DB facade?
- You use $client->transaction() with optimistic concurrency rather than DB::transaction() closures, and you must handle retries on contention yourself. Pagination is cursor-based via query result pages, not paginate(), so you cannot reuse Laravel's paginator views directly. Batch operations and key-based lookups have their own helper methods on the client, which is often faster than querying by property.
- What are the production gotchas with Datastore entity groups and indexes?
- Writes within a single entity group are serialized, with roughly one sustained write per second as guidance, so hot keys and counters can become incidents. Composite index management lives outside your repository in index.yaml deployed via gcloud, which breaks the migrations-in-version-control habit Laravel teams rely on. Index fan-out also affects write cost and latency, so the data model must be designed around access patterns up front. Datastore is strongly consistent by key but eventually consistent on index queries.
- Is google/cloud-datastore actively maintained and safe to pin?
- It is maintained by Google as part of the googleapis/google-cloud-php monorepo, and this repository is a subtree split rather than a standalone project. That explains the low star count and zero dependents, which are misleading signals rather than signs of abandonment. GAPIC clients regenerate frequently and minor versions can shift surface area, so pin a version and read changelogs before upgrading.
- When should I choose Datastore over Cloud SQL or Firestore for a Laravel app?
- Pick Datastore only for a bounded context that genuinely needs a schemaless, globally distributed store with high read scale and flexible schema. For most Laravel applications PostgreSQL on Cloud SQL is cheaper, better documented, and lets you keep Eloquent, migrations, and DB::transaction(). Datastore has no portable SQL surface, so moving a domain off it means rewriting the persistence layer, which is a one-way door worth a design review. Datastore mode Firestore is the better pick if you also want the newer Firestore ecosystem and tooling.
Weaver
How can I help you explore Laravel packages today?