From a2d07ca489624d0db524bb95c34f0ad935fbf9fc Mon Sep 17 00:00:00 2001
From: skuruppu <skuruppu@google.com>
Date: Wed, 8 Apr 2026 03:34:29 +0000
Subject: [PATCH] docs(spanner): snippets to set transaction options

Adds a snippet for setting the isolation level and another for setting
the read lock mode.

Both samples shows how to set the isolation level and read lock mode at
the client level, and how to set it at a transaction level.
---
 spanner/src/isolation_level.php | 74 +++++++++++++++++++++++++++++++++
 spanner/src/read_lock_mode.php  | 74 +++++++++++++++++++++++++++++++++
 spanner/test/spannerTest.php    | 20 +++++++++
 3 files changed, 168 insertions(+)
 create mode 100644 spanner/src/isolation_level.php
 create mode 100644 spanner/src/read_lock_mode.php

diff --git a/spanner/src/isolation_level.php b/spanner/src/isolation_level.php
new file mode 100644
index 000000000..778d101b8
--- /dev/null
+++ b/spanner/src/isolation_level.php
@@ -0,0 +1,74 @@
+<?php
+/**
+ * Copyright 2026 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/main/spanner/README.md
+ */
+
+namespace Google\Cloud\Samples\Spanner;
+
+// [START spanner_isolation_level]
+use Google\Cloud\Spanner\SpannerClient;
+use Google\Cloud\Spanner\Transaction;
+use Google\Cloud\Spanner\V1\TransactionOptions\IsolationLevel;
+
+/**
+ * Shows how to run a Read Write transaction with isolation level options.
+ *
+ * Example:
+ * ```
+ * isolation_level($instanceId, $databaseId);
+ * ```
+ *
+ * @param string $instanceId The Spanner instance ID.
+ * @param string $databaseId The Spanner database ID.
+ */
+function isolation_level(string $instanceId, string $databaseId): void
+{
+    // The isolation level specified at the client-level will be applied to all
+    // RW transactions.
+    $spanner = new SpannerClient([
+        'isolationLevel' => IsolationLevel::SERIALIZABLE
+    ]);
+    $instance = $spanner->instance($instanceId);
+    $database = $instance->database($databaseId);
+
+    // The isolation level specified at the request level takes precedence over
+    // the isolation level configured at the client level.
+    $database->runTransaction(function (Transaction $t) {
+        // Read an AlbumTitle.
+        $results = $t->execute('SELECT AlbumTitle from Albums WHERE SingerId = 1 and AlbumId = 1');
+        foreach ($results as $row) {
+            printf('Current Album Title: %s' . PHP_EOL, $row['AlbumTitle']);
+        }
+
+        // Update the AlbumTitle.
+        $rowCount = $t->executeUpdate('UPDATE Albums SET AlbumTitle = \'A New Title\' WHERE SingerId = 1 and AlbumId = 1');
+        printf('%d record(s) updated.' . PHP_EOL, $rowCount);
+    }, [
+        'transactionOptions' => [
+            'isolationLevel' => IsolationLevel::REPEATABLE_READ
+        ]
+    ]);
+}
+// [END spanner_isolation_level]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);
diff --git a/spanner/src/read_lock_mode.php b/spanner/src/read_lock_mode.php
new file mode 100644
index 000000000..1e3bf115a
--- /dev/null
+++ b/spanner/src/read_lock_mode.php
@@ -0,0 +1,74 @@
+<?php
+/**
+ * Copyright 2026 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/main/spanner/README.md
+ */
+
+namespace Google\Cloud\Samples\Spanner;
+
+// [START spanner_read_lock_mode]
+use Google\Cloud\Spanner\SpannerClient;
+use Google\Cloud\Spanner\Transaction;
+use Google\Cloud\Spanner\V1\TransactionOptions\ReadWrite\ReadLockMode;
+
+/**
+ * Shows how to run a Read Write transaction with read lock mode options.
+ *
+ * Example:
+ * ```
+ * read_lock_mode($instanceId, $databaseId);
+ * ```
+ *
+ * @param string $instanceId The Spanner instance ID.
+ * @param string $databaseId The Spanner database ID.
+ */
+function read_lock_mode(string $instanceId, string $databaseId): void
+{
+    // The read lock mode specified at the client-level will be applied to all
+    // RW transactions.
+    $spanner = new SpannerClient([
+        'readLockMode' => ReadLockMode::OPTIMISTIC
+    ]);
+    $instance = $spanner->instance($instanceId);
+    $database = $instance->database($databaseId);
+
+    // The read lock mode specified at the request level takes precedence over
+    // the read lock mode configured at the client level.
+    $database->runTransaction(function (Transaction $t) {
+        // Read an AlbumTitle.
+        $results = $t->execute('SELECT AlbumTitle from Albums WHERE SingerId = 2 and AlbumId = 1');
+        foreach ($results as $row) {
+            printf('Current Album Title: %s' . PHP_EOL, $row['AlbumTitle']);
+        }
+
+        // Update the AlbumTitle.
+        $rowCount = $t->executeUpdate('UPDATE Albums SET AlbumTitle = \'A New Title\' WHERE SingerId = 2 and AlbumId = 1');
+        printf('%d record(s) updated.' . PHP_EOL, $rowCount);
+    }, [
+        'transactionOptions' => [
+            'readLockMode' => ReadLockMode::PESSIMISTIC
+        ]
+    ]);
+}
+// [END spanner_read_lock_mode]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);
diff --git a/spanner/test/spannerTest.php b/spanner/test/spannerTest.php
index 548042e6c..0b86844ce 100644
--- a/spanner/test/spannerTest.php
+++ b/spanner/test/spannerTest.php
@@ -492,6 +492,26 @@ public function testReadWriteTransaction()
         $this->assertStringContainsString('Transaction complete.', $output);
     }
 
+    /**
+     * @depends testUpdateData
+     */
+    public function testReadLockMode()
+    {
+        $output = $this->runFunctionSnippet('read_lock_mode');
+        $this->assertStringContainsString('Current Album Title:', $output);
+        $this->assertStringContainsString('record(s) updated.', $output);
+    }
+
+    /**
+     * @depends testUpdateData
+     */
+    public function testIsolationLevel()
+    {
+        $output = $this->runFunctionSnippet('isolation_level');
+        $this->assertStringContainsString('Current Album Title:', $output);
+        $this->assertStringContainsString('record(s) updated.', $output);
+    }
+
     /**
      * @depends testAddColumn
      */