feat!: Spanner V2

Core/src/ApiHelperTrait.php

@@ -261,8 +261,8 @@ private function splitOptionalArgs(array $input, array $extraAllowedKeys = []) :
         $callOptionFields = array_keys((new CallOptions([]))->toArray());
         $keys = array_merge($callOptionFields, $extraAllowedKeys);
 
-        $optionalArgs = $this->pluckArray($keys, $input);
+        $callOptions = $this->pluckArray($keys, $input);
 
-        return [$input, $optionalArgs];
+        return [$input, $callOptions];
     }
 }

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/Iterator/PageIteratorTrait.php

@@ -260,6 +260,7 @@ private function mapResults(array $results)
         if ($items) {
             foreach ($items as $key => $item) {
                 $items[$key] = $resultMapper($item);
+
                 $this->itemCount++;
 
                 if ($this->config['resultLimit'] && $this->config['resultLimit'] <= $this->itemCount) {

Core/src/Middleware/ExceptionMiddleware.php

@@ -0,0 +1,86 @@
+<?php
+/*
+ * Copyright 2024 Google LLC
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *     * Neither the name of Google Inc. nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+namespace Google\Cloud\Core\Middleware;
+
+use Google\ApiCore\ApiException;
+use Google\ApiCore\BidiStream;
+use Google\ApiCore\Call;
+use Google\ApiCore\ClientStream;
+use Google\ApiCore\Middleware\MiddlewareInterface;
+use Google\ApiCore\ServerStream;
+use Google\Cloud\Core\RequestProcessorTrait;
+use GuzzleHttp\Promise\PromiseInterface;
+use Throwable;
+
+/**
+ * Middleware that adds autopopulation functionality. This middlware is
+ * added iff auto population settings are present in the resource
+ * descriptor config for the rpc method in context.
+ *
+ * @internal
+ */
+class ExceptionMiddleware implements MiddlewareInterface
+{
+    use RequestProcessorTrait;
+
+    /** @var callable */
+    private $nextHandler;
+
+    public function __construct(callable $nextHandler) {
+        $this->nextHandler = $nextHandler;
+    }
+
+    /**
+     * @param Call $call
+     * @param array $options
+     *
+     * @return PromiseInterface|ClientStream|ServerStream|BidiStream
+     */
+    public function __invoke(Call $call, array $options)
+    {
+        $response = ($this->nextHandler)($call, $options);
+        if ($response instanceof PromiseInterface) {
+            return $response->then(null, function ($value) {
+                if ($value instanceof \Google\ApiCore\ApiException) {
+                    throw $this->convertToGoogleException($value);
+                }
+                if ($value instanceof Throwable) {
+                    throw $value;
+                }
+            });
+        }
+        // this can also be a Stream
+        return $response;
+    }
+}
+

Core/src/RequestHandler.php

@@ -45,11 +45,11 @@ class RequestHandler
      */
     private Serializer $serializer;
 
-    private array $clients;
+    private array $clients = [];
 
     /**
      * @param Serializer $serializer
-     * @param array $clientClasses
+     * @param array<string|object> $clientClasses
      * @param array $clientConfig
      */
     public function __construct(
@@ -76,11 +76,14 @@ 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 ($clientClasses as $client) {
+            if (is_object($client)) {
+                $this->clients[get_class($client)] = $client;
+            } else {
+                $this->clients[$client] = new $client($clientConfig);
+            }
         }
     }
 

Core/src/RequestProcessorTrait.php

@@ -25,6 +25,7 @@
 use \Google\Protobuf\Internal\Message;
 use Google\Rpc\RetryInfo;
 use Google\Rpc\BadRequest;
+use GuzzleHttp\Promise\PromiseInterface;
 
 /**
  * @internal
@@ -45,7 +46,7 @@ trait RequestProcessorTrait
      * Serializes a gRPC response.
      *
      * @param mixed $response
-     * @return \Generator|OperationResponse|array|null
+     * @return \Generator|OperationResponse|array|PromiseInterface|null
      */
     private function handleResponse($response)
     {
@@ -57,7 +58,7 @@ private function handleResponse($response)
             return $this->serializer->encodeMessage($response);
         }
 
-        if ($response instanceof OperationResponse) {
+        if ($response instanceof OperationResponse || $response instanceof PromiseInterface) {
             return $response;
         }
 

Core/src/ServiceBuilder.php

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

Core/src/Testing/Snippet/Parser/Snippet.php

@@ -168,6 +168,7 @@ public function invoke($returnVar = null)
                 $out = ob_get_clean();
             } catch (\Exception $e) {
                 ob_end_clean();
+                var_dump($content);
                 throw $e;
             }
 

Core/tests/Snippet/Iam/IamManagerTest.php

@@ -36,7 +36,7 @@ class IamManagerTest extends SnippetTestCase
     private $policyData;
     private $resource;
 
-    private $requestHandler;
+    private $spannerClient;
     private $serializer;
     private $iam;
 

Core/tests/Snippet/Iam/IamTest.php

@@ -19,6 +19,7 @@
 
 use Google\Cloud\Core\Testing\Snippet\SnippetTestCase;
 use Google\Cloud\Core\Iam\Iam;
+use Google\Cloud\Core\Iam\IamManager;
 use Google\Cloud\Core\Iam\IamConnectionInterface;
 use Google\Cloud\Core\Testing\TestHelpers;
 use Google\Cloud\Spanner\SpannerClient;
@@ -55,7 +56,7 @@ public function testClass()
         ]);
         $res = $snippet->invoke('iam');
 
-        $this->assertInstanceOf(Iam::class, $res->returnVal());
+        $this->assertInstanceOf(IamManager::class, $res->returnVal());
     }
 
     public function testPolicy()

Core/tests/Unit/LongRunning/OperationResponseTraitTest.php

@@ -18,10 +18,12 @@
 namespace Google\Cloud\Core\Tests\Unit\LongRunning;
 
 use Google\ApiCore\OperationResponse;
+use Google\ApiCore\Serializer;
 use Google\Cloud\Core\LongRunning\OperationResponseTrait;
 use Google\Cloud\Core\LongRunning\LongRunningOperation;
 use Google\Cloud\Core\LongRunning\LongRunningConnectionInterface;
-use Google\ApiCore\Serializer;
+use Google\Cloud\Core\RequestHandler;
+use Google\Cloud\Spanner\Admin\Database\V1\DatabaseAdminClient;
 use Prophecy\Argument;
 use Google\Cloud\Audit\RequestMetadata;
 use Google\Cloud\Audit\AuthorizationInfo;

Core/tests/Unit/ServiceBuilderTest.php

@@ -24,7 +24,6 @@
 use Google\Cloud\Firestore\FirestoreClient;
 use Google\Cloud\Language\LanguageClient;
 use Google\Cloud\Logging\LoggingClient;
-use Google\Cloud\Spanner\SpannerClient;
 use Google\Cloud\Speech\SpeechClient;
 use Google\Cloud\Storage\StorageClient;
 use Google\Cloud\Core\Tests\Unit\Fixtures;
@@ -175,11 +174,6 @@ public function serviceProvider()
             ], [
                 'language',
                 LanguageClient::class
-            ], [
-                'spanner',
-                SpannerClient::class,
-                [],
-                [$this, 'checkAndSkipGrpcTests']
             ], [
                 'speech',
                 SpeechClient::class,

Spanner/MIGRATING.md

@@ -0,0 +1,115 @@
+# Migrating Google Spanner from V1 to V2
+
+## How to upgrade
+
+Update your `google/cloud-spanner` dependency to `^2.0`:
+
+```
+{
+    "require": {
+        "google/cloud-spanner": "^2.0"
+    }
+}
+```
+
+## Changes
+
+### Client Options changes
+
+The following client options are removed/replaced with other options present in
+[`ClientOptions`][ClientOptions]. This was done to ensure client options are consistent across all
+Google Cloud clients.
+
+- `authCache` -> Moved to `credentialsConfig.authCache`
+- `authCacheOptions` -> Moved to `credentialsConfig.authCacheOptions`
+- `FetchAuthTokenInterface` -> Moved to `credentials`
+- `keyFile` -> Moved to `credentials`
+- `keyFilePath` -> Moved to `credentials`
+- `requestTimeout` -> Removed from client options and moved to a call option `timeoutMillis`
+- `scopes` -> Moved to `credentialsConfig.scopes`
+- `quotaProject` -> Moved to `credentialsConfig.quotaProject`
+- `httpHandler` -> Moved to `transportConfig.rest.httpHandler`
+- `authHttpHandler` -> Moved to `credentialsConfig.authHttpHandler`
+- `retries` -> Removed from client options and moved to call options `retrySettings.maxRetries`
+
+### Retry Options changes
+
+The retry options have been moved to use [`RetrySettings`][RetrySettings] in call options
+and function parameters.
+
+- `retries` -> Renamed to `retrySettings.maxRetries`
+- `maxRetries` -> Renamed to `retrySettings.maxRetries`
+
+[RetrySettings]: https://googleapis.github.io/gax-php/v1.26.1/Google/ApiCore/RetrySettings.html
+
+[ClientOptions]: https://googleapis.github.io/gax-php/v1.26.1/Google/ApiCore/Options/ClientOptions.html
+
+### Connection classes are not used anymore.
+
+This is a major change with this major version but one that we hope won't break any users. When the
+`SpannerClient` was created, behind the scenes a connection adapter was initialized.
+This connection object was then forwarded to any resource classes internally,
+like so:
+
+```php
+// This initialized a connection object
+$client = new SpannerClient();
+// This passed on the connection object to the Instance class
+$instance = $spanner->instance('my-instance');
+```
+
+As you can see the connection object was handled internally. If you used the library in this way,
+you will not need to make any changes. However, if you created the connection classes directly
+and passed it to the `Instance` class, this will break in Spanner `v2`:
+
+```php
+// Not intended
+$connObj = new Grpc([]);
+$instance = new Instance(
+    $connObj,
+    // other constructor options
+);
+```
+
+### `Google\Cloud\Spanner\Duration` class is not used anymore.
+We have removed the `Google\Cloud\Spanner\Duration` class from the library. Instead we will be using the `Google\Protobuf\Duration` class.
+
+### IAM class changes
+
+We have kept the functionality of `IAM` the same, however the underlying `IAM` class has changed.
+```php
+// In V1, this used to return an instance of Google\Cloud\Core\Iam\Iam
+$iam = $instance->iam();
+
+// In V2, this will return an instance of Google\Cloud\Core\Iam\IamManager
+$iam = $instance->iam();
+
+// Both the classes share the same functionality, so the following methods will work for both versions.
+$iam->policy();
+$iam->setPolicy();
+$iam->testIamPermissions();
+```
+
+### LongRunningOperation class changes
+
+We have kept the functionality of `LongRunningOperation` the same,
+however the underlying `LongRunningOperation` class has changed.
+```php
+// In V1, this used to return an instance of Google\Cloud\Core\LongRunning\LongRunningOperation.
+$lro = $instance->create($configuration);
+
+// In V2, this will return an instance of Google\ApiCore\OperationResponse.
+$lro = $instance->create($configuration);
+
+// Both the classes share the same functionality, so the following methods will work for both versions.
+$lro->name();
+$lro->done();
+$lro->state();
+$lro->result();
+$lro->error();
+$lro->info();
+$lro->reload();
+$lro->pollUntilComplete();
+$lro->cancel();
+$lro->delete();
+```