chore(Spanner): TransactionOptionsBuilder refactor (WIP)

.github/workflows/emulator-system-tests-spanner.yaml

@@ -44,17 +44,17 @@ jobs:
           php-version: '8.1'
           ini-values: grpc.enable_fork_support=1
           tools: pecl
-          extensions: bcmath, grpc
+          extensions: bcmath, grpc, pcntl
 
       - name: Install dependencies
         run: |
           # ensure composer uses local Core instead of pulling from packagist
-          composer config repositories.local  --json '{"type":"path", "url": "../Core", "options": {"versions": {"google/cloud-core": "1.100"}}}' -d Spanner
+          composer config repositories.local  --json '{"type":"path", "url": "../Core", "options": {"versions": {"google/cloud-core": "1.100"}},"canonical":false}' -d Spanner
           composer update --prefer-dist --no-interaction --no-suggest -d Spanner/
 
       - name: Run system tests
         run: |
-          Spanner/vendor/bin/phpunit -c Spanner/phpunit-system.xml.dist
+          Spanner/vendor/bin/phpunit -c Spanner/phpunit-system.xml.dist --testdox
         env:
           SPANNER_EMULATOR_HOST: localhost:9010
           GOOGLE_CLOUD_PHP_TESTS_KEY_PATH: '.github/emulator/example-key.json'

Core/src/ApiHelperTrait.php

@@ -17,12 +17,10 @@
  */
 namespace Google\Cloud\Core;
 
-use Exception;
 use Google\ApiCore\ArrayTrait;
 use Google\ApiCore\Options\CallOptions;
 use Google\Protobuf\Internal\Message;
 use Google\Protobuf\NullValue;
-use LogicException;
 
 /**
  * @internal
@@ -33,6 +31,8 @@ trait ApiHelperTrait
     use ArrayTrait;
     use TimeTrait;
 
+    private OptionsValidator $optionsValidator;
+
     /**
      * Format a struct for the API.
      *
@@ -276,40 +276,9 @@ private function splitOptionalArgs(array $input, array $extraAllowedKeys = []):
      */
     private function validateOptions(array $options, array|Message|string ...$optionTypes): array
     {
-        $splitOptions = [];
-        foreach ($optionTypes as $optionType) {
-            if (is_array($optionType)) {
-                $splitOptions[] = $this->pluckArray($optionType, $options);
-            } elseif ($optionType === CallOptions::class) {
-                $callOptionKeys = array_keys((new CallOptions([]))->toArray());
-                $splitOptions[] = $this->pluckArray($callOptionKeys, $options);
-            } elseif ($optionType instanceof Message) {
-                $messageKeys = array_map(
-                    fn ($method) => lcfirst(substr($method, 3)),
-                    array_filter(
-                        get_class_methods($optionType),
-                        fn ($m) => 0 === strpos($m, 'get')
-                    )
-                );
-                $messageOptions = $this->pluckArray($messageKeys, $options);
-                if ($optionType instanceof Message) {
-                    $optionType->mergeFromJsonString(json_encode($messageOptions, JSON_FORCE_OBJECT));
-                    $validatedOptionGroup = $optionType;
-                } else {
-                    $validatedOptionGroup = $messageOptions;
-                }
-                $splitOptions[] = $validatedOptionGroup;
-            } else {
-                throw new LogicException(sprintf('Invalid option type: %s', $optionType));
-            }
+        if (!isset($this->optionsValidator)) {
+            $this->optionsValidator = new OptionsValidator();
         }
-
-        if (!empty($options)) {
-            throw new Exception(
-                'Unexpected option(s) provided: ' . implode(', ', array_keys($options))
-            );
-        }
-
-        return $splitOptions;
+        return $this->optionsValidator->validateOptions($options, ...$optionTypes);
     }
 }

Core/src/Iam/Iam.php

@@ -34,7 +34,7 @@
  *
  * use Google\Cloud\Spanner\SpannerClient;
  *
- * $spanner = new SpannerClient();
+ * $spanner = new SpannerClient(['projectId' => 'my-project']);
  * $instance = $spanner->instance('my-new-instance');
  *
  * $iam = $instance->iam();

Core/src/LongRunning/LongRunningClientConnection.php

@@ -0,0 +1,119 @@
+<?php
+/**
+ * Copyright 2025 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.
+ */
+
+namespace Google\Cloud\Core\LongRunning;
+
+use Google\ApiCore\OperationResponse;
+use Google\ApiCore\Serializer;
+use Google\Cloud\Core\RequestProcessorTrait;
+use Google\LongRunning\ListOperationsRequest;
+use Google\Protobuf\Any;
+
+/**
+ * Defines the calls required to manage Long Running Operations using a GAPIC
+ * generated client.
+ *
+ * @internal
+ */
+class LongRunningClientConnection implements LongRunningConnectionInterface
+{
+    use RequestProcessorTrait;
+
+    public function __construct(
+        private $gapicClient,
+        private Serializer $serializer
+    ) {
+    }
+
+    /**
+     * @param array $args
+     */
+    public function get(array $args)
+    {
+        $operationResponse = $this->gapicClient->resumeOperation($args['name']);
+
+        return $this->operationResponseToArray($operationResponse);
+    }
+
+    /**
+     * @param array $args
+     */
+    public function cancel(array $args)
+    {
+        $operationResponse = $this->gapicClient->resumeOperation(
+            $args['name'],
+            $args['method'] ?? null
+        );
+        $operationResponse->cancel();
+
+        return $this->operationResponseToArray($operationResponse);
+    }
+
+    /**
+     * @param array $args
+     */
+    public function delete(array $args)
+    {
+        $operationResponse = $this->gapicClient->resumeOperation(
+            $args['name'],
+            $args['method'] ?? null
+        );
+        $operationResponse->cancel();
+
+        return $this->operationResponseToArray($operationResponse);
+    }
+
+    /**
+     * @param array $args
+     */
+    public function operations(array $args)
+    {
+        $request = ListOperationsRequest::build($args['name'], $args['filter'] ?? null);
+        $response = $this->gapicClient->getOperationsClient()->listOperations($request);
+
+        return $this->handleResponse($response);
+    }
+
+    private function operationResponseToArray(OperationResponse $operationResponse)
+    {
+        $response = $this->handleResponse($operationResponse->getLastProtoResponse());
+        $metaType = $response['metadata']['typeUrl'];
+
+        // unpack result Any type
+        $result = $operationResponse->getResult();
+        if ($result instanceof Any) {
+            // For some reason we aren't doing this in GAX OperationResponse (but we should)
+            $result = $result->unpack();
+        }
+        $response['response'] = $this->handleResponse($result);
+
+        // unpack error Any type
+        $response['error'] = $this->handleResponse($operationResponse->getError());
+
+        $metadata = $operationResponse->getMetadata();
+        if ($metadata instanceof Any) {
+            // For some reason we aren't doing this in GAX OperationResponse (but we should)
+            $metadata = $metadata->unpack();
+        }
+        $response['metadata'] = $this->handleResponse($metadata);
+
+        // Used in LongRunningOperation to invoke callables
+        $response['metadata'] += ['typeUrl' => $metaType];
+
+        return $response;
+    }
+}

Core/src/LongRunning/LongRunningOperation.php

@@ -19,6 +19,7 @@
 
 /**
  * Represent and interact with a Long Running Operation.
+ * @template T
  */
 class LongRunningOperation
 {
@@ -180,7 +181,7 @@ public function state(array $options = [])
      * ```
      *
      * @param array $options [optional] Configuration options.
-     * @return mixed|null
+     * @return T|mixed|null
      */
     public function result(array $options = [])
     {
@@ -252,12 +253,11 @@ public function reload(array $options = [])
 
         $this->result = null;
         $this->error = null;
-        if (isset($res['done']) && $res['done']) {
+
+        if ($res['done'] ?? false && isset($res['metadata']['typeUrl'])) {
             $type = $res['metadata']['typeUrl'];
             $this->result = $this->executeDoneCallback($type, $res['response']);
-            $this->error = (isset($res['error']))
-                ? $res['error']
-                : null;
+            $this->error = $res['error'] ?? null;
         }
 
         return $this->info = $res;

Core/src/OptionsValidator.php

@@ -0,0 +1,77 @@
+<?php
+
+/**
+ * Copyright 2025 Google Inc. All Rights Reserved.
+ *
+ * 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.
+ */
+namespace Google\Cloud\Core;
+
+use Google\ApiCore\ArrayTrait;
+use Google\ApiCore\Options\CallOptions;
+use Google\ApiCore\Serializer;
+use Google\Protobuf\Internal\Message;
+use LogicException;
+
+class OptionsValidator
+{
+    use ArrayTrait;
+
+    public function __construct(private ?Serializer $serializer = null)
+    {
+    }
+
+    /**
+     * Helper method used to validate optons based on the supplied $optionTypes
+     * $optionTypes can be an array of string keys, a protobuf Message classname, or a
+     * the CallOptions classname. Parameters are split and returned in the order
+     * that the options types are provided.
+     */
+    public function validateOptions(array $options, array|Message|string ...$optionTypes): array
+    {
+        $splitOptions = [];
+        foreach ($optionTypes as $optionType) {
+            if (is_array($optionType)) {
+                $splitOptions[] = $this->pluckArray($optionType, $options);
+            } elseif ($optionType === CallOptions::class) {
+                $callOptionKeys = array_keys((new CallOptions([]))->toArray());
+                $splitOptions[] = $this->pluckArray($callOptionKeys, $options);
+            } elseif ($optionType instanceof Message) {
+                $messageKeys = array_map(
+                    fn ($method) => lcfirst(substr($method, 3)),
+                    array_filter(
+                        get_class_methods($optionType),
+                        fn ($m) => 0 === strpos($m, 'get')
+                    )
+                );
+                $messageOptions = $this->pluckArray($messageKeys, $options);
+                if ($this->serializer) {
+                    $optionType = $this->serializer->decodeMessage($optionType, $messageOptions);
+                } else {
+                    $optionType->mergeFromJsonString(json_encode($messageOptions, JSON_FORCE_OBJECT));
+                }
+                $splitOptions[] = $optionType;
+            } else {
+                throw new LogicException(sprintf('Invalid option type: %s', $optionType));
+            }
+        }
+
+        if (!empty($options)) {
+            throw new LogicException(
+                'Unexpected option(s) provided: ' . implode(', ', array_keys($options))
+            );
+        }
+
+        return $splitOptions;
+    }
+}

Core/src/RequestHandler.php

@@ -42,16 +42,16 @@ class RequestHandler
      */
     private Serializer $serializer;
 
-    private array $clients;
+    private array $clients = [];
 
     /**
      * @param Serializer $serializer
-     * @param array $clientClasses
+     * @param array<string|object> $clients
      * @param array $clientConfig
      */
     public function __construct(
         Serializer $serializer,
-        array $clientClasses,
+        array $clients,
         array $clientConfig = []
     ) {
         //@codeCoverageIgnoreStart
@@ -75,9 +75,12 @@ public function __construct(
         //@codeCoverageIgnoreEnd
 
         // Initialize the client classes and store them in memory
-        $this->clients = [];
-        foreach ($clientClasses as $className) {
-            $this->clients[$className] = new $className($clientConfig);
+        foreach ($clients as $client) {
+            if (is_object($client)) {
+                $this->clients[get_class($client)] = $client;
+            } else {
+                $this->clients[$client] = new $client($clientConfig);
+            }
         }
     }
 

Core/src/ServiceBuilder.php

@@ -257,7 +257,7 @@ public function pubsub(array $config = [])
      *
      * Example:
      * ```
-     * $spanner = $cloud->spanner();
+     * $spanner = $cloud->spanner(['projectId' => 'my-project']);
      * ```
      *
      * @param array $config [optional] {

Core/src/Testing/Snippet/SnippetTestCase.php

@@ -32,6 +32,8 @@
  */
 class SnippetTestCase extends TestCase
 {
+    const PROJECT = 'my-awesome-project';
+
     use CheckForClassTrait;
 
     private static $coverage;