Enhance Commit API readability

.gitignore

@@ -17,3 +17,6 @@ keys/
 .testing
 .split
 __pycache__
+
+# VS Code local workspace settings
+.vscode

Core/src/Testing/DatastoreOperationRefreshTrait.php

@@ -17,9 +17,12 @@
 
 namespace Google\Cloud\Core\Testing;
 
-use Google\Cloud\Datastore\Connection\ConnectionInterface;
+use Google\ApiCore\Serializer;
+use Google\Cloud\Core\RequestHandler;
 use Google\Cloud\Datastore\EntityMapper;
 use Google\Cloud\Datastore\Operation;
+use Google\Cloud\Datastore\V1\Client\DatastoreClient;
+use Prophecy\Argument;
 
 /**
  * Refresh Datastore operation class
@@ -33,7 +36,7 @@ trait DatastoreOperationRefreshTrait
      * Refresh the operation property of a given stubbed class.
      *
      * @param mixed $stub
-     * @param ConnectionInterface $connection
+     * @param RequestHandler $requestHandler
      * @param array $options {
      *     Configuration Options
      *
@@ -43,7 +46,7 @@ trait DatastoreOperationRefreshTrait
      * }
      * @return mixed
      */
-    public function refreshOperation($stub, ConnectionInterface $connection, array $options = [])
+    public function refreshOperation($stub, RequestHandler $requestHandler, array $options = [])
     {
         $options += [
             'projectId' => null,
@@ -57,13 +60,87 @@ public function refreshOperation($stub, ConnectionInterface $connection, array $
             $options['returnInt64AsObject']
         );
 
+        $serializer = $this->getSerializer();
+
         $stub->___setProperty('operation', new Operation(
-            $connection,
+            $requestHandler,
+            $serializer,
             $options['projectId'],
             $options['returnInt64AsObject'],
             $mapper
         ));
 
         return $stub;
     }
+
+    /**
+     * Helper method for Unit and Snippet test classes. This mocks the
+     * $requestHandler class property present in the Test Class with
+     * given arguments.
+     *
+     * @param string $methodName The method name to mock in RequestHandler::sendRequest
+     * @param array<string, mixed> $params The parameters to look for in the
+     * array equivalent of rpc request.
+     * @param mixed $returnValue The value to be returned by sendRequest mock.
+     * @param null|int $shouldBeCalledTimes Adds a shouldBeCalled prophecy. Defaults to `null`, implying nothing is added.
+     * [
+     *      `0` => `shouldBeCalled`,
+     *      Non zero positive integer $x => `shouldBeCalledTimes($x)`
+     * ]
+     */
+    private function mockSendRequest($methodName, $params, $returnValue, $shouldBeCalledTimes = null)
+    {
+        $serializer = $this->getSerializer();
+
+        $prophecy = $this->requestHandler->sendRequest(
+            DatastoreClient::class,
+            $methodName,
+            Argument::that(function ($arg) use ($methodName, $params, $serializer) {
+                $requestName = ucfirst($methodName . 'Request');
+                $x = explode('\\', get_class($arg));
+                $argName = end($x);
+
+                if ($requestName != $argName) {
+                    return false;
+                }
+                $data = $serializer->encodeMessage($arg);
+                return array_replace_recursive($data, $params) == $data;
+            }),
+            Argument::cetera()
+        );
+
+        if (!is_null($shouldBeCalledTimes)) {
+            if ($shouldBeCalledTimes == 0) {
+                $prophecy->shouldBeCalled();
+            } else {
+                $prophecy->shouldBeCalledTimes($shouldBeCalledTimes);
+            }
+        }
+
+        $prophecy->willReturn($returnValue);
+    }
+
+    private function getSerializer()
+    {
+        if (isset($this->serializer)) {
+            return $this->serializer;
+        }
+
+        return new Serializer([], [
+            'google.protobuf.Value' => function ($v) {
+                return $this->flattenValue($v);
+            },
+            'google.protobuf.Timestamp' => function ($v) {
+                return $this->formatTimestampFromApi($v);
+            }
+        ], [], [
+            'google.protobuf.Timestamp' => function ($v) {
+                if (is_string($v)) {
+                    $dt = new \DateTime($v);
+                    return ['seconds' => $dt->format('U')];
+                }
+                return $v;
+            }
+        ]);
+    }
 }

Core/tests/Unit/ServiceBuilderTest.php

@@ -20,7 +20,6 @@
 use Google\Cloud\Core\ServiceBuilder;
 use Google\Cloud\Core\Testing\CheckForClassTrait;
 use Google\Cloud\Core\Testing\GrpcTestTrait;
-use Google\Cloud\Datastore\DatastoreClient;
 use Google\Cloud\Firestore\FirestoreClient;
 use Google\Cloud\Language\LanguageClient;
 use Google\Cloud\Logging\LoggingClient;
@@ -161,9 +160,6 @@ public function serviceProvider()
             [
                 'bigQuery',
                 BigQueryClient::class
-            ], [
-                'datastore',
-                DatastoreClient::class
             ], [
                 'firestore',
                 FirestoreClient::class,

Datastore/MIGRATION.md

@@ -0,0 +1,83 @@
+# Migrating Google Datastore from V1 to V2
+
+## How to upgrade
+
+Update your `google/cloud-datastore` dependency to `^2.0`:
+
+```
+{
+    "require": {
+        "google/cloud-datastore": "^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`
+- `credentialsFetcher` -> 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`
+- `defaultScopes` -> Moved to `credentialsConfig.defaultScopes`
+- `quotaProject` -> Moved to `credentialsConfig.quotaProject`
+- `httpHandler` -> Moved to `transportConfig.rest.httpHandler`
+- `authHttpHandler` -> Moved to `credentialsConfig.authHttpHandler`
+- `asyncHttpHandler` -> Removed in favour of a single httpHandler option.
+- `restOptions` -> Moved to `transportConfig.rest`
+- `grpcOptions` -> Moved to `transportConfig.grpc`
+- `accessToken` -> Removed
+- `shouldSignRequest` -> Removed
+- `preferNumericProjectId` -> Removed
+
+### Retry Options changes
+
+The retry options have been moved to use [`RetrySettings`][RetrySettings] in Client Options and in
+call options.
+
+- `retries` -> Renamed to `retrySettings.maxRetries`
+- `restRetryFunction` -> Renamed to `retrySettings.retryFunction`
+- `grpcRetryFunction` -> Renamed to `retrySettings.retryFunction`
+- `delayFunc`/`calcDelayFunction` -> Removed in favor of the properties
+  `retrySettings.initialRetryDelayMillis`, `retrySettings.retryDelayMultiplier` and
+  `retrySettings.maxRetryDelayMillis`.
+
+[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 most users. When one
+created a `DatastoreClient`, behind the scenes a connection adapter was initialized based on your
+transport preferences and then forwarded to operation class internally. This connection adapter was used
+to deliver requests internally:
+
+```php
+// This initialized a connection object and passed it internally to Operation class.
+$client = new DatastoreClient(['transport' => 'rest']);
+// This used the connection object internally to deliver the lookup request.
+$client->lookup($key);
+```
+
+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 Operation class, this will break in Datastore `v2`:
+
+```php
+// Not intended
+$connObj = new Rest([]);
+$operation = new Operation(
+    $connObj,
+    // other operation options
+);
+$operation->lookup($keys);
+```

Datastore/composer.json

@@ -5,7 +5,7 @@
     "minimum-stability": "stable",
     "require": {
         "php": "^8.0",
-        "google/cloud-core": "^1.52.7",
+        "google/cloud-core": "^1.59",
         "google/gax": "^1.30"
     },
     "require-dev": {