feat: Add support for apiEndpoint and deprecate serviceAddress client…

… configuration option. (#2206)

Datastore/src/V1/Gapic/DatastoreGapicClient.php

@@ -69,7 +69,7 @@
  * calls that map to API methods. Sample code to get started:
  *
  * ```
- * $datastoreClient = new DatastoreClient();
+ * $datastoreClient = new Google\Cloud\Datastore\V1\DatastoreClient();
  * try {
  *     $projectId = '';
  *     $keys = [];
@@ -117,7 +117,7 @@ private static function getClientDefaults()
     {
         return [
             'serviceName' => self::SERVICE_NAME,
-            'serviceAddress' => self::SERVICE_ADDRESS.':'.self::DEFAULT_SERVICE_PORT,
+            'apiEndpoint' => self::SERVICE_ADDRESS.':'.self::DEFAULT_SERVICE_PORT,
             'clientConfig' => __DIR__.'/../resources/datastore_client_config.json',
             'descriptorsConfigPath' => __DIR__.'/../resources/datastore_descriptor_config.php',
             'gcpApiConfigPath' => __DIR__.'/../resources/datastore_grpc_config.json',
@@ -139,6 +139,9 @@ private static function getClientDefaults()
      *                       Optional. Options for configuring the service API wrapper.
      *
      *     @type string $serviceAddress
+     *           **Deprecated**. This option will be removed in a future major release. Please
+     *           utilize the `$apiEndpoint` option instead.
+     *     @type string $apiEndpoint
      *           The address of the API remote host. May optionally include the port, formatted
      *           as "<uri>:<port>". Default 'datastore.googleapis.com:443'.
      *     @type string|array|FetchAuthTokenInterface|CredentialsWrapper $credentials
@@ -166,7 +169,7 @@ private static function getClientDefaults()
      *           or `grpc`. Defaults to `grpc` if gRPC support is detected on the system.
      *           *Advanced usage*: Additionally, it is possible to pass in an already instantiated
      *           {@see \Google\ApiCore\Transport\TransportInterface} object. Note that when this
-     *           object is provided, any settings in $transportConfig, and any $serviceAddress
+     *           object is provided, any settings in $transportConfig, and any `$apiEndpoint`
      *           setting, will be ignored.
      *     @type array $transportConfig
      *           Configuration options that will be used to construct the transport. Options for
@@ -195,7 +198,7 @@ public function __construct(array $options = [])
      *
      * Sample code:
      * ```
-     * $datastoreClient = new DatastoreClient();
+     * $datastoreClient = new Google\Cloud\Datastore\V1\DatastoreClient();
      * try {
      *     $projectId = '';
      *     $keys = [];
@@ -253,10 +256,10 @@ public function lookup($projectId, $keys, array $optionalArgs = [])
      *
      * Sample code:
      * ```
-     * $datastoreClient = new DatastoreClient();
+     * $datastoreClient = new Google\Cloud\Datastore\V1\DatastoreClient();
      * try {
      *     $projectId = '';
-     *     $partitionId = new PartitionId();
+     *     $partitionId = new Google\Cloud\Datastore\V1\PartitionId();
      *     $response = $datastoreClient->runQuery($projectId, $partitionId);
      * } finally {
      *     $datastoreClient->close();
@@ -324,7 +327,7 @@ public function runQuery($projectId, $partitionId, array $optionalArgs = [])
      *
      * Sample code:
      * ```
-     * $datastoreClient = new DatastoreClient();
+     * $datastoreClient = new Google\Cloud\Datastore\V1\DatastoreClient();
      * try {
      *     $projectId = '';
      *     $response = $datastoreClient->beginTransaction($projectId);
@@ -380,10 +383,10 @@ public function beginTransaction($projectId, array $optionalArgs = [])
      *
      * Sample code:
      * ```
-     * $datastoreClient = new DatastoreClient();
+     * $datastoreClient = new Google\Cloud\Datastore\V1\DatastoreClient();
      * try {
      *     $projectId = '';
-     *     $mode = CommitRequest\Mode::MODE_UNSPECIFIED;
+     *     $mode = Google\Cloud\Datastore\V1\CommitRequest\Mode::MODE_UNSPECIFIED;
      *     $mutations = [];
      *     $response = $datastoreClient->commit($projectId, $mode, $mutations);
      * } finally {
@@ -456,7 +459,7 @@ public function commit($projectId, $mode, $mutations, array $optionalArgs = [])
      *
      * Sample code:
      * ```
-     * $datastoreClient = new DatastoreClient();
+     * $datastoreClient = new Google\Cloud\Datastore\V1\DatastoreClient();
      * try {
      *     $projectId = '';
      *     $transaction = '';
@@ -511,7 +514,7 @@ public function rollback($projectId, $transaction, array $optionalArgs = [])
      *
      * Sample code:
      * ```
-     * $datastoreClient = new DatastoreClient();
+     * $datastoreClient = new Google\Cloud\Datastore\V1\DatastoreClient();
      * try {
      *     $projectId = '';
      *     $keys = [];
@@ -566,7 +569,7 @@ public function allocateIds($projectId, $keys, array $optionalArgs = [])
      *
      * Sample code:
      * ```
-     * $datastoreClient = new DatastoreClient();
+     * $datastoreClient = new Google\Cloud\Datastore\V1\DatastoreClient();
      * try {
      *     $projectId = '';
      *     $keys = [];

Datastore/synth.metadata

@@ -1,19 +1,19 @@
 {
-  "updateTime": "2019-04-02T17:30:33.020313Z",
+  "updateTime": "2019-08-07T20:02:45.410181Z",
   "sources": [
     {
       "generator": {
         "name": "artman",
-        "version": "0.16.22",
-        "dockerImage": "googleapis/artman@sha256:e7f9554322a8aa1416c122c918fdc4cdec8cfe816f027fc948dec0be7edef320"
+        "version": "0.29.1",
+        "dockerImage": "googleapis/artman@sha256:b2a73f4dda03ef8fcaa973e3ba26d0cf34091f6c22c70add663af325931aef4d"
       }
     },
     {
       "git": {
         "name": "googleapis",
         "remote": "https://github.com/googleapis/googleapis.git",
-        "sha": "0e86713beaaddfc48d73e016e3ff3ef6755e1d84",
-        "internalRef": "241554189"
+        "sha": "3a1b46a6668194a527e532a2c355b404c79b0e6a",
+        "internalRef": "262167956"
       }
     }
   ],

Datastore/synth.py

@@ -40,7 +40,7 @@
 s.move(library / 'tests/')
 
 # copy GPBMetadata file to metadata
-s.move(library / 'proto/src/GPBMetadata/Google/Cloud/Datastore', 'metadata/')
+s.move(library / 'proto/src/GPBMetadata/Google/Datastore', 'metadata/')
 
 # document and utilize apiEndpoint instead of serviceAddress
 s.replace(
@@ -73,84 +73,18 @@
     r'Copyright \d{4}',
     'Copyright 2018')
 
-# Use new namespace in the doc sample. See
-# https://github.com/googleapis/gapic-generator/issues/2141
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'(\@type|\@param) CommitRequest_',
-    r'\1 ')
-
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'CommitRequest_',
-    r'CommitRequest\\')
-
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'(\@type|\@param) CompositeFilter_',
-    r'\1 ')
-
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'CompositeFilter_',
-    r'CompositeFilter\\')
-
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'(\@type|\@param) EntityResult_',
-    r'\1 ')
-
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'EntityResult_',
-    r'EntityResult\\')
-
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'(\@type|\@param) Key_',
-    r'\1 ')
-
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'Key_',
-    r'Key\\')
-
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'(\@type|\@param) PropertyFilter_',
-    r'\1 ')
-
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'PropertyFilter_',
-    r'PropertyFilter\\')
-
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'(\@type|\@param) PropertyOrder_',
-    r'\1 ')
-
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'PropertyOrder_',
-    r'PropertyOrder\\')
-
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'(\@type|\@param) QueryResultBatch_',
-    r'\1 ')
-
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'QueryResultBatch_',
-    r'QueryResultBatch\\')
-
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'(\@type|\@param) ReadOptions_',
-    r'\1 ')
-
-s.replace(
-    'src/V1/Gapic/*.php',
-    r'ReadOptions_',
-    r'ReadOptions\\')
+# Fix class references in gapic samples
+for version in ['V1']:
+    pathExpr = 'src/' + version + '/Gapic/DatastoreGapicClient.php'
+
+    types = {
+        '= new DatastoreClient': r'= new Google\\Cloud\\Datastore\\' + version + r'\\DatastoreClient',
+        '= Mode::': r'= Google\\Cloud\\Datastore\\' + version + r'\\CommitRequest\\Mode::',
+        'new PartitionId': r'new Google\\Cloud\\Datastore\\' + version + r'\\PartitionId',
+    }
+
+    for search, replace in types.items():
+        s.replace(
+            pathExpr,
+            search,
+            replace)

Datastore/tests/Unit/V1/DatastoreClientTest.php

@@ -29,7 +29,7 @@
 use Google\ApiCore\Testing\MockTransport;
 use Google\Cloud\Datastore\V1\AllocateIdsResponse;
 use Google\Cloud\Datastore\V1\BeginTransactionResponse;
-use Google\Cloud\Datastore\V1\CommitRequest_Mode;
+use Google\Cloud\Datastore\V1\CommitRequest\Mode;
 use Google\Cloud\Datastore\V1\CommitResponse;
 use Google\Cloud\Datastore\V1\LookupResponse;
 use Google\Cloud\Datastore\V1\PartitionId;
@@ -54,15 +54,23 @@ private function createTransport($deserialize = null)
         return new MockTransport($deserialize);
     }
 
+    /**
+     * @return CredentialsWrapper
+     */
+    private function createCredentials()
+    {
+        return $this->getMockBuilder(CredentialsWrapper::class)
+            ->disableOriginalConstructor()
+            ->getMock();
+    }
+
     /**
      * @return DatastoreClient
      */
     private function createClient(array $options = [])
     {
         $options += [
-            'credentials' => $this->getMockBuilder(CredentialsWrapper::class)
-                ->disableOriginalConstructor()
-                ->getMock(),
+            'credentials' => $this->createCredentials(),
         ];
 
         return new DatastoreClient($options);
@@ -311,7 +319,7 @@ public function commitTest()
 
         // Mock request
         $projectId = 'projectId-1969970175';
-        $mode = CommitRequest_Mode::MODE_UNSPECIFIED;
+        $mode = Mode::MODE_UNSPECIFIED;
         $mutations = [];
 
         $response = $client->commit($projectId, $mode, $mutations);
@@ -359,7 +367,7 @@ public function commitExceptionTest()
 
         // Mock request
         $projectId = 'projectId-1969970175';
-        $mode = CommitRequest_Mode::MODE_UNSPECIFIED;
+        $mode = Mode::MODE_UNSPECIFIED;
         $mutations = [];
 
         try {