feat!: Spanner V2

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

@@ -49,7 +49,7 @@ jobs:
       - 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"}}}' -d Spanner
           composer update --prefer-dist --no-interaction --no-suggest -d Spanner/
 
       - name: Run system tests

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/LongRunning/LongRunningGapicConnection.php

@@ -0,0 +1,123 @@
+<?php
+/**
+ * Copyright 2016 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\Operation;
+use Google\LongRunning\ListOperationsRequest;
+use Google\LongRunning\GetOperationRequest;
+use Google\LongRunning\CancelOperationRequest;
+use Google\LongRunning\DeleteOperationRequest;
+use Google\Protobuf\Any;
+
+/**
+ * Defines the calls required to manage Long Running Operations using a GAPIC
+ * generated client.
+ *
+ * @internal
+ */
+class LongRunningGapicConnection 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

@@ -252,12 +252,11 @@ public function reload(array $options = [])
 
         $this->result = null;
         $this->error = null;
-        if (isset($res['done']) && $res['done']) {
+
+        if (isset($res['done']) && $res['done'] && 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/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/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/TimeTrait.php

@@ -92,10 +92,10 @@ private function formatTimeAsString(\DateTimeInterface $dateTime, $ns)
      *        $dateTime will be used instead.
      * @return array
      */
-    private function formatTimeAsArray(\DateTimeInterface $dateTime, $ns)
+    private function formatTimeAsArray(\DateTimeInterface $dateTime, $ns = null)
     {
         if ($ns === null) {
-            $ns = $dateTime->format('u');
+            $ns = $this->convertFractionToNanoSeconds($dateTime->format('u'));
         }
         return [
             'seconds' => (int) $dateTime->format('U'),

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,10 @@
 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 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();
+```