Download the PHP package google/cloud-spanner without Composer

Google Cloud Spanner for PHP

Idiomatic PHP client for Cloud Spanner.

• API documentation

NOTE: This repository is part of Google Cloud PHP. Any support requests, bug reports, or development contributions should be directed to that project.

A fully managed, mission-critical, relational database service that offers transactional consistency at global scale, schemas, SQL (ANSI 2011 with extensions), and automatic, synchronous replication for high availability.

Installation

To begin, install the preferred dependency manager for PHP, Composer.

Now install this component:

This component requires the gRPC extension. Please see our gRPC installation guide for more information on how to configure the extension.

Authentication

Please see our Authentication guide for more information on authenticating your client. Once authenticated, you'll be ready to start making requests.

Sample

Multiplexed Sessions

The V2 version of the Spanner Client Library for PHP uses Multiplexed Sessions. Multiplexed Sessions allow your application to create a large number of concurrent requests on a single session. Some advantages include reduced backend resource consumption due to a more straightforward session management protocol, and less management as sessions no longer require cleanup after use or keep-alive requests when idle.

Session Caching

The session cache is configured with a default cache which uses the PSR-6 compatible SysvCacheItemPool when the sysvshm extension is enabled, and FileSystemCacheItemPool when sysvshm is not available. This ensures that your processes share a single multiplex session for each database and creator role.

To change the default cache pool, use the option cacheItemPool when instantiating your Spanner client:

This can also be passed in as an option to the instance or database methods:

Refreshing Sessions

Sessions will refresh synchronously every 7 days. You can use this script to refresh the session asynchronously, in to avoid latency in your application (recommended every ~24 hours):

Session Locking

Locking occurs when a new session is created, and ensures no race conditions occur when a session expires. Locking uses a Semaphore lock when sysvmsg, sysvsem, and sysvshm extensions are enabled, and a Flock lock otherwise. To configure a custom lock, supply a class implementing LockInterface when calling Instance::database. Here's an example which encorporates the Symfony Lock component:

Client-Side Metrics

The Cloud Spanner client library supports exporting built-in client-side metrics to Google Cloud Monitoring using OpenTelemetry. These metrics provide detailed observability into operations, RPC attempts, and Google Front End (GFE) or Spanner API Frontend (AFE) latencies.

To enable client-side metrics:

All captured metrics are aggregated in-memory and exported synchronously during the PHP process shutdown phase.

[!WARNING] Performance Caveat: Because PHP has a share-nothing architecture, exporting metrics synchronously at shutdown will add to the total request execution latency of the PHP process. For this reason, it is advised to enable built-in metrics primarily for debugging and active performance monitoring.

To minimize this performance overhead, installing the PECL ext-opentelemetry extension is highly recommended.

Prerequisites

1. IAM Permissions: The credentials used by your application require monitoring.timeSeries.create permission to publish metrics. Predefined Spanner roles (such as roles/spanner.databaseAdmin, roles/spanner.databaseUser, and roles/spanner.databaseReader) already include this permission by default. If you are using a custom IAM role, ensure this permission is added.
2. OpenTelemetry Extension: Installing the ext-opentelemetry PHP extension is highly advised to optimize metrics collection and export performance.

Debugging

Please see our Debugging guide for more information about the debugging tools.

Version

This component is considered GA (generally available). As such, it will not introduce backwards-incompatible changes in any minor or patch releases. We will address issues and requests with the highest priority.

Next Steps

1. Understand the official documentation.
2. Take a look at in-depth usage samples.